View source for 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 {{PhabricatorInstance}}.

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 [{{PhabricatorInstance}}/diffusion/ Diffusion]. Each repository will offer you a clone command.

For example, it could be:
  git clone ssh://vcs@devcentral.nasqueron.org:5022/someproject

Most projects are directly hosted on DevCentral. In this case, you need to [{{PhabricatorInstance}}/settings/panel/ssh/ 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.

If you want to edit a Keruald library, clone the monorepo and not directly the read-only repo of the library. This is intended to ease development across dependent libraries.

=== Don't forget the dependencies ===

For PHP and Node.JS projects, don't forget to require dependencies :

    $ composer install
    $ yarn install

For Python, you probably want a virtual environment for the project :

    $ python3 -m venv $HOME/dev/python/awesomeproject
    $ source $HOME/dev/python/awesomeproject/bin/activate
    $ pip install -r requirements.php

For Rust projects, the first Cargo build will take care of it.

For C project, `make` should also take care of it.

== Code something ==
<div style="display: table; margin: 1em; padding: 0.5em 1.5em; border: 4px solid #aaa; background-color: #f9f9f9;">
'''Never work in Git main branch''', when you are submitting new code.

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

The main 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.'''
</div>

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 switch -c feature/something-awesome

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

 git switch -c 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.

The title should be at imperative, not followed by a final dot.

The paragraphs should focus to explain why this change is needed.

See http://chris.beams.io/posts/git-commit/ for more best practices.

=== 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 main and this branch (your commit).

You'll find more information about this on [https://secure.phabricator.com/book/phabricator/article/arcanist_diff/ the Phabricator documentation].

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

=== Edit a change ===

To edit the change, amend the relevant commit.

  git checkout <the relevant branch>
  [change something]
  git add <the files modified>
  git commit --amend
  arc diff

If arc complain, try to explicitly give the commit range <code>HEAD^</code> to select the latest commit and the differential ID:

  arc diff HEAD^ --update <differential id with 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 main, not at your previous branch:

 git checkout main
 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 ==

=== Where are reviews and what can I do there? ===

Reviews are accessible at [{{PhabricatorInstance}}/differential 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.

=== Accept a revision ===
<div style="display: table; margin: 1em; padding: 0.5em 1.5em; border: 4px solid #aaa; background-color: #f9f9f9;">
'''Don't self review''', ie don't accept your own revisions.

Consider to '''land accepted revisions immediately'''.
</div>

==== What does that mean? ====

An accepted revision is a revision ready to be integrated into the code base (the goal of the CI process), and so to be sent to production environment.

Some projects trigger automatically a new deployment step after a commit has been integrated, for example the Docker images are all configured to rebuild a new image from the latest tag. Websites like https://docker.nasqueron.org/ or https://assets.nasqueron.org/ are also automatically updated.

By accepting a revision, you express your confidence it's ready and sounds safe to deploy.

Does your project have special guidelines for code review?
* If so, follow them.
* If not, any member considering themself a member of the project can accept any revision from another project member.

Next step is to land the accepted revision. This currently requires <code>arc land</code>, but we're working to allow to land from the web UI.

==== Merge the revision to main ====
In Phabricator language, that's called ''land the revision''.

# Use a clean and up-to-date main: <code>git fetch && git checkout main && git reset --hard origin/main</code>
# Get the patch: <code>arc patch D300</code>
# Merge the patch to main: <code>arc land</code>

The differential UI gives the next step in the header.

==== After the merge ====

Stay reachable and watch the post commit actions (e.g. does the Docker image has been successfully built on Docker Hub?). Be ready to use <code>git revert</code> to revert the change if something is wrong.

=== When can I self review? ===

Self review is frowned upon, but in two cases it could be needed:
* when there is an emergency, for example to fix a security issue, when no one in duty can be found;
* when you're alone on your project, and can't find someone to review.

=== How to revert a change? ===

A change revert is a commit:
* you can automatically create by <code>git revert <commit-ish></code>
* you craft manually, like any other change

Then, you follow the exact same instructions you would for a regular change: send to the code review, review it, land it.

The revision should be accepted by:
* the original commit author if present at deployment time
* someone you work with to solve currently the issue if the author isn't there
* yourself if you're alone

The review should contain a comment about what is broken in the reverted commit, excepted if there is already such information in Audit or Differential.

== Troubleshoot Arcanist ==
=== Install Arcanist like on Nasqueron devserver role ===

If you wish to reproduce the setup we use on our development servers in your local machine, you can clone our maintained version of Arcanist and shellcheck-linter:

‎<syntaxhighlight lang="shell">
$ mkdir /opt/phabricator
$ cd /opt/phabricator

$ git clone https://devcentral.nasqueron.org/source/shellcheck-linter.git

$ git clone https://github.com/nasqueron/arcanist.git
$ cd arcanist
$ git checkout production
$ ln -s /opt/phabricator/arcanist/bin/arc /usr/local/bin/arc
</syntaxhighlight>

=== Use Nasqueron maintained patches ===
If you wish to get upstream + a patch to use by default main and not master branch name + PHPUnit support
you can clone the '''production''' branch at https:/github.com/nasqueron/arcanist (it's the default branch).

=== PHPUnit7+ support ===
You can apply [https://secure.phabricator.com/P2084 this patch] to get a working Arcanist on the upstream version:

‎<syntaxhighlight lang="shell">
$ file `which arc`
$ cd /path/to/arcanist
$ arc install-certificate
$ arc paste P2084 | patch -p1
‎</syntaxhighlight>

On Debian, the path to Arcanist is <code>/usr/share/arcanist</code> when installed through a package.

If you wish to maintain it against last Arcanist release:
‎<syntaxhighlight lang="shell">
$ git checkout -b production
$ git commit -a -m "Support PHPUnit 7+"
‎</syntaxhighlight>

=== arc lint ===
If `arc lint` complains about a missing executable you can have a message like this:

    Error in parsing '.arclint' file, in key 'bin' for linter 'phpcs'.

Look in .arclint what's expected. In this case, it's the PHP dependencies from Composer / Packagist.

    $ composer install

=== arc patch changed the commit date ===

You can recover the unix timestamp of the change from the devcentral_differential database with the correct HH:MM:SS expected granularity. For example for D1656:

    $ bin/storage shell
    SELECT min(dateCreated) FROM devcentral_differential.differential_diff WHERE revisionID = 1656;

Then, inject that timestamp to git: <code>git commit --amend --date=1535846555</code>

== Useful links ==
* http://www.unixwiz.net/techtips/ssh-agent-forwarding.html
* http://chris.beams.io/posts/git-commit/
* https://devcentral.nasqueron.org/w/setup_2fa/

[[Category:Reference]]
[[Category:Contributor guide]]
[[Category:Internship guide]]