CONTRIBUTING.md revision 11921
111901Sjason@lowepower.comAuthors: Jason Lowe-Power 211901Sjason@lowepower.com Andreas Sandberg 311901Sjason@lowepower.com Steve Reinhardt 411901Sjason@lowepower.com 511901Sjason@lowepower.comIf you've made changes to gem5 that might benefit others, we strongly encourage 611901Sjason@lowepower.comyou to contribute those changes to the public gem5 repository. There are 711901Sjason@lowepower.comseveral reasons to do this: 811901Sjason@lowepower.com * Share your work with others, so that they can benefit from new functionality. 911901Sjason@lowepower.com * Support the scientific principle by enabling others to evaluate your 1011901Sjason@lowepower.com suggestions without having to guess what you did. 1111901Sjason@lowepower.com * Once your changes are part of the main repo, you no longer have to merge 1211901Sjason@lowepower.com them back in every time you update your local repo. This can be a huge time 1311901Sjason@lowepower.com saving! 1411901Sjason@lowepower.com * Once your code is in the main repo, other people have to make their changes 1511901Sjason@lowepower.com work with your code, and not the other way around. 1611901Sjason@lowepower.com * Others may build on your contributions to make them even better, or extend 1711901Sjason@lowepower.com them in ways you did not have time to do. 1811901Sjason@lowepower.com * You will have the satisfaction of contributing back to the community. 1911901Sjason@lowepower.com 2011901Sjason@lowepower.comThe main method for contributing code to gem5 is via our code review website: 2111901Sjason@lowepower.comhttps://gem5-review.googlesource.com/. This documents describes the details of 2211901Sjason@lowepower.comhow to create code changes, upload your changes, have your changes 2311901Sjason@lowepower.comreviewed, and finally push your changes to gem5. More information can be found 2411901Sjason@lowepower.comfrom the following sources: 2511901Sjason@lowepower.com * http://gem5.org/Submitting_Contributions 2611901Sjason@lowepower.com * https://gerrit-review.googlesource.com/Documentation/index.html 2711901Sjason@lowepower.com * https://git-scm.com/book 2811901Sjason@lowepower.com 2911901Sjason@lowepower.com 3011901Sjason@lowepower.comHigh-level flow for submitting changes 3111901Sjason@lowepower.com====================================== 3211901Sjason@lowepower.com 3311901Sjason@lowepower.com +-------------+ 3411901Sjason@lowepower.com | Make change | 3511901Sjason@lowepower.com +------+------+ 3611901Sjason@lowepower.com | 3711901Sjason@lowepower.com | 3811901Sjason@lowepower.com v 3911901Sjason@lowepower.com +------+------+ 4011901Sjason@lowepower.com | Post review | 4111901Sjason@lowepower.com +------+------+ 4211901Sjason@lowepower.com | 4311901Sjason@lowepower.com v 4411901Sjason@lowepower.com +--------+---------+ 4511901Sjason@lowepower.com | Wait for reviews | <--------+ 4611901Sjason@lowepower.com +--------+---------+ | 4711901Sjason@lowepower.com | | 4811901Sjason@lowepower.com | | 4911901Sjason@lowepower.com v | 5011901Sjason@lowepower.com +----+----+ No +------+------+ 5111901Sjason@lowepower.com |Reviewers+--------->+ Update code | 5211901Sjason@lowepower.com |happy? | +------+------+ 5311901Sjason@lowepower.com +----+----+ ^ 5411901Sjason@lowepower.com | | 5511901Sjason@lowepower.com | Yes | 5611901Sjason@lowepower.com v | 5711901Sjason@lowepower.com +----+-----+ No | 5811901Sjason@lowepower.com |Maintainer+----------------+ 5911901Sjason@lowepower.com |happy? | 6011901Sjason@lowepower.com +----+-----+ 6111901Sjason@lowepower.com | 6211901Sjason@lowepower.com | Yes 6311901Sjason@lowepower.com v 6411901Sjason@lowepower.com +------+------+ 6511901Sjason@lowepower.com | Submit code | 6611901Sjason@lowepower.com +-------------+ 6711901Sjason@lowepower.com 6811901Sjason@lowepower.comAfter creating your change to gem5, you can post a review on our Gerrit 6911901Sjason@lowepower.comcode-review site: https://gem5-review.googlesource.com. Before being able to 7011901Sjason@lowepower.comsubmit your code to the mainline of gem5, the code is reviewed by others in the 7111901Sjason@lowepower.comcommunity. Additionally, the maintainer for that part of the code must sign off 7211901Sjason@lowepower.comon it. 7311901Sjason@lowepower.com 7411901Sjason@lowepower.comCloning the gem5 repo to contribute 7511901Sjason@lowepower.com=================================== 7611901Sjason@lowepower.com 7711901Sjason@lowepower.comIf you plan on contributing, it is strongly encouraged for you to clone the 7811901Sjason@lowepower.comrepository directly from our gerrit instance at 7911901Sjason@lowepower.comhttps://gem5.googlesource.com/. 8011901Sjason@lowepower.com 8111901Sjason@lowepower.comTo clone the master gem5 repository: 8211901Sjason@lowepower.com > git clone https://gem5.googlesource.com/public/gem5 8311901Sjason@lowepower.com 8411901Sjason@lowepower.comOther gem5 repositories 8511901Sjason@lowepower.com----------------------- 8611901Sjason@lowepower.com 8711901Sjason@lowepower.comThere are a few repositories other than the main gem5 development repository. 8811901Sjason@lowepower.com 8911901Sjason@lowepower.com * public/m5threads: The code for a pthreads implementation that works with 9011901Sjason@lowepower.com gem5's syscall emulation mode. 9111901Sjason@lowepower.com 9211901Sjason@lowepower.comOther gem5 branches 9311901Sjason@lowepower.com------------------- 9411901Sjason@lowepower.com 9511901Sjason@lowepower.comNone right now. 9611901Sjason@lowepower.com 9711901Sjason@lowepower.comMaking changes to gem5 9811901Sjason@lowepower.com====================== 9911901Sjason@lowepower.com 10011901Sjason@lowepower.comIt is strongly encouraged to use git branches when making changes to gem5. 10111901Sjason@lowepower.comAdditionally, keeping changes small and concise and only have a single logical 10211901Sjason@lowepower.comchange per commit. 10311901Sjason@lowepower.com 10411901Sjason@lowepower.comUnlike our previous flow with Mercurial and patch queues, when using git, you 10511901Sjason@lowepower.comwill be committing changes to your local branch. By using separate branches in 10611901Sjason@lowepower.comgit, you will be able to pull in and merge changes from mainline and simply 10711901Sjason@lowepower.comkeep up with upstream changes. 10811901Sjason@lowepower.com 10911901Sjason@lowepower.comRequirements for change descriptions 11011901Sjason@lowepower.com------------------------------------ 11111901Sjason@lowepower.comTo help reviewers and future contributors more easily understand and track 11211901Sjason@lowepower.comchanges, we require all change descriptions be strictly formatted. 11311901Sjason@lowepower.com 11411901Sjason@lowepower.comA canonical commit message consists of three parts: 11511901Sjason@lowepower.com * A short summary line describing the change. This line starts with one or 11611901Sjason@lowepower.com more keywords separated by commas followed by a colon and a description of 11711901Sjason@lowepower.com the change. This line should be no more than 65 characters long since 11811901Sjason@lowepower.com version control systems usually add a prefix that causes line-wrapping for 11911901Sjason@lowepower.com longer lines. 12011901Sjason@lowepower.com * (Optional, but highly recommended) A detailed description. This describes 12111901Sjason@lowepower.com what you have done and why. If the change isn't obvious, you might want to 12211901Sjason@lowepower.com motivate why it is needed. Lines need to be wrapped to 75 characters or 12311901Sjason@lowepower.com less. 12411901Sjason@lowepower.com * Tags describing patch metadata. You are highly recommended to use 12511901Sjason@lowepower.com tags to acknowledge reviewers for their work. Gerrit will automatically add 12611901Sjason@lowepower.com most tags. 12711901Sjason@lowepower.com 12811901Sjason@lowepower.comThe keyword should be one or more of the following separated by commas: 12911901Sjason@lowepower.com * Architecture name in lower case (e.g., arm or x86): Anything that is 13011901Sjason@lowepower.com target-architecture specific. 13111901Sjason@lowepower.com * base 13211901Sjason@lowepower.com * ext 13311901Sjason@lowepower.com * stats 13411901Sjason@lowepower.com * sim 13511901Sjason@lowepower.com * syscall_emul 13611901Sjason@lowepower.com * config: 13711901Sjason@lowepower.com * mem: Classic memory system. Ruby uses its own keyword. 13811901Sjason@lowepower.com * ruby: Ruby memory models. 13911901Sjason@lowepower.com * cpu: CPU-model specific (except for kvm) 14011901Sjason@lowepower.com * kvm: KVM-specific. Changes to host architecture specific components should 14111901Sjason@lowepower.com include an architecture keyword (e.g., arm or x86) as well. 14211901Sjason@lowepower.com * gpu-compute 14311901Sjason@lowepower.com * energy 14411901Sjason@lowepower.com * dev 14511901Sjason@lowepower.com * arch: General architecture support (src/arch/) 14611901Sjason@lowepower.com * scons: Build-system related. Trivial changes as a side effect of doing 14711901Sjason@lowepower.com something unrelated (e.g., adding a source file to a SConscript) don't 14811901Sjason@lowepower.com require this. 14911901Sjason@lowepower.com * tests 15011901Sjason@lowepower.com * style: Changes to the style checkers of style fixes. 15111901Sjason@lowepower.com * misc 15211901Sjason@lowepower.com 15311901Sjason@lowepower.comTags are an optional mechanism to store additional metadata about a patch and 15411901Sjason@lowepower.comacknowledge people who reported a bug or reviewed that patch. Tags are 15511901Sjason@lowepower.comgenerally appended to the end of the commit message in the order they happen. 15611901Sjason@lowepower.comWe currently use the following tags: 15711901Sjason@lowepower.com * Signed-off-by: Added by the author and the submitter (if different). 15811901Sjason@lowepower.com This tag is a statement saying that you believe the patch to be correct and 15911901Sjason@lowepower.com have the right to submit the patch according to the license in the affected 16011901Sjason@lowepower.com files. Similarly, if you commit someone else's patch, this tells the rest 16111901Sjason@lowepower.com of the world that you have have the right to forward it to the main 16211901Sjason@lowepower.com repository. If you need to make any changes at all to submit the change, 16311901Sjason@lowepower.com these should be described within hard brackets just before your 16411901Sjason@lowepower.com Signed-off-by tag. By adding this line, the contributor certifies the 16511901Sjason@lowepower.com contribution is made under the terms of the Developer Certificate of Origin 16611901Sjason@lowepower.com (DCO) [https://developercertificate.org/]. 16711901Sjason@lowepower.com * Reviewed-by: Used to acknowledge patch reviewers. It's generally considered 16811901Sjason@lowepower.com good form to add these. Added automatically. 16911901Sjason@lowepower.com * Reported-by: Used to acknowledge someone for finding and reporting a bug. 17011901Sjason@lowepower.com * Reviewed-on: Link to the review request corresponding to this patch. Added 17111901Sjason@lowepower.com automatically. 17211901Sjason@lowepower.com * Change-Id: Used by Gerrit to track changes across rebases. Added 17311901Sjason@lowepower.com automatically with a commit hook by git. 17411901Sjason@lowepower.com * Tested-by: Used to acknowledge people who tested a patch. Sometimes added 17511901Sjason@lowepower.com automatically by review systems that integrate with CI systems. 17611901Sjason@lowepower.com 17711901Sjason@lowepower.comOther than the "Signed-off-by", "Reported-by", and "Tested-by" tags, you 17811901Sjason@lowepower.comgenerally don't need to add these manually as they are added automatically by 17911901Sjason@lowepower.comGerrit. 18011901Sjason@lowepower.com 18111901Sjason@lowepower.comIt is encouraged for the author of the patch and the submitter to add a 18211901Sjason@lowepower.comSigned-off-by tag to the commit message. By adding this line, the contributor 18311901Sjason@lowepower.comcertifies the contribution is made under the terms of the Developer Certificate 18411901Sjason@lowepower.comof Origin (DCO) [https://developercertificate.org/]. 18511901Sjason@lowepower.com 18611901Sjason@lowepower.comIt is imperative that you use your real name and your real email address in 18711901Sjason@lowepower.comboth tags and in the author field of the changeset. 18811901Sjason@lowepower.com 18911921Spierre-yves.peneau@lirmm.frFor significant changes, authors are encouraged to add copyright information 19011921Spierre-yves.peneau@lirmm.frand their names at the beginning of the file. The main purpose of the author 19111921Spierre-yves.peneau@lirmm.frnames on the file is to track who is most knowledgeable about the file (e.g., 19211921Spierre-yves.peneau@lirmm.frwho has contributed a significant amount of code to the file). 19311921Spierre-yves.peneau@lirmm.fr 19411901Sjason@lowepower.comNote: If you do not follow these guidelines, the gerrit review site will 19511901Sjason@lowepower.comautomatically reject your patch. 19611901Sjason@lowepower.comIf this happens, update your changeset descriptions to match the required style 19711901Sjason@lowepower.comand resubmit. The following is a useful git command to update the most recent 19811901Sjason@lowepower.comcommit (HEAD). 19911901Sjason@lowepower.com 20011901Sjason@lowepower.com > git commit --amend 20111901Sjason@lowepower.com 20211901Sjason@lowepower.comPosting a review 20311901Sjason@lowepower.com================ 20411901Sjason@lowepower.com 20511901Sjason@lowepower.comIf you have not signed up for an account on the Gerrit review site 20611901Sjason@lowepower.com(https://gem5-review.googlesource.com), you first have to create an account. 20711901Sjason@lowepower.com 20811901Sjason@lowepower.comSetting up an account 20911901Sjason@lowepower.com--------------------- 21011901Sjason@lowepower.com 1. Go to https://gem5.googlesource.com/ 21111901Sjason@lowepower.com 2. Click "Sign In" in the upper right corner. Note: You will need a Google 21211901Sjason@lowepower.com account to contribute. 21311901Sjason@lowepower.com 3. After signing in, click "Generate Password" and follow the instructions. 21411901Sjason@lowepower.com 21511901Sjason@lowepower.comSubmitting a change 21611901Sjason@lowepower.com------------------- 21711901Sjason@lowepower.com 21811901Sjason@lowepower.comIn gerrit, to submit a review request, you can simply push your git commits to 21911901Sjason@lowepower.coma special named branch. For more information on git push see 22011901Sjason@lowepower.comhttps://git-scm.com/docs/git-push. 22111901Sjason@lowepower.com 22211901Sjason@lowepower.comThere are three ways to push your changes to gerrit. 22311901Sjason@lowepower.com 22411901Sjason@lowepower.comPush change to gerrit review 22511901Sjason@lowepower.com---------------------------- 22611901Sjason@lowepower.com 22711901Sjason@lowepower.com > git push origin HEAD:refs/for/master 22811901Sjason@lowepower.com 22911901Sjason@lowepower.comAssuming origin is https://gem5.googlesource.com/public/gem5 and you want to 23011901Sjason@lowepower.compush the changeset at HEAD, this will create a new review request on top of the 23111901Sjason@lowepower.commaster branch. More generally, 23211901Sjason@lowepower.com 23311901Sjason@lowepower.com > git push <gem5 gerrit instance> <changeset>:refs/for/<branch> 23411901Sjason@lowepower.com 23511901Sjason@lowepower.comSee https://gerrit-review.googlesource.com/Documentation/user-upload.html for 23611901Sjason@lowepower.commore information. 23711901Sjason@lowepower.com 23811901Sjason@lowepower.comPushing your first change 23911901Sjason@lowepower.com-------------------------- 24011901Sjason@lowepower.comThe first time you push a change you may get the following error: 24111901Sjason@lowepower.com 24211901Sjason@lowepower.com > remote: ERROR: [fb1366b] missing Change-Id in commit message footer 24311901Sjason@lowepower.com > ... 24411901Sjason@lowepower.com 24511901Sjason@lowepower.comWithin the error message, there is a command line you should run. For every new 24611901Sjason@lowepower.comclone of the git repo, you need to run the following command to automatically 24711901Sjason@lowepower.cominsert the change id in the the commit (all on one line). 24811901Sjason@lowepower.com 24911901Sjason@lowepower.com > curl -Lo `git rev-parse --git-dir`/hooks/commit-msg 25011901Sjason@lowepower.com https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; chmod +x 25111901Sjason@lowepower.com `git rev-parse --git-dir`/hooks/commit-msg 25211901Sjason@lowepower.com 25311901Sjason@lowepower.comIf you receive the above error, simply run this command and then amend your 25411901Sjason@lowepower.comchangeset. 25511901Sjason@lowepower.com 25611901Sjason@lowepower.com > git commit --amend 25711901Sjason@lowepower.com 25811901Sjason@lowepower.comPush change to gerrit as a draft 25911901Sjason@lowepower.com-------------------------------- 26011901Sjason@lowepower.com 26111901Sjason@lowepower.com > git push origin HEAD:refs/drafts/master 26211901Sjason@lowepower.com 26311901Sjason@lowepower.comPush change bypassing gerrit 26411901Sjason@lowepower.com----------------------------- 26511901Sjason@lowepower.com 26611901Sjason@lowepower.comOnly maintainers can bypass gerrit review. This should very rarely be used. 26711901Sjason@lowepower.com 26811901Sjason@lowepower.com > git push origin HEAD:refs/heads/master 26911901Sjason@lowepower.com 27011901Sjason@lowepower.comOther gerrit push options 27111901Sjason@lowepower.com------------------------- 27211901Sjason@lowepower.com 27311901Sjason@lowepower.comThere are a number of options you can specify when uploading your changes to 27411901Sjason@lowepower.comgerrit (e.g., reviewers, labels). The gerrit documentation has more 27511901Sjason@lowepower.cominformation. 27611901Sjason@lowepower.comhttps://gerrit-review.googlesource.com/Documentation/user-upload.html 27711901Sjason@lowepower.com 27811901Sjason@lowepower.com 27911901Sjason@lowepower.comReviewing patches 28011901Sjason@lowepower.com================= 28111901Sjason@lowepower.com 28211901Sjason@lowepower.comReviewing patches is done on our gerrit instance at 28311901Sjason@lowepower.comhttps://gem5-review.googlesource.com/. 28411901Sjason@lowepower.com 28511901Sjason@lowepower.comAfter logging in with your Google account, you will be able to comment, review, 28611901Sjason@lowepower.comand push your own patches as well as review others' patches. All gem5 users are 28711901Sjason@lowepower.comencouraged to review patches. The only requirement to review patches is to be 28811901Sjason@lowepower.compolite and respectful of others. 28911901Sjason@lowepower.com 29011901Sjason@lowepower.comThere are multiple labels in Gerrit that can be applied to each review detailed 29111901Sjason@lowepower.combelow. 29211901Sjason@lowepower.com * Code-review: This is used by any gem5 user to review patches. When reviewing 29311901Sjason@lowepower.com a patch you can give it a score of -2 to +2 with the following semantics. 29411901Sjason@lowepower.com * -2: This blocks the patch. You believe that this patch should never be 29511901Sjason@lowepower.com committed. This label should be very rarely used. 29611901Sjason@lowepower.com * -1: You would prefer this is not merged as is 29711901Sjason@lowepower.com * 0: No score 29811901Sjason@lowepower.com * +1: This patch seems good, but you aren't 100% confident that it should be 29911901Sjason@lowepower.com pushed. 30011901Sjason@lowepower.com * +2: This is a good patch and should be pushed as is. 30111901Sjason@lowepower.com * Maintainer: Currently only PMC members are maintainers. At least one 30211901Sjason@lowepower.com maintainer must review your patch and give it a +1 before it can be merged. 30311901Sjason@lowepower.com * Verified: This is automatically generated from the continuous integrated 30411901Sjason@lowepower.com (CI) tests. Each patch must receive at least a +1 from the CI tests before 30511901Sjason@lowepower.com the patch can be merged. The patch will receive a +1 if gem5 builds and 30611901Sjason@lowepower.com runs, and it will receive a +2 if the stats match. 30711901Sjason@lowepower.com * Style-Check: This is automatically generated and tests the patch against the 30811901Sjason@lowepower.com gem5 code style (http://www.gem5.org/Coding_Style). The patch must receive a 30911901Sjason@lowepower.com +1 from the style checker to be pushed. 31011901Sjason@lowepower.com 31111901Sjason@lowepower.comNote: Whenever the patch creator updates the patch all reviewers must re-review 31211901Sjason@lowepower.comthe patch. There is no longer a "Fix it, then Ship It" option. 31311901Sjason@lowepower.com 31411901Sjason@lowepower.comOnce you have received reviews for your patch, you will likely need to make 31511901Sjason@lowepower.comchanges. To do this, you should update the original git changeset. Then, you 31611901Sjason@lowepower.comcan simply push the changeset again to the same Gerrit branch to update the 31711901Sjason@lowepower.comreview request. 31811901Sjason@lowepower.com 31911901Sjason@lowepower.com > git push origin HEAD:refs/for/master 32011901Sjason@lowepower.com 32111901Sjason@lowepower.comNote: If you have posted a patch and don't receive any reviews, you may need to 32211901Sjason@lowepower.comprod the reviewers. You can do this by adding a reply to your changeset review 32311901Sjason@lowepower.comon gerrit. It is expected that at least the maintainer will supply a review for 32411901Sjason@lowepower.comyour patch. 32511901Sjason@lowepower.com 32611901Sjason@lowepower.comCommitting changes 32711901Sjason@lowepower.com================== 32811901Sjason@lowepower.com 32911901Sjason@lowepower.comEach patch must meet the following criteria to be merged: 33011901Sjason@lowepower.com * At least one review with +2 33111901Sjason@lowepower.com * At least one maintainer with +1 33211901Sjason@lowepower.com * At least +1 from the CI tests (gem5 must build and run) 33311901Sjason@lowepower.com * At least +1 from the style checker 33411901Sjason@lowepower.com 33511901Sjason@lowepower.comOnce a patch meets the above criteria, the submitter of the patch will be able 33611901Sjason@lowepower.comto merge the patch by pressing the "Submit" button on Gerrit. When the patch is 33711901Sjason@lowepower.comsubmitted, it is merged into the public gem5 branch. 338