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.
Remember: One new change, one new branch.
To fix a bug, or code a new feature, three operations are needed:
- code it
- commit it
- 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!
Edit a change
To edit the change, amend the relevant commit.
git checkout <the relevant branch> [change something] git commit --amend arc diff
If arc complain, try:
arc diff --update <differential id without D prefix>
You can also use the web interface: Differential allows you to submit a patch to amend your change.
In this case, you edit the files, run `git diff` and copy/paste the result on Phabricator.
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.
