/ 
WWW-Mechanize-Chrome-0.73
River stage one • 4 direct dependents • 4 total dependents
/ WWW::Mechanize::Chrome::Contributing

WWW::Mechanize::Chrome::Contributing

Welcome!

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:

Changes

A changelog history, formatted in a way that CPAN::Changes can read.

Contributing

This file

README

A short file with installation instructions.

README.mkdn

Top level doc in a format for GitHub

runtests.pl

A helper to run the test suite across a set of Chrome versions.

.travis.yml

A Travis-CI instruction file for automatically running the test suite across OSX and Ubuntu and various versions of Perl.

examples/

A directory of Project examples.

lib/

Project library code.

t/

Project test suite.

Development

This module uses git for development.

Installation

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 .

Testing

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.

Running a single test

To run a single test during development of a new feature, run that test as follows:

perl -Ilib -w t/50-form2.t

Running the complete test suite

To run the complete test suite, use make / gmake:

perl Makefile.PL
make test

Alternatively, you can use the prove tool:

perl Makefile.PL
make
prove -wl

Running tests with different transport backends

To run a test program with the different backends, Mojolicious, AnyEvent and IO::Async, use the runtests.pl program:

perl Makefile.PL
perl -w runtests.pl -t t/50-form2.t

Author Tests

The author tests live in xt/ . These mostly cover problems that I encountered when engineering a release. These must pass before making a release.

Installing Dependencies

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 .

OSX

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.

Workflow

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.

Create a new branch

git checkout -b my-new-feature

Develop the 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.

Run the new feature test

Ideally the new feature test you added passes on your machine.

Run the test suite

Ideally the test suite passes without failure on your machine.

Rebase your changes to clean up your commit history

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 master branch.

Push the changes to Github

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.

Rebase your changes to the master branch

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.

Open a Github pull request

Opening the pull request will notify me, and Travis CI and AppVeyor will automatically run the test suite for the change.

Send a change set via mail

If you don't want to use Github, you can use git to send the changes via mail:

git send-email --compose --to corion@cpan.org

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

Coding style

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.