X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=CONTRIBUTING.md;h=0fb4ab27296839d82be9c7edc08843cd02fabe0e;hb=63d57fd8615c850ea2ca9540f84ca2a72ed475a8;hp=7b3dcfd9d0b2bb0672ca8b4f8b37173dc1045944;hpb=5f304f7e75d2bb17f6a130184737e8c9603d45a7;p=gem5.git diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7b3dcfd9d..0fb4ab272 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,3 @@ -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: @@ -276,20 +271,35 @@ changeset. git commit --amend ``` -Push change to gerrit as a draft/private ----------------------------------------- +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). + +See https://gerrit-review.googlesource.com/Documentation/intro-user.html#wip +for details on WIP gerrit changes. -See https://gerrit-review.googlesource.com/Documentation/intro-user.html#private-changes -for details on private 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 ----------------------------- @@ -466,3 +476,67 @@ contributors and reviewers to follow. 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.