-
Notifications
You must be signed in to change notification settings - Fork 103
Contributing to ReFrame
In order to contribute to the project, you will have first to fork the repository (if you are a member of the official development team, this step is not needed). After you have forked, you should create a new branch for your work. Direct pushes to master are disallowed (of course, you can push to your fork's master, but a good strategy is to try to keep your master in sync with the main development's master without "contaminating" it with commits that are not officially in the master, unless you really want to diverge). After you have finished your work, push your changes to your remote and then use Github to create a pull request (PR) to merge your new branch with the master of the main repository. Though not strictly required, we do have the following recommended naming convention for branches:
- Feature branches:
feature/pbs-scheduler - Bug fix branches:
bugfix/incorrect-host-parsing - New regression check branches:
check/hello-world-codes
Notice the descriptive name in branches. Please do not use cryptic names, names referring to an issue number or very long names. You can add more details in your PR's description, in which you should also put a note of the actual issue number this request fixes, e.g., "Fixes issue #31". Github recognises the "fixes" keyword and will automatically close the corresponding issue as soon as your PR is merged into the master.
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.
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~10This 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 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-featureNote 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.
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.
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:
- Merge the master into your branch
- You can achieve this by running on your branch:
git merge master.
- You can achieve this by running on your branch:
-
Rebase your branch onto the master
- You can achieve this by running on your branch:
git rebase master.
- You can achieve this by running on your branch:
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).
Please go through our Coding Style Guide before submitting a merge request.