How to contribute code

This guide explains how to contribute code to a Nasqueron project.

We use Phabricator for tasks and code reviews, our instance is called DevCentral and is accessible at https://devcentral.nasqueron.org.

In a nutshell, to submit a change, you need to clone the relevant repository, create a new branch, commit and send this commit to our code review server. Pull requests on GitHub could be fine for trivial hit and run patches, but if you add a new feature, use our code review server.

Clone the repository

On DevCentral, go to Diffusion. Each repository will offer you a clone command.

For example, it could be:

git clone ssh://git@github.com/nasqueron/someproject

Internal projects are directly hosted on DevCentral. In this case, you need to add your SSH key to the settings.

If the repository is on GitHub but not on DevCentral, please request it to be added. For that, create a task on DevCentral and add DevCentral as project You can use the priority Unbreak now! if you already have a change to review, high if you plan to do it in the next 12 hours, normal for 24 hours, low for one week.

Code something

Never work in Git master branch, when you are submitting new code.

Always create a new branch for each change, code feature or bug fix.

The master branch is only to merge changes, not to work.

Trust us, you want to code and have fun, not to spend an evening to fix your Git repositories merging infinite conflicts.

To fix a bug, or code a new feature, three operations are needed:

1. code it
2. commit it
3. review it

Code it

Before to start to code, create a new branch:

git checkout -b feature/something-awesome

If you fix a bug, use the number of the bug on DevCentral:

git checkout -b bug/T434

Then code something, test it, reread it.

Commit it

When you're ready, you can commit it.

Your commit message should use the following format:

• a title, as short as possible, with 43 max characters recommended, 55 characters as soft limit, 72 as hard limit
• some paragraphs, but wrap lines < 72 characters. You can extend at 80 (soft limit) or 100 (hard limit) if really needed.

Review it

arc diff

This will send your change on DevCentral, and allow the review process to start.

When you use `arc diff`, Arcanist will try to guess what change you want to offer. If you've committed in a branch, it will guess correctly you want to submit the diff between master and this branch (your commit).

You'll find more information about this on the Phabricator documentation.

Once reviewed, your change will be live in the master repository. Cheers!

You can now go on to code

Meanwhile review, you can go to another branch and go on to work.

If this change is independent, your new branch must start at master, not at your previous branch:

git checkout master
git checkout -b feature/another-awesome-change

But when your change depends of the previous one, you create a new branch from the last:

git checkout -b feature/the-next-change

Then again, code, commit, and send to review with arc diff.

Review code

Reviews are accessible at Differential.

In the bottom of a revision page, you'll find a action menu to accept a revision or request changes.

You can also comment inline, clicking on line numbers.

Everyone can offer comment.

To definitively accept the review, if your project has guidelines, follow them.

If not, any member considering themself a member of the project can accept any review from another project member.

You shouldn't self review.

Useful links

• http://www.unixwiz.net/techtips/ssh-agent-forwarding.html