Software Development with GitLab

6.1. Software Development with GitLab#

6.1.1. Browse the Git Repository Online#

You can browse repositories from your home page or from https://gitlab.rtems.org/explore/projects to see a global view including all forks and most starred projects on the RTEMS gitlab instance.

The sort order can be changed by the drop-down at the far right of the GUI. If you are logged in, your preferences should be saved so that the sort order is persistent.

From your home page, you can also view your starred repositories. This is a handy page to use to navigate to the repositories that interest you the most. In addition, you can change your preferences for your Homepage to show the Starred Projects among other possibly useful landing pages.

6.1.2. Using Git#

An exhaustive treatment here is not possible. We suggest availing yourself of online resources to learn how to use Git, such as:

6.1.3. Making Changes with Branches#

Git allows you to make changes in the RTEMS source tree and track those changes locally. We recommend you make all your changes in local branches. If you are working on a few different changes or a progression of changes it is best to use a local branch for each change.

A branch for each change lets your repo’s main branch track the upstream RTEMS’ main branch without interacting with any of the changes you are working on. A completed change is submitted as Merge Request for review and this can take time. While this is happening the upstream’s main branch may be updated and you may need to rebase your work and test again if you are required to change or update your patch. A local branch isolates a specific change from others and helps you manage the process.

6.1.4. Working with Remote Branches#

The previous releases of RTEMS are available through remote branches. To check out a remote branch, first query the Git repository for the list of branches:

git branch origin -r

Then check out the desired remote branch, for example:

git checkout -t rtems70 origin/7.0

Or if you have previously checked out the remote branch then you should see it in your local branches:

git branch

6.1.5. Rebasing#

An alternative to the merge command is rebase, which replays the changes (commits) on one branch onto another. git rebase finds the common ancestor of the two branches, stores each commit of the branch you are on to temporary files and applies each commit in order.

Rebasing makes a cleaner history than merging; the log of a rebased branch looks like a linear history as if the work was done serially rather than in parallel. A primary reason to rebase is to ensure commits apply cleanly on a remote branch, e.g. when submitting patches to RTEMS that you create by working on a branch in a personal repository. Using rebase to merge your work with the remote branch eliminates most integration work for the committer/maintainer. We require maintaining a linear history in our repositories.

There is one caveat to using rebase: Do not rebase commits that you have pushed to a public repository. Rebase abandons existing commits and creates new ones that are similar but different. If you push commits that others pull down, and then you rewrite those commits with git rebase and push them up again, the others will have to re-merge their work and trying to integrate their work into yours can become messy.

6.1.6. Commit Message Guidance#

The commit message associated with a change to any software project is of critical importance. It is the explanation of the change and the rationale for it. Future users looking back through the project history will rely on it. Even the author of the change will likely rely on it once they have forgotten the details of the change. It is important to make the message useful. Here are some guidelines followed by the RTEMS Project to help improve the quality of our commit messages.

  • When committing a change the first line is a summary. Please make it short while hinting at the nature of the change. You can discuss the change if you wish in a ticket that has a PR number which can be referenced in the commit message. After the first line, leave an empty line and add whatever required details you feel are needed.

  • Patches should be as single purpose as possible. This is reflected in the first line summary message. If you find yourself writing something like “Fixed X and Y”, “Updated A and B”, or similar, then evaluate whether the patch should really be a patch series rather than a single larger patch.

  • Format the commit message so it is readable and clear. If you have specific points related to the change make them with separate paragraphs and if you wish you can optionally uses a - marker with suitable indents and alignment to aid readability.

  • Limit the line length to less than 80 characters

  • Please use a real name with a valid email address. Please do not use pseudonyms or provide anonymous contributions.

  • Please do not use terms such as “Fix bug”, “With this change it works”, or “Bump hash”. If you fix a bug please state the nature of the bug and why this change fixes it. If a change makes something work then detail the reason. You do not need to explain the change line by line as the commits diff and associated ticket will.

  • If you change the formatting of source code in a repository please make that a separate patch and use “Formatting changes only” on the first line. Please indicate the reason or process. For example to “Conforming to code standing”, “Reverting to upstream format”, “Result of automatic formatting”.

  • Similarly, if addressing a spelling, grammar, or Doxygen issue, please put that in a commit by itself separate from technical changes.

An example commit message:

test/change: Test message on formatting of commits

- Shows a simple single first line

- Has an empty second line

- Shows the specifics of adding separate points in the commit message as
  separate paragraphs. It also shows a `-` separator and multilines
  that are less than the 80 character width

- Show a ticket update and close

Updates #9876
Closes #8765

The first line generally starts with a file or directory name which indicates the area in RTEMS to which the commit applies. For a patch series which impacts multiple BSPs, it is common to put each BSP into a separate patch. This improves the quality and specificity of the commit messages.

6.1.7. Preparing and Submitting Merge Requests#

The RTEMS Project uses Git for version control and uses Gitlab for managing changes. Contributions are made by creating a Merge Request (MR) on Gitlab. The Gitlab merge request documentation comprehensively explains the concepts of using merge requests. RTEMS will only accept changes via a Merge Request. Most merge requests should have one or more Issues associated with them, unless it is a simple, isolated change. Please do not use merge requests to introduce new code, concepts, styles or to change existing behaviours such as APIs or internal interfaces. Please create an issue before you start the work so the community is aware of the changes coming. The merge requests can then focus on the details of the implementation and approval does not need to be about approval of change at a functional level.

We use project forks as the base of our workflow and outside of that there is no workflow we mandate. What works for one task or work package may not work for another. Complex tasks may affect a number of our GitLab Projects with issues and merge requests in a number of projects. You may want to use an Epic to bring work together.

With our GitLab instance, you fork a repo into your personal workspace and use that to manage your changes. This means you need to keep your forked project up to date. See the Gitlab forking workflow documentation for details. If you are part of a team working on a change you can collaborate on merge requests. GitLab enforces branch naming rules and provides branch naming patterns that simplifies code review and software change management. You can create merge requests from your fork back to the upstream repository. We do not normally squash merge requests. A merge request with more than one commit should be buildable at each commit so a bisect of main does not break.

6.1.7.1. Checklist for Merge Requests#

Check the following items before you publish your merge requests:

  • The author name of each commit is a full name of the author.

  • The author email of each commit is a valid email address for the author.

  • The licence conditions of the contributed content allow an integration into the RTEMS code base.

  • If you are the copyright holder of the entire patch content, then please contribute it under the BSD-2-Clause license. For documentation use CC BY-SA 4.0.

  • Make sure you have a meaningful title which does not exceed 50 characters in one line. Use a “topic: The meaningful title” style. A topic could be the main component of the commit. Just have a look at existing commit messages.

  • Each patch has a good commit message. It should describe the reason for the change. It should list alternative approaches and why they were not chosen.

  • The code changes honour the coding style. At least do your changes in the style of the surrounding code.

  • Each patch contains no spelling mistakes and grammar errors.

  • Each patch is easy to review. It changes one thing only and contains no unrelated changes. Format changes should be separated from functional changes.

  • If commits correspond to Issues, the merge request should have “Close #X.” or “Update #X.” to update status once it is merged.

  • Each patch builds. All RTEMS tests link with every patch.

  • Each patch does not introduce new compiler warnings.

  • Each patch does not introduce new test failures in existing tests.

6.1.7.2. Updating a Merge Request#

As you make changes to your merge request through the review process, you will either be layering additional patches on top of your current patch set, or you will be rebasing your patch set. Either approach is acceptable, but remember that every patch in your patch set must pass continuous integration testing and adhere to the Checklist for Merge Requests. Most often, this means that you should rebase the patch set in your merge request to include the updates.

There are several ways you can rebase the patch set. The following is one suggested workflow:

  • Before making changes, create a new local branch of your merge request. Make your changes on this branch, so that you can always go back to your previous state. Always keep your original branch until you have pushed a new, clean version that supersedes it. Even then, you may want to keep your original branch around in case something went wrong that you did not notice, such as you accidentally removed a necessary commit while rebasing.

  • Make and commit changes locally until you are satisfied with your code

  • Interactively rebase your local branch using git rebase --interactive to allow you to select the order of commits and to reword or fixup commits. One good strategy here is to reorder and fixup commits in one round and then reword them in a second round, so that you get your commits in the right order and shape you want before finalizing the patch descriptions.

  • Force-push your local branch to your merge request branch on your fork. If something goes wrong, you can revert back to your local version.

6.1.8. Rebasing a Merge Request#

You can follow a similar process as Updating a Merge Request to rebase your merge request branch to an updated target branch, e.g., to pick up changes on main. In this case, after creating a local branch, use git pull --rebase stopping to fix merge conflicts along the way. If it gets out of hand, you can either abort the rebase or you can go back to your original branch.

When merge conflicts are too much to handle doing a rebase, you may instead like to create a fresh branch from main and then use git-cherry-pick to pull commits from your merge request branch on to the head of main. If you are having too much trouble, ask for help.

6.1.9. Merge Request Review Process#

Merge requests sent to the RTEMS Gitlab undergo a public review process. At least two approvals are required before a merge request can be pushed to the RTEMS repository. It helps if you follow the Checklist for Merge Requests. An easy to review patch series which meets the quality standards of the RTEMS Project will be more likely to get integrated quickly.

The review process includes both objective and subjective feedback. You should reflect upon and consider all feedback before making or refusing changes. It is important to note that some feedback may be relevant at one point in time, but less relevant in the future. Also, what concerns one developer may not concern another. Just because you address all the feedback in one round of review does not mean your submission will be approved, as someone (even the same reviewer) may notice something that was not seen before. It is important to have patience, humility, and open-mindedness when engaging in open-source software review and approval processes. This is true for both contributors and reviewers.

Reviews should be conducted primarily via the GitLab interface using the in-line commenting feature. Follow-up comments to the same line should be threaded, while new comments should be added to the specific, relevant line of modified code. Although high-level comments about the entire patch set are allowed, the most useful commments are those that are specifically targeted to problematic lines of code.

Threads usually should be resolved by the first author of the thread, i.e., the reviewer who wrote the first comment. In particular, code submitters should not resolve the threads but should reply to the thread to indicate that they think they have addressed the concern.

6.1.9.1. Approvers#

Merge Request approvals must be from a code owner, identified by the CODEOWNERS file and by sub-groups beneath Approvers. Any one who has requested approval permission can approve a merge request. Once a patch series is approved for integration into the RTEMS code base it can be merged by anyone with merge rights, which may include an automated bot.

Approvers are volunteering their time so be polite. If you do not get a response to a merge request after five working days, please send a reminder on the merge request or send email to the Developers Mailing List.

Contents