CONTRIBUTING.md revision 11977
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 11611977Sjason@lowepower.com more keywords (found in the MAINTAINERS file) separated by commas followed 11711977Sjason@lowepower.com by a colon and a description of the change. This line should be no more than 11811977Sjason@lowepower.com 65 characters long since version control systems usually add a prefix that 11911977Sjason@lowepower.com causes line-wrapping for 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.comTags are an optional mechanism to store additional metadata about a patch and 12911901Sjason@lowepower.comacknowledge people who reported a bug or reviewed that patch. Tags are 13011901Sjason@lowepower.comgenerally appended to the end of the commit message in the order they happen. 13111901Sjason@lowepower.comWe currently use the following tags: 13211901Sjason@lowepower.com * Signed-off-by: Added by the author and the submitter (if different). 13311901Sjason@lowepower.com This tag is a statement saying that you believe the patch to be correct and 13411901Sjason@lowepower.com have the right to submit the patch according to the license in the affected 13511901Sjason@lowepower.com files. Similarly, if you commit someone else's patch, this tells the rest 13611901Sjason@lowepower.com of the world that you have have the right to forward it to the main 13711901Sjason@lowepower.com repository. If you need to make any changes at all to submit the change, 13811901Sjason@lowepower.com these should be described within hard brackets just before your 13911901Sjason@lowepower.com Signed-off-by tag. By adding this line, the contributor certifies the 14011901Sjason@lowepower.com contribution is made under the terms of the Developer Certificate of Origin 14111901Sjason@lowepower.com (DCO) [https://developercertificate.org/]. 14211901Sjason@lowepower.com * Reviewed-by: Used to acknowledge patch reviewers. It's generally considered 14311901Sjason@lowepower.com good form to add these. Added automatically. 14411901Sjason@lowepower.com * Reported-by: Used to acknowledge someone for finding and reporting a bug. 14511901Sjason@lowepower.com * Reviewed-on: Link to the review request corresponding to this patch. Added 14611901Sjason@lowepower.com automatically. 14711901Sjason@lowepower.com * Change-Id: Used by Gerrit to track changes across rebases. Added 14811901Sjason@lowepower.com automatically with a commit hook by git. 14911901Sjason@lowepower.com * Tested-by: Used to acknowledge people who tested a patch. Sometimes added 15011901Sjason@lowepower.com automatically by review systems that integrate with CI systems. 15111901Sjason@lowepower.com 15211901Sjason@lowepower.comOther than the "Signed-off-by", "Reported-by", and "Tested-by" tags, you 15311901Sjason@lowepower.comgenerally don't need to add these manually as they are added automatically by 15411901Sjason@lowepower.comGerrit. 15511901Sjason@lowepower.com 15611901Sjason@lowepower.comIt is encouraged for the author of the patch and the submitter to add a 15711901Sjason@lowepower.comSigned-off-by tag to the commit message. By adding this line, the contributor 15811901Sjason@lowepower.comcertifies the contribution is made under the terms of the Developer Certificate 15911901Sjason@lowepower.comof Origin (DCO) [https://developercertificate.org/]. 16011901Sjason@lowepower.com 16111901Sjason@lowepower.comIt is imperative that you use your real name and your real email address in 16211901Sjason@lowepower.comboth tags and in the author field of the changeset. 16311901Sjason@lowepower.com 16411921Spierre-yves.peneau@lirmm.frFor significant changes, authors are encouraged to add copyright information 16511921Spierre-yves.peneau@lirmm.frand their names at the beginning of the file. The main purpose of the author 16611921Spierre-yves.peneau@lirmm.frnames on the file is to track who is most knowledgeable about the file (e.g., 16711921Spierre-yves.peneau@lirmm.frwho has contributed a significant amount of code to the file). 16811921Spierre-yves.peneau@lirmm.fr 16911901Sjason@lowepower.comNote: If you do not follow these guidelines, the gerrit review site will 17011901Sjason@lowepower.comautomatically reject your patch. 17111901Sjason@lowepower.comIf this happens, update your changeset descriptions to match the required style 17211901Sjason@lowepower.comand resubmit. The following is a useful git command to update the most recent 17311901Sjason@lowepower.comcommit (HEAD). 17411901Sjason@lowepower.com 17511901Sjason@lowepower.com > git commit --amend 17611901Sjason@lowepower.com 17711901Sjason@lowepower.comPosting a review 17811901Sjason@lowepower.com================ 17911901Sjason@lowepower.com 18011901Sjason@lowepower.comIf you have not signed up for an account on the Gerrit review site 18111901Sjason@lowepower.com(https://gem5-review.googlesource.com), you first have to create an account. 18211901Sjason@lowepower.com 18311901Sjason@lowepower.comSetting up an account 18411901Sjason@lowepower.com--------------------- 18511901Sjason@lowepower.com 1. Go to https://gem5.googlesource.com/ 18611901Sjason@lowepower.com 2. Click "Sign In" in the upper right corner. Note: You will need a Google 18711901Sjason@lowepower.com account to contribute. 18811901Sjason@lowepower.com 3. After signing in, click "Generate Password" and follow the instructions. 18911901Sjason@lowepower.com 19011901Sjason@lowepower.comSubmitting a change 19111901Sjason@lowepower.com------------------- 19211901Sjason@lowepower.com 19311901Sjason@lowepower.comIn gerrit, to submit a review request, you can simply push your git commits to 19411901Sjason@lowepower.coma special named branch. For more information on git push see 19511901Sjason@lowepower.comhttps://git-scm.com/docs/git-push. 19611901Sjason@lowepower.com 19711901Sjason@lowepower.comThere are three ways to push your changes to gerrit. 19811901Sjason@lowepower.com 19911901Sjason@lowepower.comPush change to gerrit review 20011901Sjason@lowepower.com---------------------------- 20111901Sjason@lowepower.com 20211901Sjason@lowepower.com > git push origin HEAD:refs/for/master 20311901Sjason@lowepower.com 20411901Sjason@lowepower.comAssuming origin is https://gem5.googlesource.com/public/gem5 and you want to 20511901Sjason@lowepower.compush the changeset at HEAD, this will create a new review request on top of the 20611901Sjason@lowepower.commaster branch. More generally, 20711901Sjason@lowepower.com 20811901Sjason@lowepower.com > git push <gem5 gerrit instance> <changeset>:refs/for/<branch> 20911901Sjason@lowepower.com 21011901Sjason@lowepower.comSee https://gerrit-review.googlesource.com/Documentation/user-upload.html for 21111901Sjason@lowepower.commore information. 21211901Sjason@lowepower.com 21311901Sjason@lowepower.comPushing your first change 21411901Sjason@lowepower.com-------------------------- 21511901Sjason@lowepower.comThe first time you push a change you may get the following error: 21611901Sjason@lowepower.com 21711901Sjason@lowepower.com > remote: ERROR: [fb1366b] missing Change-Id in commit message footer 21811901Sjason@lowepower.com > ... 21911901Sjason@lowepower.com 22011901Sjason@lowepower.comWithin the error message, there is a command line you should run. For every new 22111901Sjason@lowepower.comclone of the git repo, you need to run the following command to automatically 22211901Sjason@lowepower.cominsert the change id in the the commit (all on one line). 22311901Sjason@lowepower.com 22411901Sjason@lowepower.com > curl -Lo `git rev-parse --git-dir`/hooks/commit-msg 22511901Sjason@lowepower.com https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; chmod +x 22611901Sjason@lowepower.com `git rev-parse --git-dir`/hooks/commit-msg 22711901Sjason@lowepower.com 22811901Sjason@lowepower.comIf you receive the above error, simply run this command and then amend your 22911901Sjason@lowepower.comchangeset. 23011901Sjason@lowepower.com 23111901Sjason@lowepower.com > git commit --amend 23211901Sjason@lowepower.com 23311901Sjason@lowepower.comPush change to gerrit as a draft 23411901Sjason@lowepower.com-------------------------------- 23511901Sjason@lowepower.com 23611901Sjason@lowepower.com > git push origin HEAD:refs/drafts/master 23711901Sjason@lowepower.com 23811901Sjason@lowepower.comPush change bypassing gerrit 23911901Sjason@lowepower.com----------------------------- 24011901Sjason@lowepower.com 24111901Sjason@lowepower.comOnly maintainers can bypass gerrit review. This should very rarely be used. 24211901Sjason@lowepower.com 24311901Sjason@lowepower.com > git push origin HEAD:refs/heads/master 24411901Sjason@lowepower.com 24511901Sjason@lowepower.comOther gerrit push options 24611901Sjason@lowepower.com------------------------- 24711901Sjason@lowepower.com 24811901Sjason@lowepower.comThere are a number of options you can specify when uploading your changes to 24911901Sjason@lowepower.comgerrit (e.g., reviewers, labels). The gerrit documentation has more 25011901Sjason@lowepower.cominformation. 25111901Sjason@lowepower.comhttps://gerrit-review.googlesource.com/Documentation/user-upload.html 25211901Sjason@lowepower.com 25311901Sjason@lowepower.com 25411901Sjason@lowepower.comReviewing patches 25511901Sjason@lowepower.com================= 25611901Sjason@lowepower.com 25711901Sjason@lowepower.comReviewing patches is done on our gerrit instance at 25811901Sjason@lowepower.comhttps://gem5-review.googlesource.com/. 25911901Sjason@lowepower.com 26011901Sjason@lowepower.comAfter logging in with your Google account, you will be able to comment, review, 26111901Sjason@lowepower.comand push your own patches as well as review others' patches. All gem5 users are 26211901Sjason@lowepower.comencouraged to review patches. The only requirement to review patches is to be 26311901Sjason@lowepower.compolite and respectful of others. 26411901Sjason@lowepower.com 26511901Sjason@lowepower.comThere are multiple labels in Gerrit that can be applied to each review detailed 26611901Sjason@lowepower.combelow. 26711901Sjason@lowepower.com * Code-review: This is used by any gem5 user to review patches. When reviewing 26811901Sjason@lowepower.com a patch you can give it a score of -2 to +2 with the following semantics. 26911901Sjason@lowepower.com * -2: This blocks the patch. You believe that this patch should never be 27011901Sjason@lowepower.com committed. This label should be very rarely used. 27111901Sjason@lowepower.com * -1: You would prefer this is not merged as is 27211901Sjason@lowepower.com * 0: No score 27311901Sjason@lowepower.com * +1: This patch seems good, but you aren't 100% confident that it should be 27411901Sjason@lowepower.com pushed. 27511901Sjason@lowepower.com * +2: This is a good patch and should be pushed as is. 27611901Sjason@lowepower.com * Maintainer: Currently only PMC members are maintainers. At least one 27711901Sjason@lowepower.com maintainer must review your patch and give it a +1 before it can be merged. 27811901Sjason@lowepower.com * Verified: This is automatically generated from the continuous integrated 27911901Sjason@lowepower.com (CI) tests. Each patch must receive at least a +1 from the CI tests before 28011901Sjason@lowepower.com the patch can be merged. The patch will receive a +1 if gem5 builds and 28111901Sjason@lowepower.com runs, and it will receive a +2 if the stats match. 28211901Sjason@lowepower.com * Style-Check: This is automatically generated and tests the patch against the 28311901Sjason@lowepower.com gem5 code style (http://www.gem5.org/Coding_Style). The patch must receive a 28411901Sjason@lowepower.com +1 from the style checker to be pushed. 28511901Sjason@lowepower.com 28611901Sjason@lowepower.comNote: Whenever the patch creator updates the patch all reviewers must re-review 28711901Sjason@lowepower.comthe patch. There is no longer a "Fix it, then Ship It" option. 28811901Sjason@lowepower.com 28911901Sjason@lowepower.comOnce you have received reviews for your patch, you will likely need to make 29011901Sjason@lowepower.comchanges. To do this, you should update the original git changeset. Then, you 29111901Sjason@lowepower.comcan simply push the changeset again to the same Gerrit branch to update the 29211901Sjason@lowepower.comreview request. 29311901Sjason@lowepower.com 29411901Sjason@lowepower.com > git push origin HEAD:refs/for/master 29511901Sjason@lowepower.com 29611901Sjason@lowepower.comNote: If you have posted a patch and don't receive any reviews, you may need to 29711901Sjason@lowepower.comprod the reviewers. You can do this by adding a reply to your changeset review 29811901Sjason@lowepower.comon gerrit. It is expected that at least the maintainer will supply a review for 29911901Sjason@lowepower.comyour patch. 30011901Sjason@lowepower.com 30111901Sjason@lowepower.comCommitting changes 30211901Sjason@lowepower.com================== 30311901Sjason@lowepower.com 30411901Sjason@lowepower.comEach patch must meet the following criteria to be merged: 30511901Sjason@lowepower.com * At least one review with +2 30611901Sjason@lowepower.com * At least one maintainer with +1 30711901Sjason@lowepower.com * At least +1 from the CI tests (gem5 must build and run) 30811901Sjason@lowepower.com * At least +1 from the style checker 30911901Sjason@lowepower.com 31011901Sjason@lowepower.comOnce a patch meets the above criteria, the submitter of the patch will be able 31111901Sjason@lowepower.comto merge the patch by pressing the "Submit" button on Gerrit. When the patch is 31211901Sjason@lowepower.comsubmitted, it is merged into the public gem5 branch. 313