@@ -4,8 +4,23 @@ Thank you for considering contributing to this distribution. This file
44contains instructions that will help you work with the source code.
55
66The distribution is managed with Dist::Zilla. This means than many of the
7- usual files you might expect are not in the repository, but are generated
8- at release time (e.g. Makefile.PL).
7+ usual files you might expect are not in the repository, but are generated at
8+ release time (e.g. Makefile.PL).
9+
10+ Generally, **you do not need Dist::Zilla to contribute patches**. You do need
11+ Dist::Zilla to create a tarball and/or install from the repository. See below
12+ for guidance.
13+
14+ ### Acceptable contributions
15+
16+ HTTP::Tiny is considered nearly feature-complete. The only features likely to
17+ be added are those that improve compliance with RFC 2616. If you have ideas
18+ for other features, please look at
19+ [HTTP::Tiny::UA](http://p3rl.org/HTTP::Tiny::UA/) and consider adding your
20+ feature there.
21+
22+ Bug fixes and performance improvements that do not bloat the code will be
23+ considered for inclusion.
924
1025### Getting dependencies
1126
@@ -27,35 +42,51 @@ You can run tests directly using the `prove` tool:
2742 $ prove -l
2843 $ prove -lv t/some_test_file.t
2944
30- For most distributions, `prove` is entirely sufficent for you to test any
31- patches you have.
45+ For most of my distributions, `prove` is entirely sufficient for you to test any
46+ patches you have. I use `prove` for 99% of my testing during development.
3247
3348### Code style and tidying
3449
35- Please try to match any existing coding style. If there is a `.perltidyrc`
36- file, please install Perl::Tidy and use perltidy before submitting patches.
37-
38- If there is a `tidyall.ini` file, you can also install Code::TidyAll and run
39- `tidyall` on a file or `tidyall -a` to tidy all files.
50+ Please try to match any existing coding style.
4051
4152### Patching documentation
4253
4354Much of the documentation Pod is generated at release time.
44- Depending on the distribution, some documentation may be written in a Pod
45- dialect called WikiDoc. (See Pod::WikiDoc on CPAN.)
4655
4756If you would like to submit a documentation edit, please limit yourself to the
4857documentation you see.
4958
5059If you see typos or documentation issues in the generated docs, please
5160email or open a bug ticket instead of patching.
5261
53- ### Learning Dist::Zilla
62+ ### Installing from the repository
63+
64+ If you want to install directly from the repository, you need to have
65+ Dist::Zilla installed (see below). If this is a burden to you, I welcome
66+ patches against a CPAN tarball instead of the repository.
67+
68+ ### Installing and using Dist::Zilla
5469
55- Dist::Zilla is a very powerful authoring tool, but requires a number of
56- author-specific plugins. If you would like to use it for contributing,
57- install it from CPAN, then run one of the following commands, depending on
58- your CPAN client:
70+ Dist::Zilla is a very powerful authoring tool, optimized for maintaining a
71+ large number of distributions with a high degree of automation, but it has a
72+ large dependency chain, a bit of a learning curve and requires a number of
73+ author-specific plugins.
74+
75+ To install it from CPAN, I recommend one of the following approaches for
76+ the quickest installation:
77+
78+ # using CPAN.pm, but bypassing non-functional pod tests
79+ $ cpan TAP::Harness::Restricted
80+ $ PERL_MM_USE_DEFAULT=1 HARNESS_CLASS=TAP::Harness::Restricted cpan Dist::Zilla
81+
82+ # using cpanm, bypassing *all* tests
83+ $ cpanm -n Dist::Zilla
84+
85+ In either case, it's probably going to take about 10 minutes. Go for a walk,
86+ go get a cup of your favorite beverage, take a bathroom break, or whatever.
87+ When you get back, Dist::Zilla should be ready for you.
88+
89+ Then you need to install any plugins specific to this distribution:
5990
6091 $ cpan `dzil authordeps`
6192 $ dzil authordeps | cpanm
@@ -66,5 +97,9 @@ Once installed, here are some dzil commands you might try:
6697 $ dzil test
6798 $ dzil xtest
6899
100+ To install from the repository, use:
101+
102+ $ dzil install
103+
69104You can learn more about Dist::Zilla at http://dzil.org/
70105
0 commit comments