-Authors: Jason Lowe-Power
- Andreas Sandberg
- Steve Reinhardt
- Bobby R. Bruce
-
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:
git clone https://gem5.googlesource.com/public/gem5
```
-By default, the master branch is checked out. The master branch is stable,
-containing the latest released version of gem5. To obtain code still
-under-development (and which contributions can be made):
+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 master branch
+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 master Branch upon the next
+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 master branch within three to
+made to the develop branch should appear on the stable branch within three to
four months as part of a stable release.
Other gem5 repositories
* public/m5threads: The code for a pthreads implementation that works with
gem5's syscall emulation mode.
-
+ * public/gem5-resources: Resources to enable computer architecture research
+ with gem5. See the README.md file in the gem5-resources repository for more
+ information.
+ * public/gem5-website: The gem5.org website source. See the README.md file in
+ the gem5-website repository for more information.
Making changes to gem5
======================
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].
+
+[git book]: https://git-scm.com/book/en/v2/Git-Branching-Rebasing
+
Requirements for change descriptions
------------------------------------
To help reviewers and future contributors more easily understand and track
causes line-wrapping for longer lines.
* (Optional, but highly recommended) A detailed description. This describes
what you have done and why. If the change isn't obvious, you might want to
- motivate why it is needed. Lines need to be wrapped to 75 characters or
+ motivate why it is needed. Lines need to be wrapped to 72 characters or
less.
* Tags describing patch metadata. You are highly recommended to use
tags to acknowledge reviewers for their work. Gerrit will automatically add
automatically with a commit hook by git.
* Tested-by: Used to acknowledge people who tested a patch. Sometimes added
automatically by review systems that integrate with CI systems.
+ * Issue-On: Used to link a commit to an issue in gem5's [issue tracker]. The
+ format should be https://gem5.atlassian.net/browse/GEM5-<NUMBER>
+
+[issue tracker]: https://gem5.atlassian.net/
-Other than the "Signed-off-by", "Reported-by", and "Tested-by" tags, you
-generally don't need to add these manually as they are added automatically by
-Gerrit.
+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
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).
+who has contributed a significant amount of code to the file). The
+`util/update-copyright.py` helper script can help to keep your copyright dates
+up-to-date when you make further changes to files which already have your
+copyright but with older dates.
Note: If you do not follow these guidelines, the gerrit review site will
automatically reject your patch.
git commit --amend
```
-Push change to gerrit as a draft/private
-----------------------------------------
+Push change to gerrit as a Work In Progress
+-------------------------------------------
-See https://gerrit-review.googlesource.com/Documentation/intro-user.html#private-changes
-for details on private gerrit changes.
+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%private
+ git push origin HEAD:refs/for/develop%wip
```
-Once you have pushed your change as "private", you can log onto [gerrit]
-(https://gem5-review.googlesource.com) and once you're happy with the commit
-click the "unmark private" which may be hidden in the "more options" dropdown
-in the upper right corner.
+Once you have pushed your change as a WIP, you can log onto [gerrit](
+https://gem5-review.googlesource.com) 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).
Push change bypassing gerrit
-----------------------------
========
By default, contributions to gem5 should be made on the develop branch. The
-master branch is maintained as a stable release branch (i.e., it can be pulled
+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
intervention by the PMC are undesirable. Attempts should be made to resolve
disagreements via respectful and polite discourse before being escalated to
this level.
+
+Releases
+========
+
+gem5 releases occur 3 times per year. The procedure for releasing gem5 is as
+follows:
+
+1. Developers will be notified, via the gem5-dev mailing list, that a new
+release of gem5 will occur. This should be no sooner than 2 weeks prior to the
+creation of the staging branch (the first step in releasing a new version of
+gem5). This gives time for developers to ensure their changes for the next
+release are submitted to the develop branch.
+2. When a release is ready, a new staging branch shall be created by a project
+maintainer, from develop, with the name "release-staging-{VERSION}". The
+gem5-dev mailing list will be notified that the staging branch will be merged
+into the stable branch after two weeks, thus marking the new release.
+3. The staging branch will have the full suite of gem5 tests run on it to
+ensure all tests pass and the to-be-released code is in a decent state.
+4. If a user submits a changeset to the staging branch, it will be considered
+and undergo the standard Gerrit review process. However, only alterations that
+cannot wait until the following release will be accepted for submission into
+the branch (i.e., submissions to the staging branch for "last minute"
+inclusions to the release should be of a high priority, such as a critical bug
+fix). The project maintainers will use their discretion in deciding whether a
+change may be submitted directly to the staging branch. All other submissions
+to gem5 will continue to be made to the develop branch. Patches submitted
+into the staging branch do not need to be re-added to the develop branch.
+5. Once signed off by members of the PMC the staging branch shall be merged
+into the stable and develop branch. The staging branch will then be deleted.
+6. The stable branch shall be tagged with the correct version number for that
+release. gem5 conforms to a "v{YY}.{MAJOR}.{MINOR}.{HOTFIX}" versioning system.
+E.g., the first major release of 2022 will be "v22.0.0.0", followed by
+"v22.1.0.0". All the releases (with the exception of hotfixes) are considered
+major releases. For the meantime, there are no minor releases though we keep
+the minor release numbers in case this policy changes in the future.
+7. The gem5-dev and gem5-user mailing lists shall be notified of the new gem5
+release.
+
+Hotfixes
+--------
+
+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:
+
+1. A new branch with the prefix "hotfix-" will be created from the stable
+branch. Only gem5 maintainers can create branches. If a non-maintainer requires
+the creation of a hotfix branch then they should contact a gem5 maintainer.
+2. The change shall be submitted to the hotfix branch via gerrit. Full review,
+as with any other change, will be required.
+3. Once fully submitted, the hotfix branch shall be merged into both the
+develop and the stable branch by a gem5 maintainer.
+4. The stable branch will be tagged with the new version number; the same as
+the last but with an incremented hotfix number (e.g., "v20.2.0.0" would
+transition to "v20.2.0.1").
+4. The hotfix branch will then be deleted.
+5. The gem5-dev and the gem5-user mailing lists shall be notified of this
+hotfix.
projects / gem5.git / blobdiff