package Catmandu::Development;

=head1 DESCRIPTION

This guide has been written to help anyone interested in contributing to the
development of Catmandu.

Please read this guide before contributing to Catmandu or related projects, to avoid wasted effort and
maximizing the chances of your contributions being used.


=head1 WAYS TO CONTRIBUTE

There are many ways to contribute to the project. Catmandu is a young yet active
project and any kind of help is very much appreciated!

=head2 Publicity

You don't have to start by hacking the code, spreading the word is very
valuable as well!

If you have a blog, just feel free to speak about Catmandu.

Of course, it doesn't have to be limited to blogs or Twitter.
Feel free to spread the word in whatever way you consider fit and drop us a
line on the Catmandu user mailing list noted below.

Also, if you're using and enjoying Catmandu,
L<rating us on cpanratings.perl.org|http://cpanratings.perl.org/dist/Catmandu>,
explaining what you like about Catmandu is another very valuable contribution that
helps other new users find us!

=head2 Mailing list

Subscribing to the mailing list and providing assistance to new users is incredibly valuable.

=over 4

=item *

Mailing list: L<librecat-dev@listservice.lub.lu.se> to
subscribe or view archives

=back

=head2 Documentation

We value documentation very much, but it's difficult to keep it up-to-date.
If you find a typo or an error in the documentation please do let us know -
ideally by submitting a patch (pull request) with your fix or suggestion 
(see "Patch Submission").

=head2 Contribute to CPAN Testers

If you have access to perl on rare operating systems, please
consider contributing tests. See
L<http://wiki.cpantesters.org/wiki/TestDuringInstall> for more information.

=head2 Code

You can write extensions (plugins) for Catmandu extending core functionality or
contribute to Catmandu's core code, see "Patch Submission" below.

=head1 GENERAL DEVELOPMENT GUIDELINES

This section lists high-level recommendations for developing Catmandu, for more
detailed guidelines, see "Coding Guidelines" below.

=head2 Quality Assurance

Catmandu should be able to install for all Perl versions since 5.10.1, on any
platform for which Perl exists. We focus mainly on GNU/Linux (any distribution).

You should avoid regressions as much as possible and keep backwards
compatibility in mind when refactoring. Stable releases should not break
functionality and new releases should provide an upgrade path and upgrade tips
such as warning the user about deprecated functionality.

=head2 Quality Supervision

We can measure our quality using the CPAN testers platform:
L<http://www.cpantesters.org>.

A good way to help the project is to find a failing build log on the CPAN
testers: L<http://www.cpantesters.org/distro/D/Catmandu.html>

If you find a failing test report, feel free to report it as a GitHub issue:
L<http://github.com/LibreCat/Catmandu/issues>.

=head2 Reporting Bugs

We prefer to have all our bug reports on GitHub, in the issues section:
L<http://github.com/PerlDancer/Catmandu/issues>.

Please make sure the bug you're reporting does not yet exist.

=head1 ENVIRONMENT AND PATCH SUBMISSION

=head2 Set up a development environment

If you want to submit a patch for Catmandu, you need git and very likely also 
L<Dist::Zilla>. We also recommend perlbrew (see below) to test and develop Catmandu on a recent version of perl. We also
suggest L<App::cpanminus>) to quickly and comfortably install perl modules under perlbrew.

In the following sections we provide tips for the installation of some of these 
tools together with Dancer. Please also see the documentation that comes with 
these tools for more info.

=head3 Perlbrew tips (Optional)

Install perlbrew for example with 
    
    cpanm App::perlbrew

Check which perls are available

    perlbrew available

At the time of writing it looks like this

  perl-5.18.0
  perl-5.16.3
  perl-5.14.4
  perl-5.12.5
  perl-5.10.1
  perl-5.8.9
  perl-5.6.2
  perl5.005_04
  perl5.004_05
  perl5.003_07

Then go on and install a version inside Perlbrew. I recommend you give a name
to the installation (C<--as> option), as well as compiling without the tests
(C<--n> option) to speed it up.

  perlbrew install -n perl-5.16.3 --as catmandu_dev -j 3

Wait a while, and it should be done. Switch to your new Perl with:

  perlbrew switch catmandu_dev

Now you are using the fresh Perl, you can check it with:

  which perl

Install cpanm on your brewed version of perl.

  perlbrew install-cpanm


=head2 Install various dependencies (required)

Install Module::Build

    $ cpanm Module::Build


=head2 Get Catmandu sources

Get the Dancer sources from github (for a more complete git workflow see 
below):

Clone your fork to have a local copy using the following command:

    $ git clone git@github.com:LibreCat/Catmandu.git

The installation is then straight forward:

    $ cd Catmandu
    $ perl Build.PL
    $ ./Build
    $ ./Build test
    $ ./Build install

=head2 Patch Submission (Github workflow)

The Catmandu development team uses GitHub to collaborate.  We greatly appreciate
contributions submitted via GitHub, as it makes tracking these contributions and
applying them much, much easier. This gives your contribution a much better
chance of being integrated into Catmandu quickly!

To help us achieve high-quality, stable releases, git-flow workflow is used to
handle pull-requests, that means contributors must work on their C<devel> branch
rather than on their C<master>.  (Master should be touched only by the core dev
team when preparing a release to CPAN; all ongoing development happens in
branches which are merged to the C<devel> branch.)

Here is the workflow for submitting a patch:

=over 4

=item *

Fork the repository L<http://github.com/PerlDancer/Catmandu> (click "Fork")

=item *

Clone your fork to have a local copy using the following command:

    $ git clone git://github.com/myname/Catmandu.git

=item *

As a contributor, you should B<always> work on the C<devel> branch of
your clone (C<master> is used only for building releases).

    $ git remote add upstream https://github.com/LibreCat/Catmandu.git
    $ git fetch upstream
    $ git checkout -b devel upstream/devel

This will create a local branch in your clone named C<devel> and that
will track the official C<devel> branch. That way, if you have more or
less commits than the upstream repo, you'll be immediately notified by git.

=item *

You want to isolate all your commits in a I<topic> branch, this will make the
reviewing much easier for the core team and will allow you to continue working
on your clone without worrying about different commits mixing together.

To do that, first create a local branch to build your pull request:

    # you should be in devel here
    git checkout -b pr/$name

Now you have created a local branch named I<pr/$name> where I<$name> is the
name you want (it should describe the purpose of the pull request you're
preparing).

In that branch, do all the commits you need (the more the better) and when
done, push the branch to your fork:

    # ... commits ...
    git push origin pr/$name

You are now ready to send a pull request.

=item *

Send a I<pull request> via the GitHub interface. Make sure your pull request is
based on the I<pr/$name> branch you've just pushed, so that it incorporates the
appropriate commits only.

It's also a good idea to summarize your work in a report sent to the users
mailing list (see below), in order to make sure the team is aware of it.

=item *

When the core team reviews your pull request, it will either accept (and
then merge into I<devel>) or refuse your request.

If it's refused, try to understand the reasons explained by the team for
the denial. Most of the time, communicating with the core team is enough to
understand what the mistake was. Above all, please don't be offended.

If your pull-request is merged into I<devel>, then all you have to do is to
remove your local and remote I<pr/$name> branch:

    git checkout devel
    git branch -D pr/$name
    git push origin :pr/$name

And then, of course, you need to sync your local devel branch with the upstream:

    git pull upstream devel
    git push origin devel

You're now ready to start working on a new pull request!

=back

=head1 RESOURCES FOR DEVELOPERS

=head2 Website

The official website is here:
L<http://librecat.org/>

=head2 Mailing Lists

A mailing list is available here:
L<librecat-dev@listservice.lub.lu.se>

=head2 Repositories

The official repository is hosted on GitHub at the following location:
L<git@github.com:LibreCat/Catmandu>

Official developers have write access to this repository, contributors are
invited to fork it if they want to submit patches, as explained in the
I<Patch submission> section.

=head1 Disclaimer

This guide is heavily based on L<Dancer2::Development>.

=cut