If you've made changes to gem5 that might benefit others, we strongly encourage you to contribute those changes to the public gem5 repository. There are several reasons to do this:
The main method for contributing code to gem5 is via our code review website: https://gem5-review.googlesource.com/. This documents describes the details of how to create code changes, upload your changes, have your changes reviewed, and finally push your changes to gem5. More information can be found from the following sources:
+-------------+
| Make change |
+------+------+
|
|
v
+-------------+
| Run tests |<--------------+
+------+------+ |
| |
| |
v |
+------+------+ |
| Post review | |
+------+------+ |
| |
v |
+--------+---------+ |
| Wait for reviews | |
+--------+---------+ |
| |
| |
v |
+----+----+ No +------+------+
|Reviewers+--------->+ Update code |
|happy? | +------+------+
+----+----+ ^
| |
| Yes |
v |
+----+-----+ No |
|Maintainer+----------------+
|happy? |
+----+-----+
|
| Yes
v
+------+------+
| Submit code |
+-------------+
After creating your change to gem5, you can post a review on our Gerrit code-review site: https://gem5-review.googlesource.com. Before being able to submit your code to the mainline of gem5, the code is reviewed by others in the community. Additionally, the maintainer for that part of the code must sign off on it.
If you plan on contributing, it is strongly encouraged for you to clone the repository directly, and checkout the develop branch from our gerrit instance at https://gem5.googlesource.com/.
To clone the gem5 repository:
git clone https://gem5.googlesource.com/public/gem5
By default, the stable branch is checked out. The stable branch contains the latest released version of gem5. To obtain code still under-development (and which contributions can be made):
cd gem5 git checkout --track origin/develop
Changes should be made to this develop branch. Changes to the stable branch will be blocked. Once a change on the develop branch is properly incorporated into the gem5 repo it will be merged into the stable branch upon the next release of gem5. New releases of gem5 occur three times a year. Ergo, changes made to the develop branch should appear on the stable branch within three to four months as part of a stable release.
There are a few repositories other than the main gem5 development repository.
It is strongly encouraged to use git branches when making changes to gem5. Additionally, keeping changes small and concise and only have a single logical change per commit.
Unlike our previous flow with Mercurial and patch queues, when using git, you will be committing changes to your local branch. By using separate branches in git, you will be able to pull in and merge changes from mainline and simply keep up with upstream changes.
We use a rebase-always model for contributions to the develop branch of gem5. In this model, the changes are rebased on top of the tip of develop instead of merged. This means that to contribute, you will have to frequently rebase any feature branches on top of develop. If you see a “merge conflict” in gerrit, it can often be solved with a simple rebase. To find out more information about rebasing and git, see the git book.
To help reviewers and future contributors more easily understand and track changes, we require all change descriptions be strictly formatted.
A canonical commit message consists of three parts:
Tags are an optional mechanism to store additional metadata about a patch and acknowledge people who reported a bug or reviewed that patch. Tags are generally appended to the end of the commit message in the order they happen. We currently use the following tags:
Other than the “Signed-off-by”, “Issue-On”, “Reported-by”, and “Tested-by” tags, you generally don't need to add these manually as they are added automatically by Gerrit.
It is encouraged for the author of the patch and the submitter to add a Signed-off-by tag to the commit message. By adding this line, the contributor certifies the contribution is made under the terms of the Developer Certificate of Origin (DCO) [https://developercertificate.org/].
If your change relates to a Jira Issue, it is advised that you provide a link to the issue in the commit message (or messages if the Jira Issue relates to multiple commits). Though optional, doing this can help reviewers understand the context of a change.
It is imperative that you use your real name and your real email address in both tags and in the author field of the changeset.
For significant changes, authors are encouraged to add copyright information and their names at the beginning of the file. The main purpose of the author names on the file is to track who is most knowledgeable about the file (e.g., who has contributed a significant amount of code to the file).
Note: If you do not follow these guidelines, the gerrit review site will automatically reject your patch. If this happens, update your changeset descriptions to match the required style and resubmit. The following is a useful git command to update the most recent commit (HEAD).
git commit --amend
Before posting a change to the code review site, you should always run the quick tests! See TESTING.md for more information.
If you have not signed up for an account on the Gerrit review site (https://gem5-review.googlesource.com), you first have to create an account.
In gerrit, to submit a review request, you can simply push your git commits to a special named branch. For more information on git push see https://git-scm.com/docs/git-push.
There are three ways to push your changes to gerrit.
git push origin HEAD:refs/for/develop
Assuming origin is https://gem5.googlesource.com/public/gem5 and you want to push the changeset at HEAD, this will create a new review request on top of the develop branch. More generally,
git push <gem5 gerrit instance> <changeset>:refs/for/<branch>
See https://gerrit-review.googlesource.com/Documentation/user-upload.html for more information.
The first time you push a change you may get the following error:
remote: ERROR: [fb1366b] missing Change-Id in commit message footer ...
Within the error message, there is a command line you should run. For every new clone of the git repo, you need to run the following command to automatically insert the change id in the the commit (all on one line).
curl -Lo `git rev-parse --git-dir`/hooks/commit-msg \ https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; \ chmod +x `git rev-parse --git-dir`/hooks/commit-msg
If you receive the above error, simply run this command and then amend your changeset.
git commit --amend
It is acceptable to push commits as “Work In Progress” (WIP) changes within gerrit. WIP changes are publicly visible though no one will be able to review the changes or be directly notified they have been submitted. WIP changes can be useful for backing up code currently under-development or for sharing incomplete code with the wider community (i.e., the link to the gerrit change may be shared, and others may download the change, comment on it, and track alterations over time).
See https://gerrit-review.googlesource.com/Documentation/intro-user.html#wip for details on WIP gerrit changes.
To push a change as a WIP:
git push origin HEAD:refs/for/develop%wip
Once you have pushed your change as a WIP, you can log onto gerrit and view it. Once you're happy with the change you can add reviewers which shall move your change from WIP status to be considered for submission by the wider gem5 community. Switching from a WIP to a regular change does not notify the gem5 community, via the gem5-dev mailing-list, that a change has been submitted (as would occur if a change were submitted directly for review). It is therefore important to include reviewers and CC those who you wish to view the change (they will be notified automatically via email).
Only maintainers can bypass gerrit review. This should very rarely be used.
git push origin HEAD:refs/heads/develop
There are a number of options you can specify when uploading your changes to gerrit (e.g., reviewers, labels). The gerrit documentation has more information. https://gerrit-review.googlesource.com/Documentation/user-upload.html
By default, contributions to gem5 should be made on the develop branch. The stable branch is maintained as a stable release branch (i.e., it can be pulled to obtain the latest official release of gem5). Creation of additional branches is generally discouraged due to their tendency to bloat git repositories with abandoned code. However, the creation of new branches is permitted for development of a specific feature or improvement if one or more of the following criteria are met:
If a branch is required it can only be created by a project maintainer. Therefore, if a gem5 contributor desires a separate branch for their work, they should request one from the maintainer of the component the work relates to (see MAINTAINERS for the list of maintainers and the components they are responsible for). The maintainer shall use their discretion to determine whether the creation of a branch is necessary. If approved, the maintainer shall create the branch which the contributor may then use.
Development on a branch within Gerrit functions in exactly the same way as contributing to the develop branch. When contributors to a branch are satisfied, they should create a merge commit into the develop branch. The maintainer should then be notified that the branch they created can now be deleted.
Abandonment of changes within branches may result in these branches being removed from the repository. All branches within a repo should be under active development.
Reviewing patches is done on our gerrit instance at https://gem5-review.googlesource.com/.
After logging in with your Google account, you will be able to comment, review, and push your own patches as well as review others' patches. All gem5 users are encouraged to review patches. The only requirement to review patches is to be polite and respectful of others.
There are multiple labels in Gerrit that can be applied to each review detailed below.
Note: Whenever the patch creator updates the patch all reviewers must re-review the patch. There is no longer a “Fix it, then Ship It” option.
Once you have received reviews for your patch, you will likely need to make changes. To do this, you should update the original git changeset. Then, you can simply push the changeset again to the same Gerrit branch to update the review request.
git push origin HEAD:refs/for/develop
Each patch must meet the following criteria to be merged:
Once a patch meets the above criteria, the submitter of the patch will be able to merge the patch by pressing the “Submit” button on Gerrit. When the patch is submitted, it is merged into the public gem5 branch.
Once a change is submitted, reviewers shall review the change. This may require several iterations before a merge. Comments from reviewers may include questions, and requests for alterations to the change prior to merging. The overarching philosophy in managing this process is that there should be politeness and clear communication between all parties at all times, and, whenever possible, permission should be asked before doing anything that may inconvenience another party. Included below are some guidelines we expect contributors and reviewers to follow.
gem5 releases occur 3 times per year. The procedure for releasing gem5 is as follows:
There may be circumstances in which a change to gem5 is deemed critical and cannot wait for an official release (e.g., a high-priority bug fix). In these circumstances a hotfix shall be made.
First, if a developer suspects a hotfix may be necessary then the issue should be discussed on the gem5-dev mailing list. The community will decide whether the issue is worthy of a hotfix, and the final decision should be made by members of the PMC if there is no consensus. Assuming the hotfix is permitted, the following steps will be taken: