- Author Tests
- Installing Dependencies
- Coding style
This is the documentation for how to contribute to WWW::Mechanize::Chrome, shamelessly copied from Zilla::Dist::Contributing.
This Project is targeted to ship to CPAN and uses a plain
Makefile.PL setup to do that. This means that things are laid out mostly in the traditional way "normal" Perl module repositories look. The distribution directory looks like this at the top level:
A changelog history, formatted in a way that CPAN::Changes can read.
A short file with installation instructions.
Top level doc in a format for GitHub
A helper to run the test suite across a set of Chrome versions.
A Travis-CI instruction file for automatically running the test suite across OSX and Ubuntu and various versions of Perl.
A directory of Project examples.
Project library code.
Project test suite.
This module uses
git for development.
Installation for development is fairly straightforward:
- 1 Check out the repository
git clone https://github.com/Corion/WWW-Mechanize-Chrome.git
- 2 Install the prerequisites
cd WWW-Mechanize-Chrome cpanm --notest --installdeps .
The test suite can be run in two ways, depending on whether you want to run a matrix of combinations of backends and browser versions or not.
To run a single test during development of a new feature, run that test as follows:
perl -Ilib -w t/50-form2.t
To run the complete test suite, use
perl Makefile.PL make test
Alternatively, you can use the
perl Makefile.PL make prove -wl
perl Makefile.PL perl -w runtests.pl -t t/50-form2.t
The author tests live in
xt/ . These mostly cover problems that I encountered when engineering a release. These must pass before making a release.
There are no hard dependencies that need to be installed for development outside of the normal dependencies picked up by the CPAN installation process. Just run the following command in the
git checkout directory:
cpanm --installdeps .
The suggested environment for OSX is the Homebrew environment. This environment provides a
libpng libraries and Perl binary that are compatible with each other. Using the system
perl did not work out for me, as Imager::File::PNG does not install for the system
perl. If you do not use any of the screenshot features, you can also develop using the system
perl with a local::lib setup for the dependencies.
The development workflow described here is mostly geared towards Github. If you want to send your patches by mail or other means, they are still very welcome.
git checkout -b my-new-feature
The new feature ideally has at least one test file that exercises it. The new feature should have documentation. An entry in the
Changes file is welcome so your feature doesn't get lost in the mists of release engineering.
Ideally the new feature test you added passes on your machine.
Ideally the test suite passes without failure on your machine.
Not every commit is perfect, so here you get the chance to rewrite history a bit.
git rebase -i github/master
Note that even if you pushed your changes to Github already, it's still OK to rebase even published commits. That's why you do your development in a separate feature branch.
Please don't make such changes to the
git push github my-new-feature
Push the changes to Github to enable Travis CI to run the test suite across some other architectures and versions of Perl.
git rebase github/master git push github --force my-new-feature
Yes, this will ruin the "immutable" history of your branch. That's OK - a feature branch is allowed to have its history rewritten.
Opening the pull request will notify me, and Travis CI and AppVeyor will automatically run the test suite for the change.
If you don't want to use Github, you can use git to send the changes via mail:
git send-email --compose --to email@example.com
If you want to use a separate mail client, just format your changes as files and attach them to the mail manually:
git format-patch master..my-new-feature
Ideally your code mimics the existing style.
The important style points of this module are:
- Perl Version
Be compatible with Perl 5.10.
If you need features from a newer version of Perl, this should be discussed before you invest too much work in it.
- Use function signatures
Use the function signatures feature, as provided by Filter::signatures.
- Structure your code as testable units
Ideally, your code is not one huge method but a set of methods that can be tested in isolation.
- Strike a balance when introducing new dependencies
Ideally, your change only pulls in the bare dependencies necessary. If you think you need an object system, Moo is already there, so any module that relies on another object system should be avoided.