Nicolas Steenlant > Catmandu-0.8011 > lib/Catmandu/Development.pod

Download:
Catmandu-0.8011.tar.gz

Annotate this POD

Website

View/Report Bugs
Source   Latest Release: Catmandu-0.8014

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.

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!

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, rating us on cpanratings.perl.org, explaining what you like about Catmandu is another very valuable contribution that helps other new users find us!

Mailing list

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

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").

Code

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

GENERAL DEVELOPMENT GUIDELINES ^

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

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.

Quality Supervision

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

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

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

Reporting Bugs

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

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

ENVIRONMENT AND PATCH SUBMISSION ^

Set up a development environment

If you want to submit a patch for Catmandu, you need git and very likely also Module::Build. We also recommend perlbrew (see below) to test and develop Catmandu on a recent version of perl. We also suggest 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 Catmandu. Please also see the documentation that comes with these tools for more info.

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 (--as option), as well as compiling without the tests (--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

Install dependencies (required)

Install Module::Build

    $ cpanm Module::Build

Get Catmandu sources

Get the Catmandu 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

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 dev branch rather than on their 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 dev branch.)

Here is the workflow for submitting a patch:

RESOURCES FOR DEVELOPERS ^

Website

The official website is here: http://librecat.org/

Mailing Lists

A mailing list is available here: librecat-dev@mail.librecat.org

Repositories

The official repository is hosted on GitHub at the following location: http://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 Patch submission section.

Acknowledgement ^

This guide is heavily based on Dancer2::Development.

syntax highlighting: