-
Notifications
You must be signed in to change notification settings - Fork 31
Contribution
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.
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!
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!
Subscribing to the mailing list and providing assistance to new users is incredibly valuable.
- Mailing list:
librecat-dev@mail.librecat.org
- Subscribe or view archives here: http://mail.librecat.org/mailman/listinfo/librecat-dev
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").
To contribute to Catmandu's core code, see "Patch Submission" below. You can also extend the functionality by new Importers, Exporters, Stores, Fix packages, Validators, Binds, or Plugins. Have a look at the list of missing modules for existing ideas and resources for new Catmandu modules. Feel also free to add new ideas and links there.
This section lists high-level recommendations for developing Catmandu, for more detailed guidelines, see "Coding Guidelines" below.
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.
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 or another kind of bug, feel free to report it as a GitHub issue: http://github.com/LibreCat/Catmandu/issues. Please make sure the bug you're reporting does not yet exist.
If you want to submit a patch for Catmandu, you need git and very likely also milla (Dist::Milla). 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.
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
this section needs to be rewritten to reflect the change to Dist::Milla
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
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:
-
Fork the repository http://github.com/LibreCat/Catmandu (click "Fork")
-
Clone your fork to have a local copy using the following command:
$ git clone git://github.com/$myname/Catmandu.git
-
As a contributor, you should always work on the
dev
branch of your clone (master
is used only for building releases).$ git remote add upstream https://github.com/LibreCat/Catmandu.git $ git fetch upstream $ git checkout -b dev upstream/dev
This will create a local branch in your clone named
dev
and that will track the officialdev
branch. That way, if you have more or less commits than the upstream repo, you'll be immediately notified by git. -
You want to isolate all your commits in a
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 dev branch here git checkout -b pr/$name
Now you have created a local branch named
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.
-
Send a
pull request
via the GitHub interface. Make sure your pull request is based on thepr/$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.
When the core team reviews your pull request, it will either accept (and then merge into
dev
) 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
dev
, then all you have to do is to remove your local and remotepr/$name
branch:git checkout dev git branch -D pr/$name git push origin :pr/$name
-
And then, of course, you need to sync your local dev branch with the upstream:
git pull upstream dev git push origin dev
You're now ready to start working on a new pull request!
The official website is here: http://librecat.org/
A mailing list is available here: librecat-dev@mail.librecat.org
The official repository is hosted on GitHub at http://github.com:LibreCat/Catmandu.
Official developers have write access to this repository, contributors are invited to fork the dev branch (!) and submit a pull request.
This guide is heavily based on Dancer2::Development.