Skip to content

Contributing to ReFrame

Jump to bottom
Vasileios Karakasis edited this page Jun 21, 2026 · 10 revisions

Which branch should a pull request target

Since version 4.0, there are two main branches in ReFrame's repository:

  • master: This branch holds the latest stable version and its HEAD may also include yet unpublished bug fixes.
  • develop: This branch holds the development of the next version. This is the default branch, but read on to understand where your contribution should be targeted to.

In order to contribute to the project, you will have first to fork the repository and submit a pull request from one of your fork's branches. Depending on your contribution, you should target a different branch:

  • New features, bug fixes for new features, documentation of new features should target the develop branch, which is also the default.
  • Bug fixes, documentation updates and small enhancements of an already published stable release may target directly the master branch. Changes introduced to master have a quicker turn around time as they will be released as patch-level bumps, whereas changes in develop will be scheduled for release with the next minor or major version bump.

The develop and master branch are generally divergent, but they are sync'ed in every release.

  • In patch releases, there is a partial sync; master will be merged to develop, so that any bug fixes or documentation updates are adopted in develop too.
  • In normal releases, there is a full sync; develop will be merged into master and the new release will be tagged.

Targeting the wrong branch

If you branched off from the the wrong branch (e.g., develop instead of master) and you would like to change your PR target, simply changing the pull request base branch is not enough. Here are the steps you would need to follow:

  1. Change the target branch to the desired one (e.g., master)
  2. In your local working copy, create a new branch starting from the desired branch
  3. Cherry-pick the commits from your original branch to the new one
  4. Force push to your remote branch

Here's an example of steps (2)-(4) assuming that you want to reopen your bugfix PR on bugfix/xyz against master:

git checkout master
git checkout -b bugfix/xyz_new
git cherry-pick <your-commits-from-xyz-branch>
git push <your-remote> +bugfix/xyz_new:bugfix/xyz

Pull request policy

The title of the pull request is crucial, as it will appear almost intact as an entry in the Release Notes. Every PR must be formatted as follows:

  1. The PR title must be prefixed with one of the following tags. These will determine the section of the Release Notes, in which it will appear:

    • [feat]: This PR introduces a new feature.
    • [bugfix]: This PR introduces a bug fix.
    • [test]: This PR introduces a new ReFrame test.
    • [doc]: This PR introduces improvements to the documentation.
    • [ci]: This PR introduces improvements to the CI of ReFrame itself.

  2. The title of PRs follows the commit message policy described below but without the 50 characters limit. The titles must be in imperative mood without a final full stop, e.g., [feat] Add support for baking cakes, [bugfix] Fix framework crash when opening hot oven. Titles such as [feat] Adding support for X, [bugfix] Fixed bug X are disallowed.

  3. The title of the PR must describe briefly and precisely what it offers. It should not be overly long. Details should be listed in the PR description.

  4. If the PR closes an open issue, this should be listed in the description as follows:

    Fixes #123.

    or

    Closes #123.

    These are special Github keywords that will automatically close the issue, as soon as the PR is merged.

    If the PR closes multiple issues, each issue must be placed in a separate line after the magic word. For example,

    Closes #123.
Closes #456.

    Putting multiple issue numbers in the same line, will only close the first one. The following will only close issue #123:

    # WRONG
Closes #123, #456.

Commit policy

Developer Certificate of Origin

This project requires a Developer Certificate of Origin (DCO) on Pull Requests. It essentially requires all commit messages to contain the Signed-off-by line with an email address that matches the commit author. In practice, this can be easily achieved by passing the -s option to git:

git commit -s -m 'My commit message'

Commit messages

Commit messages must have a subject line and optionally a more detailed message. The subject line must be short and descriptive. The recommended size of the subject line is 50 characters and git-aware editors will highlight it when this limit is exceeded. The subject is the first line of your commit message, so a typical commit message should look like this:

Add support for preparing coffee

More detailed message if needed.

Have a look at this article on how to nicely format your commit messages. We are not strict on how to format your messages, but you should keep the subject line short and descriptive.

Commit history

During development you will most probably end up committing temporary or incomplete changes just to save your work or just because something trivial slipped your attention. So you could end up having tens of commits with most of them being

  • first attempt to my feature
  • second attempt to my feature
  • third attempt to my feature
  • my feature is complete
  • Ah, I forgot to commit a file
  • Oops, another file + a silly typo

You might already see that the signal-to-noise ratio is becoming quite low, so please take the extra step to make your commits more meaningful and complete before submitting a PR. This is quite easy with git, especially if you have not yet pushed to a remote. Say you need to revise the last 10 commits you have made, here is the procedure. While on your branch, do the following:

git rebase -i HEAD~10

This will open up an editor with the following text:

pick <commit> <msg>
pick <commit> <msg>
... 7 more commits
pick <commit> <msg>

You can now pick, squash or delete commits from this list. The revised list of commits will be re-applied on your branch (see git rebase documentation for more details). Let's say we want to squash the first 7 commits, keep the next 2 and squash the last one. Just edit this file as following:

pick <commit> <msg>
squash <commit> <msg>
... squash 5 more commits
pick <commit> <msg>
pick <commit> <msg>
squash <commit> <msg>

After saving and closing this file, the rebase takes place and git presents you with a large commit message for the squashed commits containing all the individual commit messages. Edit these files as they show up until no more squashes are performed and you are done. You will have ended up with just 3 meaningful commits.

Squashing commits on a remote branch

Squashing commits on a remote branch can be dangerous if other people are working on this branch, because it will rewrite the history and invalidate their local copies. However, if your are the only person working on this remote branch or if you know that people that had pulled your remote have made no local changes to it (or they simply don't care about their local commits being overwritten), then it is safe to squash commits on the remote as well. The procedure is exactly the same as before with the only difference being that you need to make a "forced update" on your remote branch:

git push origin +feature/my-awesome-new-feature

Note the + symbol denoting the forced update. If you don't use it, your push will be rejected.

If you can and want to squash commits on your remote branch, please do not squash commits that have been already peer-reviewed.

Working with multiple remotes

If you work with multiple remotes, e.g., your fork, another fellow's fork and the original repository, it's a good practice to always perform a git push remote --dry-run and review the remote you are going to push to, so that you avoid pushes to wrong remotes.

Rebasing onto master instead of merging

This is not a strict policy but rather a recommendation.

Sometimes during development on your branch, you may need to incorporate the progress done in master into your branch and continue your work. There are two options to achieve this:

  1. Merge the master into your branch
    • You can achieve this by running on your branch: git merge master.
  2. Rebase your branch onto the master
    • You can achieve this by running on your branch: git rebase master.

The first method will interleave all the commit history in master with the commits in your branch and add an additional commit denoting the merge. You will then end up with a history in your branch like the following:

<commit> Merge master into my-branch
<commit> master
<commit> master
<commit> master
<commit> my-branch
<commit> my-branch
<commit> master
<commit> my-branch
<commit> master
<commit> my-branch
<commit> my-branch

You might already see that your work might be "lost" among the commits of master, especially if your branch has been left quite behind.

The solution of the rebase solves this issue by re-applying all your commits in your branch over the latest tip of master. Your history will look now much cleaner and more consistent:

<commit> my-branch
<commit> my-branch
<commit> my-branch
<commit> my-branch
<commit> my-branch
<commit> master
<commit> master
<commit> master
<commit> master
<commit> master

The main different of rebase is that it re-applies your commits, which effectively means that these are new commits (new hash, new timestamp) over the tip of the branch you are rebasing onto. Having said that, it is not safe to rebase a remote branch unless you really know you are the only person working on this (see also Squashing commits on a remote branch).

References

Coding style

Please go through our Coding Style Guide before submitting a pull request.

Clone this wiki locally