|
Packit |
a09cf7 |
# HOW TO CONTRIBUTE
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Thank you for considering contributing to this distribution. This file
|
|
Packit |
a09cf7 |
contains instructions that will help you work with the source code.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
The distribution is managed with [Dist::Zilla](https://metacpan.org/pod/Dist::Zilla).
|
|
Packit |
a09cf7 |
This means that many of the usual files you might expect are not in the
|
|
Packit |
a09cf7 |
repository, but are generated at release time. Some generated files are kept
|
|
Packit |
a09cf7 |
in the repository as a convenience (e.g. Build.PL/Makefile.PL and META.json).
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Generally, **you do not need Dist::Zilla to contribute patches**. You may need
|
|
Packit |
a09cf7 |
Dist::Zilla to create a tarball. See below for guidance.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
## Getting dependencies
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
If you have App::cpanminus 1.6 or later installed, you can use
|
|
Packit |
a09cf7 |
[cpanm](https://metacpan.org/pod/cpanm) to satisfy dependencies like this:
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
$ cpanm --installdeps --with-develop .
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
You can also run this command (or any other cpanm command) without installing
|
|
Packit |
a09cf7 |
App::cpanminus first, using the fatpacked `cpanm` script via curl or wget:
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
$ curl -L https://cpanmin.us | perl - --installdeps --with-develop .
|
|
Packit |
a09cf7 |
$ wget -qO - https://cpanmin.us | perl - --installdeps --with-develop .
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Otherwise, look for either a `cpanfile` or `META.json` file for a list of
|
|
Packit |
a09cf7 |
dependencies to satisfy.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
## Running tests
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
You can run tests directly using the `prove` tool:
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
$ prove -l
|
|
Packit |
a09cf7 |
$ prove -lv t/some_test_file.t
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
## Code style and tidying
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This distribution contains a `.perltidyrc` file in the root of the repository.
|
|
Packit |
a09cf7 |
Please install Perl::Tidy and use `perltidy` before submitting patches. However,
|
|
Packit |
a09cf7 |
as this is an old distribution and styling has changed somewhat over the years,
|
|
Packit |
a09cf7 |
please keep your tidying constrained to the portion of code or function in which
|
|
Packit |
a09cf7 |
you're patching.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
$ perltidy lib/HTTP/Status.pm -o my_tidy_copy.pm
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
The above command, for example, would provide you with a copy of `Status.pm`
|
|
Packit |
a09cf7 |
that has been cleaned according to our `.perltidyrc` settings. You'd then look
|
|
Packit |
a09cf7 |
at the newly created `my_tidy_copy.pm` in the dist root and replace your work
|
|
Packit |
a09cf7 |
with the cleaned up copy if there are differences.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This may seem like an arbitrary thing, but it is immensely helpful if all code
|
|
Packit |
a09cf7 |
is written in a singular style. If everything were tidy, it'd look like one
|
|
Packit |
a09cf7 |
single person wrote the code rather than a mish-mash.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
## Installing and using Dist::Zilla
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
[Dist::Zilla](https://metacpan.org/pod/Dist::Zilla) is a very powerful
|
|
Packit |
a09cf7 |
authoring tool, optimized for maintaining a large number of distributions with
|
|
Packit |
a09cf7 |
a high degree of automation, but it has a large dependency chain, a bit of a
|
|
Packit |
a09cf7 |
learning curve and requires a number of author-specific plugins.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
To install it from CPAN, I recommend one of the following approaches for the
|
|
Packit |
a09cf7 |
quickest installation:
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
# using CPAN.pm, but bypassing non-functional pod tests
|
|
Packit |
a09cf7 |
$ cpan TAP::Harness::Restricted
|
|
Packit |
a09cf7 |
$ PERL_MM_USE_DEFAULT=1 HARNESS_CLASS=TAP::Harness::Restricted cpan Dist::Zilla
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
# using cpanm, bypassing *all* tests
|
|
Packit |
a09cf7 |
$ cpanm -n Dist::Zilla
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
In either case, it's probably going to take about 10 minutes. Go for a walk,
|
|
Packit |
a09cf7 |
go get a cup of your favorite beverage, take a bathroom break, or whatever.
|
|
Packit |
a09cf7 |
When you get back, Dist::Zilla should be ready for you.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Then you need to install any plugins specific to this distribution:
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
$ dzil authordeps --missing | cpanm
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
You can use Dist::Zilla to install the distribution's dependencies if you
|
|
Packit |
a09cf7 |
haven't already installed them with cpanm:
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
$ dzil listdeps --missing --develop | cpanm
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Once everything is installed, here are some dzil commands you might try:
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
$ dzil build
|
|
Packit |
a09cf7 |
$ dzil test
|
|
Packit |
a09cf7 |
$ dzil regenerate
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
You can learn more about Dist::Zilla at http://dzil.org/
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
## Other notes
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This distribution maintains the generated `META.json` and either `Makefile.PL`
|
|
Packit |
a09cf7 |
or `Build.PL` in the repository. This allows two things:
|
|
Packit |
a09cf7 |
[Travis CI](https://travis-ci.org/) can build and test the distribution without
|
|
Packit |
a09cf7 |
requiring Dist::Zilla, and the distribution can be installed directly from
|
|
Packit |
a09cf7 |
Github or a local git repository using `cpanm` for testing (again, not
|
|
Packit |
a09cf7 |
requiring Dist::Zilla).
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
$ cpanm git://github.com/Author/Distribution-Name.git
|
|
Packit |
a09cf7 |
$ cd Distribution-Name; cpanm .
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Contributions are preferred in the form of a Github pull request. See
|
|
Packit |
a09cf7 |
[Using pull requests](https://help.github.com/articles/using-pull-requests/)
|
|
Packit |
a09cf7 |
for further information. You can use the Github issue tracker to report issues
|
|
Packit |
a09cf7 |
without an accompanying patch.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
# CREDITS
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This file was adapted from an initial `CONTRIBUTING.mkdn` file from David
|
|
Packit |
a09cf7 |
Golden under the terms of the [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/), with inspiration from the
|
|
Packit |
a09cf7 |
contributing documents from [Dist::Zilla::Plugin::Author::KENTNL::CONTRIBUTING](https://metacpan.org/pod/Dist::Zilla::Plugin::Author::KENTNL::CONTRIBUTING)
|
|
Packit |
a09cf7 |
and [Dist::Zilla::PluginBundle::Author::ETHER](https://metacpan.org/pod/Dist::Zilla::PluginBundle::Author::ETHER).
|