-Authors: Jason Lowe-Power
- Andreas Sandberg
- Steve Reinhardt
-
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:
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:
- * http://gem5.org/Submitting_Contributions
+ * http://gem5.org/contributing
* https://gerrit-review.googlesource.com/Documentation/index.html
* https://git-scm.com/book
|
|
v
- +------+------+
- | Post review |
- +------+------+
- |
- v
- +--------+---------+
- | Wait for reviews | <--------+
+ +-------------+
+ | Run tests |<--------------+
+ +------+------+ |
+ | |
+ | |
+ v |
+ +------+------+ |
+ | Post review | |
+ +------+------+ |
+ | |
+ v |
+ +--------+---------+ |
+ | Wait for reviews | |
+--------+---------+ |
| |
| |
===================================
If you plan on contributing, it is strongly encouraged for you to clone the
-repository directly from our gerrit instance at
-https://gem5.googlesource.com/.
+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 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):
+
+```
+cd gem5
+git checkout --track origin/develop
+```
-To clone the master gem5 repository:
- > git clone https://gem5.googlesource.com/public/gem5
+Changes should be made to this develop branch. Changes to the master 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
+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
+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.
-Other gem5 branches
--------------------
-
-None right now.
Making changes to gem5
======================
A canonical commit message consists of three parts:
* A short summary line describing the change. This line starts with one or
- more keywords separated by commas followed by a colon and a description of
- the change. This line should be no more than 65 characters long since
- version control systems usually add a prefix that causes line-wrapping for
- longer lines.
+ more keywords (found in the MAINTAINERS file) separated by commas followed
+ by a colon and a description of the change. This line should be no more than
+ 65 characters long since version control systems usually add a prefix that
+ 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
most tags.
-The keyword should be one or more of the following separated by commas:
- * Architecture name in lower case (e.g., arm or x86): Anything that is
- target-architecture specific.
- * base
- * ext
- * stats
- * sim
- * syscall_emul
- * config:
- * mem: Classic memory system. Ruby uses its own keyword.
- * ruby: Ruby memory models.
- * cpu: CPU-model specific (except for kvm)
- * kvm: KVM-specific. Changes to host architecture specific components should
- include an architecture keyword (e.g., arm or x86) as well.
- * gpu-compute
- * energy
- * dev
- * arch: General architecture support (src/arch/)
- * scons: Build-system related. Trivial changes as a side effect of doing
- something unrelated (e.g., adding a source file to a SConscript) don't
- require this.
- * tests
- * style: Changes to the style checkers of style fixes.
- * misc
-
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.
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](https://gem5.atlassian.net), 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.
and resubmit. The following is a useful git command to update the most recent
commit (HEAD).
- > git commit --amend
+```
+ git commit --amend
+```
+
+Running tests
+=============
+
+Before posting a change to the code review site, you should always run the
+quick tests!
+See TESTING.md for more information.
Posting a review
================
Push change to gerrit review
----------------------------
- > git push origin HEAD:refs/for/master
+```
+ 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
-master branch. More generally,
+develop branch. More generally,
- > git push <gem5 gerrit instance> <changeset>:refs/for/<branch>
+```
+ 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
- > ...
+```
+ 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
+```
+ 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
+```
+ git commit --amend
+```
-Push change to gerrit as a draft
---------------------------------
+Push change to gerrit as a Work In Progress
+-------------------------------------------
+
+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).
- > git push origin HEAD:refs/drafts/master
+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](
+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
-----------------------------
Only maintainers can bypass gerrit review. This should very rarely be used.
- > git push origin HEAD:refs/heads/master
+```
+ git push origin HEAD:refs/heads/develop
+```
Other gerrit push options
-------------------------
information.
https://gerrit-review.googlesource.com/Documentation/user-upload.html
+Branches
+========
+
+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
+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:
+
+1. The feature/improvement is likely to be of a large size, consisting of many
+commits, with little logic in these commits being contributed separately.
+2. The feature/improvement will be developed over a long period of time.
+3. There is sufficient reason that a feature/improvement should not be part
+of the next gem5 release (e.g., the change should be held within a feature
+branch until ready for the next release, at which point it will be merged
+into the develop branch).
+
+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
=================
the patch can be merged. The patch will receive a +1 if gem5 builds and
runs, and it will receive a +2 if the stats match.
* Style-Check: This is automatically generated and tests the patch against the
- gem5 code style (http://www.gem5.org/Coding_Style). The patch must receive a
- +1 from the style checker to be pushed.
+ gem5 code style
+ (http://www.gem5.org/documentation/general_docs/development/coding_style/).
+ The patch must receive a +1 from the style checker to be pushed.
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.
can simply push the changeset again to the same Gerrit branch to update the
review request.
- > git push origin HEAD:refs/for/master
-
-Note: If you have posted a patch and don't receive any reviews, you may need to
-prod the reviewers. You can do this by adding a reply to your changeset review
-on gerrit. It is expected that at least the maintainer will supply a review for
-your patch.
+```
+ git push origin HEAD:refs/for/develop
+```
Committing changes
==================
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.
+
+Review moderation and guidelines
+--------------------------------
+
+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.
+
+ * In all forms of communication, contributors and reviewers must be polite.
+ Comments seen as being needlessly hostile or dismissive will not be
+ tolerated.
+ * Change contributors should respond to, or act upon, each item of feedback
+ given by reviewers. If there is disagreement with a piece of
+ feedback, a sufficiently detailed reason for this disagreement should
+ be given. Polite discussion, and sharing of information and expertise
+ is strongly encouraged.
+ * Contributors are advised to assign reviewers when submitting a change.
+ Anyone who contributes to gem5 can be assigned as a reviewer. However,
+ all changes must be accepted by at least one maintainer prior to a
+ merge, ergo assigning of at least one maintainer as a reviewer is
+ strongly recommended. Please see MAINTAINERS for a breakdown of
+ gem5 maintainers and which components they claim responsibility for.
+ Maintainers should be chosen based on which components the change is
+ targeting. Assigning of reviewers is not strictly enforced, though not
+ assigning reviewers may slow the time in which a change is reviewed.
+ * If a contributor posts a change and does not receive any reviews after two
+ working days (excluding regional holidays), it is acceptable to "prod"
+ reviewers. This can be done by adding a reply to the changeset review
+ (e.g., "Would it be possible for someone to review my change?"). If the
+ contributor has yet to assign reviewers, they are strongly advised to do so.
+ Reviewers will get notified when assigned to referee a change.
+ * By default, the original contributor is assumed to own a change. I.e.,
+ they are assumed to be the sole party to submit patchsets. If someone
+ other than the original contributor wishes to submit patchsets to a
+ change on the original contributor's behalf, they should first ask
+ permission. If two working days pass without a response, a patchset may be
+ submitted without permission. Permission does not need to be asked to submit
+ a patchset consisting of minor, inoffensive, changes such a typo and format
+ fixes.
+ * Once a change is ready to merge, it enters a "Ready to Submit" state. The
+ original contributor should merge their change at this point, assuming they
+ are content with the commit in its present form. After two working days, a
+ reviewer may message a contributor to remind them of the change being in a
+ "Ready to Submit" state and ask if they can merge the change on the
+ contributors behalf. If a further two working days elapse without a
+ response, the reviewer may merge without permission. A contributor may keep
+ a change open for whatever reason though this should be communicated to the
+ reviewer when asked.
+ * After a month of inactivity from a contributor on an active change, a
+ reviewer may post a message on the change reminding the submitter, and
+ anyone else watching the change, of its active status and ask if they are
+ still interested in eventually merging the change. After two weeks of no
+ response the reviewer reserves the right to abandon the change under the
+ assumption there is no longer interest.
+ * The final arbiter in any dispute between reviewers and/or contributors
+ is the PMC (PMC members are highlighted in MAINTAINERS). Disputes requiring
+ 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 master 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 master and develop branch. The staging branch will then be deleted.
+6. The master 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 master
+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 master branch by a gem5 maintainer.
+4. The master 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