Contributing to ReFrame

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 branch is kept in sync with the master so that any bug fixes introduced are carried forward to the next release. When a minor or major release of a new version is made, develop will be merged into master and tagged accordingly.

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

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

• Merging vs. Rebasing
• git-rebase

Coding style

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