CONTRIBUTING.md revision 12883
12623SN/AAuthors: Jason Lowe-Power 22623SN/A Andreas Sandberg 32623SN/A Steve Reinhardt 42623SN/A 52623SN/AIf you've made changes to gem5 that might benefit others, we strongly encourage 62623SN/Ayou to contribute those changes to the public gem5 repository. There are 72623SN/Aseveral reasons to do this: 82623SN/A * Share your work with others, so that they can benefit from new functionality. 92623SN/A * Support the scientific principle by enabling others to evaluate your 102623SN/A suggestions without having to guess what you did. 112623SN/A * Once your changes are part of the main repo, you no longer have to merge 122623SN/A them back in every time you update your local repo. This can be a huge time 132623SN/A saving! 142623SN/A * Once your code is in the main repo, other people have to make their changes 152623SN/A work with your code, and not the other way around. 162623SN/A * Others may build on your contributions to make them even better, or extend 172623SN/A them in ways you did not have time to do. 182623SN/A * You will have the satisfaction of contributing back to the community. 192623SN/A 202623SN/AThe main method for contributing code to gem5 is via our code review website: 212623SN/Ahttps://gem5-review.googlesource.com/. This documents describes the details of 222623SN/Ahow to create code changes, upload your changes, have your changes 232623SN/Areviewed, and finally push your changes to gem5. More information can be found 242623SN/Afrom the following sources: 252623SN/A * http://gem5.org/Submitting_Contributions 262623SN/A * https://gerrit-review.googlesource.com/Documentation/index.html 272665Ssaidi@eecs.umich.edu * https://git-scm.com/book 282665Ssaidi@eecs.umich.edu 292623SN/A 302623SN/AHigh-level flow for submitting changes 313170Sstever@eecs.umich.edu====================================== 323806Ssaidi@eecs.umich.edu 332623SN/A +-------------+ 344040Ssaidi@eecs.umich.edu | Make change | 352623SN/A +------+------+ 362623SN/A | 373348Sbinkertn@umich.edu | 383348Sbinkertn@umich.edu v 394762Snate@binkert.org +-------------+ 402901Ssaidi@eecs.umich.edu | Run tests |<--------------+ 412623SN/A +------+------+ | 422623SN/A | | 432623SN/A | | 442623SN/A v | 452623SN/A +------+------+ | 462623SN/A | Post review | | 472623SN/A +------+------+ | 482623SN/A | | 492623SN/A v | 502623SN/A +--------+---------+ | 512623SN/A | Wait for reviews | | 522623SN/A +--------+---------+ | 532623SN/A | | 542623SN/A | | 552623SN/A v | 562623SN/A +----+----+ No +------+------+ 572623SN/A |Reviewers+--------->+ Update code | 582623SN/A |happy? | +------+------+ 592623SN/A +----+----+ ^ 604873Sstever@eecs.umich.edu | | 612623SN/A | Yes | 622623SN/A v | 632856Srdreslin@umich.edu +----+-----+ No | 642856Srdreslin@umich.edu |Maintainer+----------------+ 652856Srdreslin@umich.edu |happy? | 662856Srdreslin@umich.edu +----+-----+ 672856Srdreslin@umich.edu | 682856Srdreslin@umich.edu | Yes 692856Srdreslin@umich.edu v 704968Sacolyte@umich.edu +------+------+ 714968Sacolyte@umich.edu | Submit code | 724968Sacolyte@umich.edu +-------------+ 734968Sacolyte@umich.edu 742856Srdreslin@umich.eduAfter creating your change to gem5, you can post a review on our Gerrit 752856Srdreslin@umich.educode-review site: https://gem5-review.googlesource.com. Before being able to 762856Srdreslin@umich.edusubmit your code to the mainline of gem5, the code is reviewed by others in the 772623SN/Acommunity. Additionally, the maintainer for that part of the code must sign off 782623SN/Aon it. 792623SN/A 802623SN/ACloning the gem5 repo to contribute 812623SN/A=================================== 825310Ssaidi@eecs.umich.edu 832623SN/AIf you plan on contributing, it is strongly encouraged for you to clone the 842680Sktlim@umich.edurepository directly from our gerrit instance at 852680Sktlim@umich.eduhttps://gem5.googlesource.com/. 862623SN/A 872623SN/ATo clone the master gem5 repository: 885310Ssaidi@eecs.umich.edu``` 892623SN/A git clone https://gem5.googlesource.com/public/gem5 902623SN/A``` 914968Sacolyte@umich.edu 924968Sacolyte@umich.eduOther gem5 repositories 934968Sacolyte@umich.edu----------------------- 944968Sacolyte@umich.edu 954968Sacolyte@umich.eduThere are a few repositories other than the main gem5 development repository. 964968Sacolyte@umich.edu 975310Ssaidi@eecs.umich.edu * public/m5threads: The code for a pthreads implementation that works with 985310Ssaidi@eecs.umich.edu gem5's syscall emulation mode. 995310Ssaidi@eecs.umich.edu 1002623SN/AOther gem5 branches 1012623SN/A------------------- 1022623SN/A 1033349Sbinkertn@umich.eduNone right now. 1042623SN/A 1053184Srdreslin@umich.eduMaking changes to gem5 1062623SN/A====================== 1072623SN/A 1082623SN/AIt is strongly encouraged to use git branches when making changes to gem5. 1092623SN/AAdditionally, keeping changes small and concise and only have a single logical 1103349Sbinkertn@umich.educhange per commit. 1112623SN/A 1123310Srdreslin@umich.eduUnlike our previous flow with Mercurial and patch queues, when using git, you 1133649Srdreslin@umich.eduwill be committing changes to your local branch. By using separate branches in 1142623SN/Agit, you will be able to pull in and merge changes from mainline and simply 1152623SN/Akeep up with upstream changes. 1162623SN/A 1173349Sbinkertn@umich.eduRequirements for change descriptions 1182623SN/A------------------------------------ 1193184Srdreslin@umich.eduTo help reviewers and future contributors more easily understand and track 1203184Srdreslin@umich.educhanges, we require all change descriptions be strictly formatted. 1212623SN/A 1222623SN/AA canonical commit message consists of three parts: 1232623SN/A * A short summary line describing the change. This line starts with one or 1242623SN/A more keywords (found in the MAINTAINERS file) separated by commas followed 1252623SN/A by a colon and a description of the change. This line should be no more than 1263647Srdreslin@umich.edu 65 characters long since version control systems usually add a prefix that 1273647Srdreslin@umich.edu causes line-wrapping for longer lines. 1283647Srdreslin@umich.edu * (Optional, but highly recommended) A detailed description. This describes 1293647Srdreslin@umich.edu what you have done and why. If the change isn't obvious, you might want to 1303647Srdreslin@umich.edu motivate why it is needed. Lines need to be wrapped to 75 characters or 1312626SN/A less. 1323647Srdreslin@umich.edu * Tags describing patch metadata. You are highly recommended to use 1332626SN/A tags to acknowledge reviewers for their work. Gerrit will automatically add 1342623SN/A most tags. 1352623SN/A 1362623SN/ATags are an optional mechanism to store additional metadata about a patch and 1372657Ssaidi@eecs.umich.eduacknowledge people who reported a bug or reviewed that patch. Tags are 1382623SN/Agenerally appended to the end of the commit message in the order they happen. 1392623SN/AWe currently use the following tags: 1402623SN/A * Signed-off-by: Added by the author and the submitter (if different). 1412623SN/A This tag is a statement saying that you believe the patch to be correct and 1422623SN/A have the right to submit the patch according to the license in the affected 1434192Sktlim@umich.edu files. Similarly, if you commit someone else's patch, this tells the rest 1444192Sktlim@umich.edu of the world that you have have the right to forward it to the main 1454192Sktlim@umich.edu repository. If you need to make any changes at all to submit the change, 1464192Sktlim@umich.edu these should be described within hard brackets just before your 1474192Sktlim@umich.edu Signed-off-by tag. By adding this line, the contributor certifies the 1484192Sktlim@umich.edu contribution is made under the terms of the Developer Certificate of Origin 1494192Sktlim@umich.edu (DCO) [https://developercertificate.org/]. 1504192Sktlim@umich.edu * Reviewed-by: Used to acknowledge patch reviewers. It's generally considered 1514192Sktlim@umich.edu good form to add these. Added automatically. 1524192Sktlim@umich.edu * Reported-by: Used to acknowledge someone for finding and reporting a bug. 1534192Sktlim@umich.edu * Reviewed-on: Link to the review request corresponding to this patch. Added 1542623SN/A automatically. 1552623SN/A * Change-Id: Used by Gerrit to track changes across rebases. Added 1562623SN/A automatically with a commit hook by git. 1572623SN/A * Tested-by: Used to acknowledge people who tested a patch. Sometimes added 1584968Sacolyte@umich.edu automatically by review systems that integrate with CI systems. 1594968Sacolyte@umich.edu 1602623SN/AOther than the "Signed-off-by", "Reported-by", and "Tested-by" tags, you 1612623SN/Agenerally don't need to add these manually as they are added automatically by 1622623SN/AGerrit. 1633647Srdreslin@umich.edu 1643647Srdreslin@umich.eduIt is encouraged for the author of the patch and the submitter to add a 1653647Srdreslin@umich.eduSigned-off-by tag to the commit message. By adding this line, the contributor 1662623SN/Acertifies the contribution is made under the terms of the Developer Certificate 1672623SN/Aof Origin (DCO) [https://developercertificate.org/]. 1682623SN/A 1692623SN/AIt is imperative that you use your real name and your real email address in 1702623SN/Aboth tags and in the author field of the changeset. 1712623SN/A 1722623SN/AFor significant changes, authors are encouraged to add copyright information 1732623SN/Aand their names at the beginning of the file. The main purpose of the author 1742623SN/Anames on the file is to track who is most knowledgeable about the file (e.g., 1752623SN/Awho has contributed a significant amount of code to the file). 1762915Sktlim@umich.edu 1772915Sktlim@umich.eduNote: If you do not follow these guidelines, the gerrit review site will 1783177Shsul@eecs.umich.eduautomatically reject your patch. 1793177Shsul@eecs.umich.eduIf this happens, update your changeset descriptions to match the required style 1803145Shsul@eecs.umich.eduand resubmit. The following is a useful git command to update the most recent 1812623SN/Acommit (HEAD). 1822623SN/A 1832623SN/A``` 1842623SN/A git commit --amend 1852623SN/A``` 1862623SN/A 1872623SN/ARunning tests 1882915Sktlim@umich.edu============= 1892915Sktlim@umich.edu 1903177Shsul@eecs.umich.eduBefore posting a change to the code review site, you should always run the 1913145Shsul@eecs.umich.eduquick tests! 1922915Sktlim@umich.eduSee TESTING.md for more information. 1932915Sktlim@umich.edu 1942915Sktlim@umich.eduPosting a review 1952915Sktlim@umich.edu================ 1962915Sktlim@umich.edu 1972915Sktlim@umich.eduIf you have not signed up for an account on the Gerrit review site 1985220Ssaidi@eecs.umich.edu(https://gem5-review.googlesource.com), you first have to create an account. 1995220Ssaidi@eecs.umich.edu 2005220Ssaidi@eecs.umich.eduSetting up an account 2014940Snate@binkert.org--------------------- 2025220Ssaidi@eecs.umich.edu 1. Go to https://gem5.googlesource.com/ 2033324Shsul@eecs.umich.edu 2. Click "Sign In" in the upper right corner. Note: You will need a Google 2045220Ssaidi@eecs.umich.edu account to contribute. 2055220Ssaidi@eecs.umich.edu 3. After signing in, click "Generate Password" and follow the instructions. 2065220Ssaidi@eecs.umich.edu 2075220Ssaidi@eecs.umich.eduSubmitting a change 2083324Shsul@eecs.umich.edu------------------- 2092915Sktlim@umich.edu 2102623SN/AIn gerrit, to submit a review request, you can simply push your git commits to 2112623SN/Aa special named branch. For more information on git push see 2122623SN/Ahttps://git-scm.com/docs/git-push. 2132798Sktlim@umich.edu 2142623SN/AThere are three ways to push your changes to gerrit. 2152798Sktlim@umich.edu 2162798Sktlim@umich.eduPush change to gerrit review 2172623SN/A---------------------------- 2182798Sktlim@umich.edu 2192623SN/A``` 2202623SN/A git push origin HEAD:refs/for/master 2212623SN/A``` 2222623SN/A 2232623SN/AAssuming origin is https://gem5.googlesource.com/public/gem5 and you want to 2242623SN/Apush the changeset at HEAD, this will create a new review request on top of the 2254192Sktlim@umich.edumaster branch. More generally, 2262623SN/A 2272623SN/A``` 2282623SN/A git push <gem5 gerrit instance> <changeset>:refs/for/<branch> 2292680Sktlim@umich.edu``` 2302623SN/A 2312680Sktlim@umich.eduSee https://gerrit-review.googlesource.com/Documentation/user-upload.html for 2322680Sktlim@umich.edumore information. 2332680Sktlim@umich.edu 2342623SN/APushing your first change 2353495Sktlim@umich.edu-------------------------- 2362623SN/AThe first time you push a change you may get the following error: 2372623SN/A 2382623SN/A``` 2393512Sktlim@umich.edu remote: ERROR: [fb1366b] missing Change-Id in commit message footer 2403512Sktlim@umich.edu ... 2413512Sktlim@umich.edu``` 2425169Ssaidi@eecs.umich.edu 2435169Ssaidi@eecs.umich.eduWithin the error message, there is a command line you should run. For every new 2445310Ssaidi@eecs.umich.educlone of the git repo, you need to run the following command to automatically 2455310Ssaidi@eecs.umich.eduinsert the change id in the the commit (all on one line). 2465310Ssaidi@eecs.umich.edu 2472623SN/A``` 2482623SN/A curl -Lo `git rev-parse --git-dir`/hooks/commit-msg \ 2492623SN/A https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; \ 2502623SN/A chmod +x `git rev-parse --git-dir`/hooks/commit-msg 2512623SN/A``` 2522623SN/A 2534940Snate@binkert.orgIf you receive the above error, simply run this command and then amend your 2544940Snate@binkert.orgchangeset. 2552623SN/A 2562683Sktlim@umich.edu``` 2572623SN/A git commit --amend 2582623SN/A``` 2592623SN/A 2602623SN/APush change to gerrit as a draft/private 2612623SN/A---------------------------------------- 2625101Ssaidi@eecs.umich.edu 2633686Sktlim@umich.eduSee https://gerrit-review.googlesource.com/Documentation/intro-user.html#private-changes 2643430Sgblack@eecs.umich.edufor details on private gerrit changes. 2655100Ssaidi@eecs.umich.edu 2662623SN/A``` 2672623SN/A git push origin HEAD:refs/for/master%private 2682623SN/A``` 2692623SN/A 2702623SN/AOnce you have pushed your change as "private", you can log onto [gerrit] 2712623SN/A(https://gem5-review.googlesource.com) and once you're happy with the commit 2722623SN/Aclick the "unmark private" which may be hidden in the "more options" dropdown 2734940Snate@binkert.orgin the upper right corner. 2744940Snate@binkert.org 2752623SN/APush change bypassing gerrit 2762683Sktlim@umich.edu----------------------------- 2772623SN/A 2782623SN/AOnly maintainers can bypass gerrit review. This should very rarely be used. 2792626SN/A 2802626SN/A``` 2812626SN/A git push origin HEAD:refs/heads/master 2822626SN/A``` 2832626SN/A 2842623SN/AOther gerrit push options 2852623SN/A------------------------- 2862623SN/A 2872623SN/AThere are a number of options you can specify when uploading your changes to 2882623SN/Agerrit (e.g., reviewers, labels). The gerrit documentation has more 2892623SN/Ainformation. 2902623SN/Ahttps://gerrit-review.googlesource.com/Documentation/user-upload.html 2912623SN/A 2922623SN/A 2932623SN/AReviewing patches 2943169Sstever@eecs.umich.edu================= 2954870Sstever@eecs.umich.edu 2962623SN/AReviewing patches is done on our gerrit instance at 2972623SN/Ahttps://gem5-review.googlesource.com/. 2982623SN/A 2992623SN/AAfter logging in with your Google account, you will be able to comment, review, 3002623SN/Aand push your own patches as well as review others' patches. All gem5 users are 3014999Sgblack@eecs.umich.eduencouraged to review patches. The only requirement to review patches is to be 3024999Sgblack@eecs.umich.edupolite and respectful of others. 3034999Sgblack@eecs.umich.edu 3044999Sgblack@eecs.umich.eduThere are multiple labels in Gerrit that can be applied to each review detailed 3052623SN/Abelow. 3064999Sgblack@eecs.umich.edu * Code-review: This is used by any gem5 user to review patches. When reviewing 3072623SN/A a patch you can give it a score of -2 to +2 with the following semantics. 3084999Sgblack@eecs.umich.edu * -2: This blocks the patch. You believe that this patch should never be 3094999Sgblack@eecs.umich.edu committed. This label should be very rarely used. 3104999Sgblack@eecs.umich.edu * -1: You would prefer this is not merged as is 3114999Sgblack@eecs.umich.edu * 0: No score 3124999Sgblack@eecs.umich.edu * +1: This patch seems good, but you aren't 100% confident that it should be 3134999Sgblack@eecs.umich.edu pushed. 3144999Sgblack@eecs.umich.edu * +2: This is a good patch and should be pushed as is. 3154999Sgblack@eecs.umich.edu * Maintainer: Currently only PMC members are maintainers. At least one 3164999Sgblack@eecs.umich.edu maintainer must review your patch and give it a +1 before it can be merged. 3174999Sgblack@eecs.umich.edu * Verified: This is automatically generated from the continuous integrated 3184999Sgblack@eecs.umich.edu (CI) tests. Each patch must receive at least a +1 from the CI tests before 3194999Sgblack@eecs.umich.edu the patch can be merged. The patch will receive a +1 if gem5 builds and 3204999Sgblack@eecs.umich.edu runs, and it will receive a +2 if the stats match. 3214999Sgblack@eecs.umich.edu * Style-Check: This is automatically generated and tests the patch against the 3224999Sgblack@eecs.umich.edu gem5 code style (http://www.gem5.org/Coding_Style). The patch must receive a 3234999Sgblack@eecs.umich.edu +1 from the style checker to be pushed. 3244999Sgblack@eecs.umich.edu 3254999Sgblack@eecs.umich.eduNote: Whenever the patch creator updates the patch all reviewers must re-review 3264999Sgblack@eecs.umich.eduthe patch. There is no longer a "Fix it, then Ship It" option. 3274999Sgblack@eecs.umich.edu 3284999Sgblack@eecs.umich.eduOnce you have received reviews for your patch, you will likely need to make 3294999Sgblack@eecs.umich.educhanges. To do this, you should update the original git changeset. Then, you 3304999Sgblack@eecs.umich.educan simply push the changeset again to the same Gerrit branch to update the 3314999Sgblack@eecs.umich.edureview request. 3324999Sgblack@eecs.umich.edu 3334999Sgblack@eecs.umich.edu``` 3344999Sgblack@eecs.umich.edu git push origin HEAD:refs/for/master 3354999Sgblack@eecs.umich.edu``` 3364999Sgblack@eecs.umich.edu 3374999Sgblack@eecs.umich.eduNote: If you have posted a patch and don't receive any reviews, you may need to 3384999Sgblack@eecs.umich.eduprod the reviewers. You can do this by adding a reply to your changeset review 3395012Sgblack@eecs.umich.eduon gerrit. It is expected that at least the maintainer will supply a review for 3404999Sgblack@eecs.umich.eduyour patch. 3414999Sgblack@eecs.umich.edu 3424999Sgblack@eecs.umich.eduCommitting changes 3434999Sgblack@eecs.umich.edu================== 3444999Sgblack@eecs.umich.edu 3454968Sacolyte@umich.eduEach patch must meet the following criteria to be merged: 3464986Ssaidi@eecs.umich.edu * At least one review with +2 3474999Sgblack@eecs.umich.edu * At least one maintainer with +1 3484999Sgblack@eecs.umich.edu * At least +1 from the CI tests (gem5 must build and run) 3494999Sgblack@eecs.umich.edu * At least +1 from the style checker 3504762Snate@binkert.org 3514999Sgblack@eecs.umich.eduOnce a patch meets the above criteria, the submitter of the patch will be able 3524999Sgblack@eecs.umich.eduto merge the patch by pressing the "Submit" button on Gerrit. When the patch is 3534999Sgblack@eecs.umich.edusubmitted, it is merged into the public gem5 branch. 3544999Sgblack@eecs.umich.edu