Contributing to Logilab's free softwares

Getting started

First of all you should now a bit about mercurial and its mq extension that you'll have to activate.

Then clone the project's patches repository and make sure we have read access to it. For example, you can fork it on bitbucket and make it public.

When you have something ready, tell the list and we will pull from your repository to get your patches into the code review system available on our public forges.

Using the code review system, you will get feedback and iterate until your patches are ok and get integrated into the main repository.

Writing proper patches

Beside clean, tested and documented code of course ;), a good start is to follow the points below:

• patch names should end with the .diff extension (makes it easier to detect the parser to colorize them in the web ui)
• add a ticket in the tracker describing the bug or enhancement
• set a commit message using -m or -e option of hg qnew/qrecord/qref
• this commit message should include a reference to the ticket it concerns, for example 'closes #1234' where 1234 is the number of the ticket
• if the project has a ChangeLog file, update it in your patch

Including the ticket number in the commit message will automaticaly link the patch to the ticket and close the ticket when the patch is applied.

All of this greatly helps traceability.

Using the review system

Patches are accessible through the 'patches' tab of a project. Patches have a state in the tracker. They can be in-progress, pending review, reviewed or applied (or rejected or...). By default patches that were applied or rejected are not shown.

When you send a pull request, someone with write access to the main patch repository will get your patches in. You can ask for review of a patch using the web ui or by having "<the name of your patch> ready for review" in the commit message of the patches repository (I know having two repository makes things harder to grasp ;). More on those magic words on https://www.logilab.org/doc/vcreview_dailyuse, though you should need almost only that one.

So now we have a workflow around your patches:

• you can ask for review of a patch
• we can discuss using comments/tasks that may be added on the patch and/or its revisions
• we can apply the patch, or ask for rework

The discussion should be around the patch instead of on the list.

Do not hesitate to ask or comment or tell about things you think you should be able to do but you can't. We use this review system for all our daily work, but there may be bugs or configuration problems for external contributors that we will try to fix quickly.

FAQ