Patch Submission

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:

1. Fork the repository http://github.com/LibreCat/Catmandu (click "Fork")

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

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

3. 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 official dev branch. That way, if you have more or less commits than the upstream repo, you'll be immediately notified by git.

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

5. 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.

6. Send a pull request via the GitHub interface. Make sure your pull request is based on the 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.

   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.

7. If your pull-request is merged into dev, then all you have to do is to remove your local and remote pr/$name branch:

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

8. 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!