CONTRIBUTING.md revision 12562
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: 8212562Ssiddhesh.poyarekar@gmail.com``` 8312562Ssiddhesh.poyarekar@gmail.com git clone https://gem5.googlesource.com/public/gem5 8412562Ssiddhesh.poyarekar@gmail.com``` 8511901Sjason@lowepower.com 8611901Sjason@lowepower.comOther gem5 repositories 8711901Sjason@lowepower.com----------------------- 8811901Sjason@lowepower.com 8911901Sjason@lowepower.comThere are a few repositories other than the main gem5 development repository. 9011901Sjason@lowepower.com 9111901Sjason@lowepower.com * public/m5threads: The code for a pthreads implementation that works with 9211901Sjason@lowepower.com gem5's syscall emulation mode. 9311901Sjason@lowepower.com 9411901Sjason@lowepower.comOther gem5 branches 9511901Sjason@lowepower.com------------------- 9611901Sjason@lowepower.com 9711901Sjason@lowepower.comNone right now. 9811901Sjason@lowepower.com 9911901Sjason@lowepower.comMaking changes to gem5 10011901Sjason@lowepower.com====================== 10111901Sjason@lowepower.com 10211901Sjason@lowepower.comIt is strongly encouraged to use git branches when making changes to gem5. 10311901Sjason@lowepower.comAdditionally, keeping changes small and concise and only have a single logical 10411901Sjason@lowepower.comchange per commit. 10511901Sjason@lowepower.com 10611901Sjason@lowepower.comUnlike our previous flow with Mercurial and patch queues, when using git, you 10711901Sjason@lowepower.comwill be committing changes to your local branch. By using separate branches in 10811901Sjason@lowepower.comgit, you will be able to pull in and merge changes from mainline and simply 10911901Sjason@lowepower.comkeep up with upstream changes. 11011901Sjason@lowepower.com 11111901Sjason@lowepower.comRequirements for change descriptions 11211901Sjason@lowepower.com------------------------------------ 11311901Sjason@lowepower.comTo help reviewers and future contributors more easily understand and track 11411901Sjason@lowepower.comchanges, we require all change descriptions be strictly formatted. 11511901Sjason@lowepower.com 11611901Sjason@lowepower.comA canonical commit message consists of three parts: 11711901Sjason@lowepower.com * A short summary line describing the change. This line starts with one or 11811977Sjason@lowepower.com more keywords (found in the MAINTAINERS file) separated by commas followed 11911977Sjason@lowepower.com by a colon and a description of the change. This line should be no more than 12011977Sjason@lowepower.com 65 characters long since version control systems usually add a prefix that 12111977Sjason@lowepower.com causes line-wrapping for longer lines. 12211901Sjason@lowepower.com * (Optional, but highly recommended) A detailed description. This describes 12311901Sjason@lowepower.com what you have done and why. If the change isn't obvious, you might want to 12411901Sjason@lowepower.com motivate why it is needed. Lines need to be wrapped to 75 characters or 12511901Sjason@lowepower.com less. 12611901Sjason@lowepower.com * Tags describing patch metadata. You are highly recommended to use 12711901Sjason@lowepower.com tags to acknowledge reviewers for their work. Gerrit will automatically add 12811901Sjason@lowepower.com most tags. 12911901Sjason@lowepower.com 13011901Sjason@lowepower.comTags are an optional mechanism to store additional metadata about a patch and 13111901Sjason@lowepower.comacknowledge people who reported a bug or reviewed that patch. Tags are 13211901Sjason@lowepower.comgenerally appended to the end of the commit message in the order they happen. 13311901Sjason@lowepower.comWe currently use the following tags: 13411901Sjason@lowepower.com * Signed-off-by: Added by the author and the submitter (if different). 13511901Sjason@lowepower.com This tag is a statement saying that you believe the patch to be correct and 13611901Sjason@lowepower.com have the right to submit the patch according to the license in the affected 13711901Sjason@lowepower.com files. Similarly, if you commit someone else's patch, this tells the rest 13811901Sjason@lowepower.com of the world that you have have the right to forward it to the main 13911901Sjason@lowepower.com repository. If you need to make any changes at all to submit the change, 14011901Sjason@lowepower.com these should be described within hard brackets just before your 14111901Sjason@lowepower.com Signed-off-by tag. By adding this line, the contributor certifies the 14211901Sjason@lowepower.com contribution is made under the terms of the Developer Certificate of Origin 14311901Sjason@lowepower.com (DCO) [https://developercertificate.org/]. 14411901Sjason@lowepower.com * Reviewed-by: Used to acknowledge patch reviewers. It's generally considered 14511901Sjason@lowepower.com good form to add these. Added automatically. 14611901Sjason@lowepower.com * Reported-by: Used to acknowledge someone for finding and reporting a bug. 14711901Sjason@lowepower.com * Reviewed-on: Link to the review request corresponding to this patch. Added 14811901Sjason@lowepower.com automatically. 14911901Sjason@lowepower.com * Change-Id: Used by Gerrit to track changes across rebases. Added 15011901Sjason@lowepower.com automatically with a commit hook by git. 15111901Sjason@lowepower.com * Tested-by: Used to acknowledge people who tested a patch. Sometimes added 15211901Sjason@lowepower.com automatically by review systems that integrate with CI systems. 15311901Sjason@lowepower.com 15411901Sjason@lowepower.comOther than the "Signed-off-by", "Reported-by", and "Tested-by" tags, you 15511901Sjason@lowepower.comgenerally don't need to add these manually as they are added automatically by 15611901Sjason@lowepower.comGerrit. 15711901Sjason@lowepower.com 15811901Sjason@lowepower.comIt is encouraged for the author of the patch and the submitter to add a 15911901Sjason@lowepower.comSigned-off-by tag to the commit message. By adding this line, the contributor 16011901Sjason@lowepower.comcertifies the contribution is made under the terms of the Developer Certificate 16111901Sjason@lowepower.comof Origin (DCO) [https://developercertificate.org/]. 16211901Sjason@lowepower.com 16311901Sjason@lowepower.comIt is imperative that you use your real name and your real email address in 16411901Sjason@lowepower.comboth tags and in the author field of the changeset. 16511901Sjason@lowepower.com 16611921Spierre-yves.peneau@lirmm.frFor significant changes, authors are encouraged to add copyright information 16711921Spierre-yves.peneau@lirmm.frand their names at the beginning of the file. The main purpose of the author 16811921Spierre-yves.peneau@lirmm.frnames on the file is to track who is most knowledgeable about the file (e.g., 16911921Spierre-yves.peneau@lirmm.frwho has contributed a significant amount of code to the file). 17011921Spierre-yves.peneau@lirmm.fr 17111901Sjason@lowepower.comNote: If you do not follow these guidelines, the gerrit review site will 17211901Sjason@lowepower.comautomatically reject your patch. 17311901Sjason@lowepower.comIf this happens, update your changeset descriptions to match the required style 17411901Sjason@lowepower.comand resubmit. The following is a useful git command to update the most recent 17511901Sjason@lowepower.comcommit (HEAD). 17611901Sjason@lowepower.com 17712562Ssiddhesh.poyarekar@gmail.com``` 17812562Ssiddhesh.poyarekar@gmail.com git commit --amend 17912562Ssiddhesh.poyarekar@gmail.com``` 18011901Sjason@lowepower.com 18111901Sjason@lowepower.comPosting a review 18211901Sjason@lowepower.com================ 18311901Sjason@lowepower.com 18411901Sjason@lowepower.comIf you have not signed up for an account on the Gerrit review site 18511901Sjason@lowepower.com(https://gem5-review.googlesource.com), you first have to create an account. 18611901Sjason@lowepower.com 18711901Sjason@lowepower.comSetting up an account 18811901Sjason@lowepower.com--------------------- 18911901Sjason@lowepower.com 1. Go to https://gem5.googlesource.com/ 19011901Sjason@lowepower.com 2. Click "Sign In" in the upper right corner. Note: You will need a Google 19111901Sjason@lowepower.com account to contribute. 19211901Sjason@lowepower.com 3. After signing in, click "Generate Password" and follow the instructions. 19311901Sjason@lowepower.com 19411901Sjason@lowepower.comSubmitting a change 19511901Sjason@lowepower.com------------------- 19611901Sjason@lowepower.com 19711901Sjason@lowepower.comIn gerrit, to submit a review request, you can simply push your git commits to 19811901Sjason@lowepower.coma special named branch. For more information on git push see 19911901Sjason@lowepower.comhttps://git-scm.com/docs/git-push. 20011901Sjason@lowepower.com 20111901Sjason@lowepower.comThere are three ways to push your changes to gerrit. 20211901Sjason@lowepower.com 20311901Sjason@lowepower.comPush change to gerrit review 20411901Sjason@lowepower.com---------------------------- 20511901Sjason@lowepower.com 20612562Ssiddhesh.poyarekar@gmail.com``` 20712562Ssiddhesh.poyarekar@gmail.com git push origin HEAD:refs/for/master 20812562Ssiddhesh.poyarekar@gmail.com``` 20911901Sjason@lowepower.com 21011901Sjason@lowepower.comAssuming origin is https://gem5.googlesource.com/public/gem5 and you want to 21111901Sjason@lowepower.compush the changeset at HEAD, this will create a new review request on top of the 21211901Sjason@lowepower.commaster branch. More generally, 21311901Sjason@lowepower.com 21412562Ssiddhesh.poyarekar@gmail.com``` 21512562Ssiddhesh.poyarekar@gmail.com git push <gem5 gerrit instance> <changeset>:refs/for/<branch> 21612562Ssiddhesh.poyarekar@gmail.com``` 21711901Sjason@lowepower.com 21811901Sjason@lowepower.comSee https://gerrit-review.googlesource.com/Documentation/user-upload.html for 21911901Sjason@lowepower.commore information. 22011901Sjason@lowepower.com 22111901Sjason@lowepower.comPushing your first change 22211901Sjason@lowepower.com-------------------------- 22311901Sjason@lowepower.comThe first time you push a change you may get the following error: 22411901Sjason@lowepower.com 22512562Ssiddhesh.poyarekar@gmail.com``` 22612562Ssiddhesh.poyarekar@gmail.com remote: ERROR: [fb1366b] missing Change-Id in commit message footer 22712562Ssiddhesh.poyarekar@gmail.com ... 22812562Ssiddhesh.poyarekar@gmail.com``` 22911901Sjason@lowepower.com 23011901Sjason@lowepower.comWithin the error message, there is a command line you should run. For every new 23111901Sjason@lowepower.comclone of the git repo, you need to run the following command to automatically 23211901Sjason@lowepower.cominsert the change id in the the commit (all on one line). 23311901Sjason@lowepower.com 23412562Ssiddhesh.poyarekar@gmail.com``` 23512562Ssiddhesh.poyarekar@gmail.com curl -Lo `git rev-parse --git-dir`/hooks/commit-msg \ 23612562Ssiddhesh.poyarekar@gmail.com https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; \ 23712562Ssiddhesh.poyarekar@gmail.com chmod +x `git rev-parse --git-dir`/hooks/commit-msg 23812562Ssiddhesh.poyarekar@gmail.com``` 23911901Sjason@lowepower.com 24011901Sjason@lowepower.comIf you receive the above error, simply run this command and then amend your 24111901Sjason@lowepower.comchangeset. 24211901Sjason@lowepower.com 24312562Ssiddhesh.poyarekar@gmail.com``` 24412562Ssiddhesh.poyarekar@gmail.com git commit --amend 24512562Ssiddhesh.poyarekar@gmail.com``` 24611901Sjason@lowepower.com 24711901Sjason@lowepower.comPush change to gerrit as a draft 24811901Sjason@lowepower.com-------------------------------- 24911901Sjason@lowepower.com 25012562Ssiddhesh.poyarekar@gmail.com``` 25112562Ssiddhesh.poyarekar@gmail.com git push origin HEAD:refs/drafts/master 25212562Ssiddhesh.poyarekar@gmail.com``` 25311901Sjason@lowepower.com 25411901Sjason@lowepower.comPush change bypassing gerrit 25511901Sjason@lowepower.com----------------------------- 25611901Sjason@lowepower.com 25711901Sjason@lowepower.comOnly maintainers can bypass gerrit review. This should very rarely be used. 25811901Sjason@lowepower.com 25912562Ssiddhesh.poyarekar@gmail.com``` 26012562Ssiddhesh.poyarekar@gmail.com git push origin HEAD:refs/heads/master 26112562Ssiddhesh.poyarekar@gmail.com``` 26211901Sjason@lowepower.com 26311901Sjason@lowepower.comOther gerrit push options 26411901Sjason@lowepower.com------------------------- 26511901Sjason@lowepower.com 26611901Sjason@lowepower.comThere are a number of options you can specify when uploading your changes to 26711901Sjason@lowepower.comgerrit (e.g., reviewers, labels). The gerrit documentation has more 26811901Sjason@lowepower.cominformation. 26911901Sjason@lowepower.comhttps://gerrit-review.googlesource.com/Documentation/user-upload.html 27011901Sjason@lowepower.com 27111901Sjason@lowepower.com 27211901Sjason@lowepower.comReviewing patches 27311901Sjason@lowepower.com================= 27411901Sjason@lowepower.com 27511901Sjason@lowepower.comReviewing patches is done on our gerrit instance at 27611901Sjason@lowepower.comhttps://gem5-review.googlesource.com/. 27711901Sjason@lowepower.com 27811901Sjason@lowepower.comAfter logging in with your Google account, you will be able to comment, review, 27911901Sjason@lowepower.comand push your own patches as well as review others' patches. All gem5 users are 28011901Sjason@lowepower.comencouraged to review patches. The only requirement to review patches is to be 28111901Sjason@lowepower.compolite and respectful of others. 28211901Sjason@lowepower.com 28311901Sjason@lowepower.comThere are multiple labels in Gerrit that can be applied to each review detailed 28411901Sjason@lowepower.combelow. 28511901Sjason@lowepower.com * Code-review: This is used by any gem5 user to review patches. When reviewing 28611901Sjason@lowepower.com a patch you can give it a score of -2 to +2 with the following semantics. 28711901Sjason@lowepower.com * -2: This blocks the patch. You believe that this patch should never be 28811901Sjason@lowepower.com committed. This label should be very rarely used. 28911901Sjason@lowepower.com * -1: You would prefer this is not merged as is 29011901Sjason@lowepower.com * 0: No score 29111901Sjason@lowepower.com * +1: This patch seems good, but you aren't 100% confident that it should be 29211901Sjason@lowepower.com pushed. 29311901Sjason@lowepower.com * +2: This is a good patch and should be pushed as is. 29411901Sjason@lowepower.com * Maintainer: Currently only PMC members are maintainers. At least one 29511901Sjason@lowepower.com maintainer must review your patch and give it a +1 before it can be merged. 29611901Sjason@lowepower.com * Verified: This is automatically generated from the continuous integrated 29711901Sjason@lowepower.com (CI) tests. Each patch must receive at least a +1 from the CI tests before 29811901Sjason@lowepower.com the patch can be merged. The patch will receive a +1 if gem5 builds and 29911901Sjason@lowepower.com runs, and it will receive a +2 if the stats match. 30011901Sjason@lowepower.com * Style-Check: This is automatically generated and tests the patch against the 30111901Sjason@lowepower.com gem5 code style (http://www.gem5.org/Coding_Style). The patch must receive a 30211901Sjason@lowepower.com +1 from the style checker to be pushed. 30311901Sjason@lowepower.com 30411901Sjason@lowepower.comNote: Whenever the patch creator updates the patch all reviewers must re-review 30511901Sjason@lowepower.comthe patch. There is no longer a "Fix it, then Ship It" option. 30611901Sjason@lowepower.com 30711901Sjason@lowepower.comOnce you have received reviews for your patch, you will likely need to make 30811901Sjason@lowepower.comchanges. To do this, you should update the original git changeset. Then, you 30911901Sjason@lowepower.comcan simply push the changeset again to the same Gerrit branch to update the 31011901Sjason@lowepower.comreview request. 31111901Sjason@lowepower.com 31212562Ssiddhesh.poyarekar@gmail.com``` 31312562Ssiddhesh.poyarekar@gmail.com git push origin HEAD:refs/for/master 31412562Ssiddhesh.poyarekar@gmail.com``` 31511901Sjason@lowepower.com 31611901Sjason@lowepower.comNote: If you have posted a patch and don't receive any reviews, you may need to 31711901Sjason@lowepower.comprod the reviewers. You can do this by adding a reply to your changeset review 31811901Sjason@lowepower.comon gerrit. It is expected that at least the maintainer will supply a review for 31911901Sjason@lowepower.comyour patch. 32011901Sjason@lowepower.com 32111901Sjason@lowepower.comCommitting changes 32211901Sjason@lowepower.com================== 32311901Sjason@lowepower.com 32411901Sjason@lowepower.comEach patch must meet the following criteria to be merged: 32511901Sjason@lowepower.com * At least one review with +2 32611901Sjason@lowepower.com * At least one maintainer with +1 32711901Sjason@lowepower.com * At least +1 from the CI tests (gem5 must build and run) 32811901Sjason@lowepower.com * At least +1 from the style checker 32911901Sjason@lowepower.com 33011901Sjason@lowepower.comOnce a patch meets the above criteria, the submitter of the patch will be able 33111901Sjason@lowepower.comto merge the patch by pressing the "Submit" button on Gerrit. When the patch is 33211901Sjason@lowepower.comsubmitted, it is merged into the public gem5 branch. 333