The process for contributing code to Apertis is the same as for many other open source projects: check out the code, make changes locally, then submit them for review and merging. Apertis uses its GitLab instance as a code repository and review tool.

This guide assumes good working knowledge of git (see Version control for specific guidelines) and an account with commit rights on GitLab (see Getting commit rights for guidance).

Fork the repository to private namespace

Before commencing any work, the developer should fork the repository into their namespace

Clone

Clone the forked repository

  • Check out the git repository:

    git clone https://gitlab.apertis.org/[group name]/[repository name].git
    
  • Commit the changes (see the guidelines for making commits ), test them and check you are allowed to submit them under the project’s license, following the sign-offs documentation

    git commit -i -s
    
  • Every commit must have an appropriate Signed-off-by: tag in the commit message.

  • Add a Fixes: APERTIS-<task_id> tag for each task in the proposed commit messages (as explained in the section “Automatically closing tasks” below or in the envelope message of the merge request itself) in order to link the merge request to one or more tasks in Phabricator.

  • Note: The tag will ensure that Phabricator tasks are kept up-to-date with regard to the status of related merge requests, through the creation of a new comment with the link to the merge request every time a merge request is created/updated/merged. This syntax has been chosen for the tag because it is already supported by gitlab.

Merge Request

Review

  • Notify maintainers on the devel mailing list when submitting or updating a merge request.
  • The repository maintainer or another developer will review the merge request.
  • Reviews should happen on GitLab.
  • Reviewers can propose concrete code snippets that the submitter can decide to integrate in their patch series or not:
    • Reviewers can use code blocks in comments, and the submitter can copy and paste them in their patches when updating the merge request
    • Reviewers can edit the submitted branch with the GitLab Web IDE or checking it out manually, stacking new commits on top of the submitted patches: it's up to the submitter to cherry-pick or reject the suggested changes and squash them appropriately with the original commits before the request can be merged
    • If submitters do not agree with the suggested snippets they need to explain why they are rejecting the proposed changes
  • If changes are needed, a force-push with the changes is required to the submitted branch to update the commits that are part of the merge request (always remember to use --force-with-lease instead of --force).
  • Questions, request to clarify and any other kind of discussion should be handled via comments on the merge request.
  • Repeat these review steps until all the changes are accepted.

Merge

  • Merge request must have no thumbs down to be merged and all the discussions should be resolved.
  • Reviewers that approve the general approach but still want to discuss some details can add a thumb up, so other reviewers know that once all the discussions are resolved the merge request can be approved
  • Once all comments have been handled, the reviewer hits the merge button or otherwise pushes the submitted commits to the appropriate branch.

Extra Actions

  • If other actions need to be manually taken when commits are landed the developer accepting and merging the changes is responsible for ensuring that those actions are taken, either by doing it themselves or by asking someone else to do that.
  • If the merged commits need to be backported to other branches through cherry-pick or merges, those should go through merge requests as well: however, only changes related to the backport process are allowed, unrelated changes should be applied with a separate merge request, possibly landing in master first.

Release Commits

The process for releasing a package is documented in the packaging guide.