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).
Creating an Apertis GitLab account
The Apertis GitLab instance is open for registration. An account on the Apertis GitLab instance is required to follow the development process detailed below.
Fork the repository to private namespace
Before commencing any work, the developer should fork the repository into their namespace
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.
- Once the changes are ready to be reviewed, create a merge request on GitLab.
- If changes are not ready and some (strongly encouraged) early feedback is required, the merge request should be marked as Work In Progress (WIP).
- Getting changes reviewed is extremely important because it is a great way to
expand knowledge for both the submitter and the reviewer; some
good practices for code review help
the process to go as smoothly as possible:
- Review your own code first
- Write a clear change list description
- Automate the easy stuff
- Answer questions with the code itself
- Narrowly scope changes
- Separate functional and non-functional changes
- Break up large change lists
- Respond graciously to critiques
- Be patient when your reviewer is wrong
- Communicate your responses explicitly
- Artfully solicit missing information
- Award all ties to your reviewer
- Minimize lag between rounds of review
- Maintainers usually monitor pending merge requests, but it can be helpful
to also mention them 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
- 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 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.
- 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 the main branch first.
The process for releasing a package is documented in the packaging guide.