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 3912883Sjason@lowepower.com +-------------+ 4012883Sjason@lowepower.com | Run tests |<--------------+ 4112883Sjason@lowepower.com +------+------+ | 4212883Sjason@lowepower.com | | 4312883Sjason@lowepower.com | | 4412883Sjason@lowepower.com v | 4512883Sjason@lowepower.com +------+------+ | 4612883Sjason@lowepower.com | Post review | | 4712883Sjason@lowepower.com +------+------+ | 4812883Sjason@lowepower.com | | 4912883Sjason@lowepower.com v | 5012883Sjason@lowepower.com +--------+---------+ | 5112883Sjason@lowepower.com | Wait for reviews | | 5211901Sjason@lowepower.com +--------+---------+ | 5311901Sjason@lowepower.com | | 5411901Sjason@lowepower.com | | 5511901Sjason@lowepower.com v | 5611901Sjason@lowepower.com +----+----+ No +------+------+ 5711901Sjason@lowepower.com |Reviewers+--------->+ Update code | 5811901Sjason@lowepower.com |happy? | +------+------+ 5911901Sjason@lowepower.com +----+----+ ^ 6011901Sjason@lowepower.com | | 6111901Sjason@lowepower.com | Yes | 6211901Sjason@lowepower.com v | 6311901Sjason@lowepower.com +----+-----+ No | 6411901Sjason@lowepower.com |Maintainer+----------------+ 6511901Sjason@lowepower.com |happy? | 6611901Sjason@lowepower.com +----+-----+ 6711901Sjason@lowepower.com | 6811901Sjason@lowepower.com | Yes 6911901Sjason@lowepower.com v 7011901Sjason@lowepower.com +------+------+ 7111901Sjason@lowepower.com | Submit code | 7211901Sjason@lowepower.com +-------------+ 7311901Sjason@lowepower.com 7411901Sjason@lowepower.comAfter creating your change to gem5, you can post a review on our Gerrit 7511901Sjason@lowepower.comcode-review site: https://gem5-review.googlesource.com. Before being able to 7611901Sjason@lowepower.comsubmit your code to the mainline of gem5, the code is reviewed by others in the 7711901Sjason@lowepower.comcommunity. Additionally, the maintainer for that part of the code must sign off 7811901Sjason@lowepower.comon it. 7911901Sjason@lowepower.com 8013398Santhony.gutierrez@amd.comContributing long-lived feature branches 8113398Santhony.gutierrez@amd.com---------------------------------------- 8213398Santhony.gutierrez@amd.comOftentimes users or institutions add features that are necessarily complex, 8313398Santhony.gutierrez@amd.comand require many changes on long-lived feature branches. In this case, 8413398Santhony.gutierrez@amd.commaintaining a perfect history where all changes work individually is infeasible. 8513398Santhony.gutierrez@amd.comWhen contributing long-lived feature branches back to gem5's public repository 8613398Santhony.gutierrez@amd.comusers may merge entire long-lived branches into a single changeset and contribute 8713398Santhony.gutierrez@amd.comtheir code back as long as 1) the changes have been reviewed by the maintainer 8813398Santhony.gutierrez@amd.com2) the maintainer agrees to allow such a change, and 3) the changes are passing 8913398Santhony.gutierrez@amd.comthe public tests. Changes that affect common code (outside of a specific 9013398Santhony.gutierrez@amd.commaintainer's purview) will still need to follow the standard gem5 protocol. 9113398Santhony.gutierrez@amd.com 9213398Santhony.gutierrez@amd.com 9311901Sjason@lowepower.comCloning the gem5 repo to contribute 9411901Sjason@lowepower.com=================================== 9511901Sjason@lowepower.com 9611901Sjason@lowepower.comIf you plan on contributing, it is strongly encouraged for you to clone the 9711901Sjason@lowepower.comrepository directly from our gerrit instance at 9811901Sjason@lowepower.comhttps://gem5.googlesource.com/. 9911901Sjason@lowepower.com 10011901Sjason@lowepower.comTo clone the master gem5 repository: 10112562Ssiddhesh.poyarekar@gmail.com``` 10212562Ssiddhesh.poyarekar@gmail.com git clone https://gem5.googlesource.com/public/gem5 10312562Ssiddhesh.poyarekar@gmail.com``` 10411901Sjason@lowepower.com 10511901Sjason@lowepower.comOther gem5 repositories 10611901Sjason@lowepower.com----------------------- 10711901Sjason@lowepower.com 10811901Sjason@lowepower.comThere are a few repositories other than the main gem5 development repository. 10911901Sjason@lowepower.com 11011901Sjason@lowepower.com * public/m5threads: The code for a pthreads implementation that works with 11111901Sjason@lowepower.com gem5's syscall emulation mode. 11211901Sjason@lowepower.com 11311901Sjason@lowepower.comOther gem5 branches 11411901Sjason@lowepower.com------------------- 11511901Sjason@lowepower.com 11611901Sjason@lowepower.comNone right now. 11711901Sjason@lowepower.com 11811901Sjason@lowepower.comMaking changes to gem5 11911901Sjason@lowepower.com====================== 12011901Sjason@lowepower.com 12111901Sjason@lowepower.comIt is strongly encouraged to use git branches when making changes to gem5. 12211901Sjason@lowepower.comAdditionally, keeping changes small and concise and only have a single logical 12311901Sjason@lowepower.comchange per commit. 12411901Sjason@lowepower.com 12511901Sjason@lowepower.comUnlike our previous flow with Mercurial and patch queues, when using git, you 12611901Sjason@lowepower.comwill be committing changes to your local branch. By using separate branches in 12711901Sjason@lowepower.comgit, you will be able to pull in and merge changes from mainline and simply 12811901Sjason@lowepower.comkeep up with upstream changes. 12911901Sjason@lowepower.com 13011901Sjason@lowepower.comRequirements for change descriptions 13111901Sjason@lowepower.com------------------------------------ 13211901Sjason@lowepower.comTo help reviewers and future contributors more easily understand and track 13311901Sjason@lowepower.comchanges, we require all change descriptions be strictly formatted. 13411901Sjason@lowepower.com 13511901Sjason@lowepower.comA canonical commit message consists of three parts: 13611901Sjason@lowepower.com * A short summary line describing the change. This line starts with one or 13711977Sjason@lowepower.com more keywords (found in the MAINTAINERS file) separated by commas followed 13811977Sjason@lowepower.com by a colon and a description of the change. This line should be no more than 13911977Sjason@lowepower.com 65 characters long since version control systems usually add a prefix that 14011977Sjason@lowepower.com causes line-wrapping for longer lines. 14111901Sjason@lowepower.com * (Optional, but highly recommended) A detailed description. This describes 14211901Sjason@lowepower.com what you have done and why. If the change isn't obvious, you might want to 14311901Sjason@lowepower.com motivate why it is needed. Lines need to be wrapped to 75 characters or 14411901Sjason@lowepower.com less. 14511901Sjason@lowepower.com * Tags describing patch metadata. You are highly recommended to use 14611901Sjason@lowepower.com tags to acknowledge reviewers for their work. Gerrit will automatically add 14711901Sjason@lowepower.com most tags. 14811901Sjason@lowepower.com 14911901Sjason@lowepower.comTags are an optional mechanism to store additional metadata about a patch and 15011901Sjason@lowepower.comacknowledge people who reported a bug or reviewed that patch. Tags are 15111901Sjason@lowepower.comgenerally appended to the end of the commit message in the order they happen. 15211901Sjason@lowepower.comWe currently use the following tags: 15311901Sjason@lowepower.com * Signed-off-by: Added by the author and the submitter (if different). 15411901Sjason@lowepower.com This tag is a statement saying that you believe the patch to be correct and 15511901Sjason@lowepower.com have the right to submit the patch according to the license in the affected 15611901Sjason@lowepower.com files. Similarly, if you commit someone else's patch, this tells the rest 15711901Sjason@lowepower.com of the world that you have have the right to forward it to the main 15811901Sjason@lowepower.com repository. If you need to make any changes at all to submit the change, 15911901Sjason@lowepower.com these should be described within hard brackets just before your 16011901Sjason@lowepower.com Signed-off-by tag. By adding this line, the contributor certifies the 16111901Sjason@lowepower.com contribution is made under the terms of the Developer Certificate of Origin 16211901Sjason@lowepower.com (DCO) [https://developercertificate.org/]. 16311901Sjason@lowepower.com * Reviewed-by: Used to acknowledge patch reviewers. It's generally considered 16411901Sjason@lowepower.com good form to add these. Added automatically. 16511901Sjason@lowepower.com * Reported-by: Used to acknowledge someone for finding and reporting a bug. 16611901Sjason@lowepower.com * Reviewed-on: Link to the review request corresponding to this patch. Added 16711901Sjason@lowepower.com automatically. 16811901Sjason@lowepower.com * Change-Id: Used by Gerrit to track changes across rebases. Added 16911901Sjason@lowepower.com automatically with a commit hook by git. 17011901Sjason@lowepower.com * Tested-by: Used to acknowledge people who tested a patch. Sometimes added 17111901Sjason@lowepower.com automatically by review systems that integrate with CI systems. 17211901Sjason@lowepower.com 17311901Sjason@lowepower.comOther than the "Signed-off-by", "Reported-by", and "Tested-by" tags, you 17411901Sjason@lowepower.comgenerally don't need to add these manually as they are added automatically by 17511901Sjason@lowepower.comGerrit. 17611901Sjason@lowepower.com 17711901Sjason@lowepower.comIt is encouraged for the author of the patch and the submitter to add a 17811901Sjason@lowepower.comSigned-off-by tag to the commit message. By adding this line, the contributor 17911901Sjason@lowepower.comcertifies the contribution is made under the terms of the Developer Certificate 18011901Sjason@lowepower.comof Origin (DCO) [https://developercertificate.org/]. 18111901Sjason@lowepower.com 18211901Sjason@lowepower.comIt is imperative that you use your real name and your real email address in 18311901Sjason@lowepower.comboth tags and in the author field of the changeset. 18411901Sjason@lowepower.com 18511921Spierre-yves.peneau@lirmm.frFor significant changes, authors are encouraged to add copyright information 18611921Spierre-yves.peneau@lirmm.frand their names at the beginning of the file. The main purpose of the author 18711921Spierre-yves.peneau@lirmm.frnames on the file is to track who is most knowledgeable about the file (e.g., 18811921Spierre-yves.peneau@lirmm.frwho has contributed a significant amount of code to the file). 18911921Spierre-yves.peneau@lirmm.fr 19011901Sjason@lowepower.comNote: If you do not follow these guidelines, the gerrit review site will 19111901Sjason@lowepower.comautomatically reject your patch. 19211901Sjason@lowepower.comIf this happens, update your changeset descriptions to match the required style 19311901Sjason@lowepower.comand resubmit. The following is a useful git command to update the most recent 19411901Sjason@lowepower.comcommit (HEAD). 19511901Sjason@lowepower.com 19612562Ssiddhesh.poyarekar@gmail.com``` 19712562Ssiddhesh.poyarekar@gmail.com git commit --amend 19812562Ssiddhesh.poyarekar@gmail.com``` 19911901Sjason@lowepower.com 20012883Sjason@lowepower.comRunning tests 20112883Sjason@lowepower.com============= 20212883Sjason@lowepower.com 20312883Sjason@lowepower.comBefore posting a change to the code review site, you should always run the 20412883Sjason@lowepower.comquick tests! 20512883Sjason@lowepower.comSee TESTING.md for more information. 20612883Sjason@lowepower.com 20711901Sjason@lowepower.comPosting a review 20811901Sjason@lowepower.com================ 20911901Sjason@lowepower.com 21011901Sjason@lowepower.comIf you have not signed up for an account on the Gerrit review site 21111901Sjason@lowepower.com(https://gem5-review.googlesource.com), you first have to create an account. 21211901Sjason@lowepower.com 21311901Sjason@lowepower.comSetting up an account 21411901Sjason@lowepower.com--------------------- 21511901Sjason@lowepower.com 1. Go to https://gem5.googlesource.com/ 21611901Sjason@lowepower.com 2. Click "Sign In" in the upper right corner. Note: You will need a Google 21711901Sjason@lowepower.com account to contribute. 21811901Sjason@lowepower.com 3. After signing in, click "Generate Password" and follow the instructions. 21911901Sjason@lowepower.com 22011901Sjason@lowepower.comSubmitting a change 22111901Sjason@lowepower.com------------------- 22211901Sjason@lowepower.com 22311901Sjason@lowepower.comIn gerrit, to submit a review request, you can simply push your git commits to 22411901Sjason@lowepower.coma special named branch. For more information on git push see 22511901Sjason@lowepower.comhttps://git-scm.com/docs/git-push. 22611901Sjason@lowepower.com 22711901Sjason@lowepower.comThere are three ways to push your changes to gerrit. 22811901Sjason@lowepower.com 22911901Sjason@lowepower.comPush change to gerrit review 23011901Sjason@lowepower.com---------------------------- 23111901Sjason@lowepower.com 23212562Ssiddhesh.poyarekar@gmail.com``` 23312562Ssiddhesh.poyarekar@gmail.com git push origin HEAD:refs/for/master 23412562Ssiddhesh.poyarekar@gmail.com``` 23511901Sjason@lowepower.com 23611901Sjason@lowepower.comAssuming origin is https://gem5.googlesource.com/public/gem5 and you want to 23711901Sjason@lowepower.compush the changeset at HEAD, this will create a new review request on top of the 23811901Sjason@lowepower.commaster branch. More generally, 23911901Sjason@lowepower.com 24012562Ssiddhesh.poyarekar@gmail.com``` 24112562Ssiddhesh.poyarekar@gmail.com git push <gem5 gerrit instance> <changeset>:refs/for/<branch> 24212562Ssiddhesh.poyarekar@gmail.com``` 24311901Sjason@lowepower.com 24411901Sjason@lowepower.comSee https://gerrit-review.googlesource.com/Documentation/user-upload.html for 24511901Sjason@lowepower.commore information. 24611901Sjason@lowepower.com 24711901Sjason@lowepower.comPushing your first change 24811901Sjason@lowepower.com-------------------------- 24911901Sjason@lowepower.comThe first time you push a change you may get the following error: 25011901Sjason@lowepower.com 25112562Ssiddhesh.poyarekar@gmail.com``` 25212562Ssiddhesh.poyarekar@gmail.com remote: ERROR: [fb1366b] missing Change-Id in commit message footer 25312562Ssiddhesh.poyarekar@gmail.com ... 25412562Ssiddhesh.poyarekar@gmail.com``` 25511901Sjason@lowepower.com 25611901Sjason@lowepower.comWithin the error message, there is a command line you should run. For every new 25711901Sjason@lowepower.comclone of the git repo, you need to run the following command to automatically 25811901Sjason@lowepower.cominsert the change id in the the commit (all on one line). 25911901Sjason@lowepower.com 26012562Ssiddhesh.poyarekar@gmail.com``` 26112562Ssiddhesh.poyarekar@gmail.com curl -Lo `git rev-parse --git-dir`/hooks/commit-msg \ 26212562Ssiddhesh.poyarekar@gmail.com https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; \ 26312562Ssiddhesh.poyarekar@gmail.com chmod +x `git rev-parse --git-dir`/hooks/commit-msg 26412562Ssiddhesh.poyarekar@gmail.com``` 26511901Sjason@lowepower.com 26611901Sjason@lowepower.comIf you receive the above error, simply run this command and then amend your 26711901Sjason@lowepower.comchangeset. 26811901Sjason@lowepower.com 26912562Ssiddhesh.poyarekar@gmail.com``` 27012562Ssiddhesh.poyarekar@gmail.com git commit --amend 27112562Ssiddhesh.poyarekar@gmail.com``` 27211901Sjason@lowepower.com 27312847Sjason@lowepower.comPush change to gerrit as a draft/private 27412847Sjason@lowepower.com---------------------------------------- 27512847Sjason@lowepower.com 27612847Sjason@lowepower.comSee https://gerrit-review.googlesource.com/Documentation/intro-user.html#private-changes 27712847Sjason@lowepower.comfor details on private gerrit changes. 27811901Sjason@lowepower.com 27912562Ssiddhesh.poyarekar@gmail.com``` 28012847Sjason@lowepower.com git push origin HEAD:refs/for/master%private 28112562Ssiddhesh.poyarekar@gmail.com``` 28211901Sjason@lowepower.com 28312847Sjason@lowepower.comOnce you have pushed your change as "private", you can log onto [gerrit] 28412847Sjason@lowepower.com(https://gem5-review.googlesource.com) and once you're happy with the commit 28512847Sjason@lowepower.comclick the "unmark private" which may be hidden in the "more options" dropdown 28612847Sjason@lowepower.comin the upper right corner. 28712847Sjason@lowepower.com 28811901Sjason@lowepower.comPush change bypassing gerrit 28911901Sjason@lowepower.com----------------------------- 29011901Sjason@lowepower.com 29111901Sjason@lowepower.comOnly maintainers can bypass gerrit review. This should very rarely be used. 29211901Sjason@lowepower.com 29312562Ssiddhesh.poyarekar@gmail.com``` 29412562Ssiddhesh.poyarekar@gmail.com git push origin HEAD:refs/heads/master 29512562Ssiddhesh.poyarekar@gmail.com``` 29611901Sjason@lowepower.com 29711901Sjason@lowepower.comOther gerrit push options 29811901Sjason@lowepower.com------------------------- 29911901Sjason@lowepower.com 30011901Sjason@lowepower.comThere are a number of options you can specify when uploading your changes to 30111901Sjason@lowepower.comgerrit (e.g., reviewers, labels). The gerrit documentation has more 30211901Sjason@lowepower.cominformation. 30311901Sjason@lowepower.comhttps://gerrit-review.googlesource.com/Documentation/user-upload.html 30411901Sjason@lowepower.com 30511901Sjason@lowepower.com 30611901Sjason@lowepower.comReviewing patches 30711901Sjason@lowepower.com================= 30811901Sjason@lowepower.com 30911901Sjason@lowepower.comReviewing patches is done on our gerrit instance at 31011901Sjason@lowepower.comhttps://gem5-review.googlesource.com/. 31111901Sjason@lowepower.com 31211901Sjason@lowepower.comAfter logging in with your Google account, you will be able to comment, review, 31311901Sjason@lowepower.comand push your own patches as well as review others' patches. All gem5 users are 31411901Sjason@lowepower.comencouraged to review patches. The only requirement to review patches is to be 31511901Sjason@lowepower.compolite and respectful of others. 31611901Sjason@lowepower.com 31711901Sjason@lowepower.comThere are multiple labels in Gerrit that can be applied to each review detailed 31811901Sjason@lowepower.combelow. 31911901Sjason@lowepower.com * Code-review: This is used by any gem5 user to review patches. When reviewing 32011901Sjason@lowepower.com a patch you can give it a score of -2 to +2 with the following semantics. 32111901Sjason@lowepower.com * -2: This blocks the patch. You believe that this patch should never be 32211901Sjason@lowepower.com committed. This label should be very rarely used. 32311901Sjason@lowepower.com * -1: You would prefer this is not merged as is 32411901Sjason@lowepower.com * 0: No score 32511901Sjason@lowepower.com * +1: This patch seems good, but you aren't 100% confident that it should be 32611901Sjason@lowepower.com pushed. 32711901Sjason@lowepower.com * +2: This is a good patch and should be pushed as is. 32811901Sjason@lowepower.com * Maintainer: Currently only PMC members are maintainers. At least one 32911901Sjason@lowepower.com maintainer must review your patch and give it a +1 before it can be merged. 33011901Sjason@lowepower.com * Verified: This is automatically generated from the continuous integrated 33111901Sjason@lowepower.com (CI) tests. Each patch must receive at least a +1 from the CI tests before 33211901Sjason@lowepower.com the patch can be merged. The patch will receive a +1 if gem5 builds and 33311901Sjason@lowepower.com runs, and it will receive a +2 if the stats match. 33411901Sjason@lowepower.com * Style-Check: This is automatically generated and tests the patch against the 33511901Sjason@lowepower.com gem5 code style (http://www.gem5.org/Coding_Style). The patch must receive a 33611901Sjason@lowepower.com +1 from the style checker to be pushed. 33711901Sjason@lowepower.com 33811901Sjason@lowepower.comNote: Whenever the patch creator updates the patch all reviewers must re-review 33911901Sjason@lowepower.comthe patch. There is no longer a "Fix it, then Ship It" option. 34011901Sjason@lowepower.com 34111901Sjason@lowepower.comOnce you have received reviews for your patch, you will likely need to make 34211901Sjason@lowepower.comchanges. To do this, you should update the original git changeset. Then, you 34311901Sjason@lowepower.comcan simply push the changeset again to the same Gerrit branch to update the 34411901Sjason@lowepower.comreview request. 34511901Sjason@lowepower.com 34612562Ssiddhesh.poyarekar@gmail.com``` 34712562Ssiddhesh.poyarekar@gmail.com git push origin HEAD:refs/for/master 34812562Ssiddhesh.poyarekar@gmail.com``` 34911901Sjason@lowepower.com 35011901Sjason@lowepower.comNote: If you have posted a patch and don't receive any reviews, you may need to 35111901Sjason@lowepower.comprod the reviewers. You can do this by adding a reply to your changeset review 35211901Sjason@lowepower.comon gerrit. It is expected that at least the maintainer will supply a review for 35311901Sjason@lowepower.comyour patch. 35411901Sjason@lowepower.com 35511901Sjason@lowepower.comCommitting changes 35611901Sjason@lowepower.com================== 35711901Sjason@lowepower.com 35811901Sjason@lowepower.comEach patch must meet the following criteria to be merged: 35911901Sjason@lowepower.com * At least one review with +2 36011901Sjason@lowepower.com * At least one maintainer with +1 36111901Sjason@lowepower.com * At least +1 from the CI tests (gem5 must build and run) 36211901Sjason@lowepower.com * At least +1 from the style checker 36311901Sjason@lowepower.com 36411901Sjason@lowepower.comOnce a patch meets the above criteria, the submitter of the patch will be able 36511901Sjason@lowepower.comto merge the patch by pressing the "Submit" button on Gerrit. When the patch is 36611901Sjason@lowepower.comsubmitted, it is merged into the public gem5 branch. 367