CONTRIBUTING.md revision 13398
13123Sgblack@eecs.umich.eduAuthors: Jason Lowe-Power 23123Sgblack@eecs.umich.edu Andreas Sandberg 33123Sgblack@eecs.umich.edu Steve Reinhardt 43123Sgblack@eecs.umich.edu 53123Sgblack@eecs.umich.eduIf you've made changes to gem5 that might benefit others, we strongly encourage 63123Sgblack@eecs.umich.eduyou to contribute those changes to the public gem5 repository. There are 73123Sgblack@eecs.umich.eduseveral reasons to do this: 83123Sgblack@eecs.umich.edu * Share your work with others, so that they can benefit from new functionality. 93123Sgblack@eecs.umich.edu * Support the scientific principle by enabling others to evaluate your 103123Sgblack@eecs.umich.edu suggestions without having to guess what you did. 113123Sgblack@eecs.umich.edu * Once your changes are part of the main repo, you no longer have to merge 123123Sgblack@eecs.umich.edu them back in every time you update your local repo. This can be a huge time 133123Sgblack@eecs.umich.edu saving! 143123Sgblack@eecs.umich.edu * Once your code is in the main repo, other people have to make their changes 153123Sgblack@eecs.umich.edu work with your code, and not the other way around. 163123Sgblack@eecs.umich.edu * Others may build on your contributions to make them even better, or extend 173123Sgblack@eecs.umich.edu them in ways you did not have time to do. 183123Sgblack@eecs.umich.edu * You will have the satisfaction of contributing back to the community. 193123Sgblack@eecs.umich.edu 203123Sgblack@eecs.umich.eduThe main method for contributing code to gem5 is via our code review website: 213123Sgblack@eecs.umich.eduhttps://gem5-review.googlesource.com/. This documents describes the details of 223123Sgblack@eecs.umich.eduhow to create code changes, upload your changes, have your changes 233123Sgblack@eecs.umich.edureviewed, and finally push your changes to gem5. More information can be found 243123Sgblack@eecs.umich.edufrom the following sources: 253123Sgblack@eecs.umich.edu * http://gem5.org/Submitting_Contributions 263123Sgblack@eecs.umich.edu * https://gerrit-review.googlesource.com/Documentation/index.html 273123Sgblack@eecs.umich.edu * https://git-scm.com/book 283123Sgblack@eecs.umich.edu 293804Ssaidi@eecs.umich.edu 303123Sgblack@eecs.umich.eduHigh-level flow for submitting changes 313123Sgblack@eecs.umich.edu====================================== 323123Sgblack@eecs.umich.edu 333123Sgblack@eecs.umich.edu +-------------+ 343123Sgblack@eecs.umich.edu | Make change | 353123Sgblack@eecs.umich.edu +------+------+ 363123Sgblack@eecs.umich.edu | 373123Sgblack@eecs.umich.edu | 383123Sgblack@eecs.umich.edu v 393123Sgblack@eecs.umich.edu +-------------+ 403123Sgblack@eecs.umich.edu | Run tests |<--------------+ 413804Ssaidi@eecs.umich.edu +------+------+ | 423804Ssaidi@eecs.umich.edu | | 433123Sgblack@eecs.umich.edu | | 443123Sgblack@eecs.umich.edu v | 453123Sgblack@eecs.umich.edu +------+------+ | 463123Sgblack@eecs.umich.edu | Post review | | 473123Sgblack@eecs.umich.edu +------+------+ | 483123Sgblack@eecs.umich.edu | | 493123Sgblack@eecs.umich.edu v | 503123Sgblack@eecs.umich.edu +--------+---------+ | 513123Sgblack@eecs.umich.edu | Wait for reviews | | 523123Sgblack@eecs.umich.edu +--------+---------+ | 533123Sgblack@eecs.umich.edu | | 543804Ssaidi@eecs.umich.edu | | 553804Ssaidi@eecs.umich.edu v | 563123Sgblack@eecs.umich.edu +----+----+ No +------+------+ 573804Ssaidi@eecs.umich.edu |Reviewers+--------->+ Update code | 583123Sgblack@eecs.umich.edu |happy? | +------+------+ 593123Sgblack@eecs.umich.edu +----+----+ ^ 603123Sgblack@eecs.umich.edu | | 613123Sgblack@eecs.umich.edu | Yes | 623123Sgblack@eecs.umich.edu v | 633123Sgblack@eecs.umich.edu +----+-----+ No | 643123Sgblack@eecs.umich.edu |Maintainer+----------------+ 653123Sgblack@eecs.umich.edu |happy? | 663123Sgblack@eecs.umich.edu +----+-----+ 673123Sgblack@eecs.umich.edu | 683123Sgblack@eecs.umich.edu | Yes 693123Sgblack@eecs.umich.edu v 703123Sgblack@eecs.umich.edu +------+------+ 713123Sgblack@eecs.umich.edu | Submit code | 723123Sgblack@eecs.umich.edu +-------------+ 733123Sgblack@eecs.umich.edu 743123Sgblack@eecs.umich.eduAfter creating your change to gem5, you can post a review on our Gerrit 753123Sgblack@eecs.umich.educode-review site: https://gem5-review.googlesource.com. Before being able to 763123Sgblack@eecs.umich.edusubmit your code to the mainline of gem5, the code is reviewed by others in the 773123Sgblack@eecs.umich.educommunity. Additionally, the maintainer for that part of the code must sign off 783123Sgblack@eecs.umich.eduon it. 793123Sgblack@eecs.umich.edu 803123Sgblack@eecs.umich.eduContributing long-lived feature branches 813123Sgblack@eecs.umich.edu---------------------------------------- 823123Sgblack@eecs.umich.eduOftentimes users or institutions add features that are necessarily complex, 833804Ssaidi@eecs.umich.eduand require many changes on long-lived feature branches. In this case, 843804Ssaidi@eecs.umich.edumaintaining a perfect history where all changes work individually is infeasible. 853123Sgblack@eecs.umich.eduWhen contributing long-lived feature branches back to gem5's public repository 863804Ssaidi@eecs.umich.eduusers may merge entire long-lived branches into a single changeset and contribute 873123Sgblack@eecs.umich.edutheir code back as long as 1) the changes have been reviewed by the maintainer 883123Sgblack@eecs.umich.edu2) the maintainer agrees to allow such a change, and 3) the changes are passing 893123Sgblack@eecs.umich.eduthe public tests. Changes that affect common code (outside of a specific 903123Sgblack@eecs.umich.edumaintainer's purview) will still need to follow the standard gem5 protocol. 913123Sgblack@eecs.umich.edu 923123Sgblack@eecs.umich.edu 933123Sgblack@eecs.umich.eduCloning the gem5 repo to contribute 943123Sgblack@eecs.umich.edu=================================== 953123Sgblack@eecs.umich.edu 963123Sgblack@eecs.umich.eduIf you plan on contributing, it is strongly encouraged for you to clone the 973123Sgblack@eecs.umich.edurepository directly from our gerrit instance at 983123Sgblack@eecs.umich.eduhttps://gem5.googlesource.com/. 993123Sgblack@eecs.umich.edu 1003123Sgblack@eecs.umich.eduTo clone the master gem5 repository: 1013123Sgblack@eecs.umich.edu``` 1023123Sgblack@eecs.umich.edu git clone https://gem5.googlesource.com/public/gem5 1033123Sgblack@eecs.umich.edu``` 1043123Sgblack@eecs.umich.edu 1053123Sgblack@eecs.umich.eduOther gem5 repositories 1063123Sgblack@eecs.umich.edu----------------------- 1073823Ssaidi@eecs.umich.edu 1083123Sgblack@eecs.umich.eduThere are a few repositories other than the main gem5 development repository. 1093123Sgblack@eecs.umich.edu 1103123Sgblack@eecs.umich.edu * public/m5threads: The code for a pthreads implementation that works with 1113123Sgblack@eecs.umich.edu gem5's syscall emulation mode. 1123123Sgblack@eecs.umich.edu 1133123Sgblack@eecs.umich.eduOther gem5 branches 1143123Sgblack@eecs.umich.edu------------------- 1153123Sgblack@eecs.umich.edu 1163123Sgblack@eecs.umich.eduNone right now. 1173123Sgblack@eecs.umich.edu 1183123Sgblack@eecs.umich.eduMaking changes to gem5 1193123Sgblack@eecs.umich.edu====================== 1203123Sgblack@eecs.umich.edu 1213123Sgblack@eecs.umich.eduIt is strongly encouraged to use git branches when making changes to gem5. 1223123Sgblack@eecs.umich.eduAdditionally, keeping changes small and concise and only have a single logical 1233804Ssaidi@eecs.umich.educhange per commit. 1243804Ssaidi@eecs.umich.edu 1253804Ssaidi@eecs.umich.eduUnlike our previous flow with Mercurial and patch queues, when using git, you 1263804Ssaidi@eecs.umich.eduwill be committing changes to your local branch. By using separate branches in 1273123Sgblack@eecs.umich.edugit, you will be able to pull in and merge changes from mainline and simply 1283123Sgblack@eecs.umich.edukeep up with upstream changes. 1293804Ssaidi@eecs.umich.edu 1303804Ssaidi@eecs.umich.eduRequirements for change descriptions 1313123Sgblack@eecs.umich.edu------------------------------------ 1323123Sgblack@eecs.umich.eduTo help reviewers and future contributors more easily understand and track 1333123Sgblack@eecs.umich.educhanges, we require all change descriptions be strictly formatted. 1343123Sgblack@eecs.umich.edu 1353123Sgblack@eecs.umich.eduA canonical commit message consists of three parts: 1363123Sgblack@eecs.umich.edu * A short summary line describing the change. This line starts with one or 1373123Sgblack@eecs.umich.edu more keywords (found in the MAINTAINERS file) separated by commas followed 1383123Sgblack@eecs.umich.edu by a colon and a description of the change. This line should be no more than 1393123Sgblack@eecs.umich.edu 65 characters long since version control systems usually add a prefix that 1403123Sgblack@eecs.umich.edu causes line-wrapping for longer lines. 1413123Sgblack@eecs.umich.edu * (Optional, but highly recommended) A detailed description. This describes 1423123Sgblack@eecs.umich.edu what you have done and why. If the change isn't obvious, you might want to 1433123Sgblack@eecs.umich.edu motivate why it is needed. Lines need to be wrapped to 75 characters or 1443123Sgblack@eecs.umich.edu less. 1453123Sgblack@eecs.umich.edu * Tags describing patch metadata. You are highly recommended to use 1463123Sgblack@eecs.umich.edu tags to acknowledge reviewers for their work. Gerrit will automatically add 1473123Sgblack@eecs.umich.edu most tags. 1483804Ssaidi@eecs.umich.edu 1493123Sgblack@eecs.umich.eduTags are an optional mechanism to store additional metadata about a patch and 1503123Sgblack@eecs.umich.eduacknowledge people who reported a bug or reviewed that patch. Tags are 1513123Sgblack@eecs.umich.edugenerally appended to the end of the commit message in the order they happen. 1523123Sgblack@eecs.umich.eduWe currently use the following tags: 1533123Sgblack@eecs.umich.edu * Signed-off-by: Added by the author and the submitter (if different). 1543123Sgblack@eecs.umich.edu This tag is a statement saying that you believe the patch to be correct and 1553804Ssaidi@eecs.umich.edu have the right to submit the patch according to the license in the affected 1563804Ssaidi@eecs.umich.edu files. Similarly, if you commit someone else's patch, this tells the rest 1573123Sgblack@eecs.umich.edu of the world that you have have the right to forward it to the main 1583123Sgblack@eecs.umich.edu repository. If you need to make any changes at all to submit the change, 1593804Ssaidi@eecs.umich.edu these should be described within hard brackets just before your 1603804Ssaidi@eecs.umich.edu Signed-off-by tag. By adding this line, the contributor certifies the 1613804Ssaidi@eecs.umich.edu contribution is made under the terms of the Developer Certificate of Origin 1623804Ssaidi@eecs.umich.edu (DCO) [https://developercertificate.org/]. 1633123Sgblack@eecs.umich.edu * Reviewed-by: Used to acknowledge patch reviewers. It's generally considered 1643123Sgblack@eecs.umich.edu good form to add these. Added automatically. 1653123Sgblack@eecs.umich.edu * Reported-by: Used to acknowledge someone for finding and reporting a bug. 1663123Sgblack@eecs.umich.edu * Reviewed-on: Link to the review request corresponding to this patch. Added 1673123Sgblack@eecs.umich.edu automatically. 1683123Sgblack@eecs.umich.edu * Change-Id: Used by Gerrit to track changes across rebases. Added 1693123Sgblack@eecs.umich.edu automatically with a commit hook by git. 1703123Sgblack@eecs.umich.edu * Tested-by: Used to acknowledge people who tested a patch. Sometimes added 1713123Sgblack@eecs.umich.edu automatically by review systems that integrate with CI systems. 1723123Sgblack@eecs.umich.edu 1733123Sgblack@eecs.umich.eduOther than the "Signed-off-by", "Reported-by", and "Tested-by" tags, you 1743123Sgblack@eecs.umich.edugenerally don't need to add these manually as they are added automatically by 1753123Sgblack@eecs.umich.eduGerrit. 1763123Sgblack@eecs.umich.edu 1773123Sgblack@eecs.umich.eduIt is encouraged for the author of the patch and the submitter to add a 1783123Sgblack@eecs.umich.eduSigned-off-by tag to the commit message. By adding this line, the contributor 1793123Sgblack@eecs.umich.educertifies the contribution is made under the terms of the Developer Certificate 1803123Sgblack@eecs.umich.eduof Origin (DCO) [https://developercertificate.org/]. 1813123Sgblack@eecs.umich.edu 1823926Ssaidi@eecs.umich.eduIt is imperative that you use your real name and your real email address in 1833926Ssaidi@eecs.umich.eduboth tags and in the author field of the changeset. 1843123Sgblack@eecs.umich.edu 1853123Sgblack@eecs.umich.eduFor significant changes, authors are encouraged to add copyright information 1863123Sgblack@eecs.umich.eduand their names at the beginning of the file. The main purpose of the author 1873123Sgblack@eecs.umich.edunames on the file is to track who is most knowledgeable about the file (e.g., 1883123Sgblack@eecs.umich.eduwho has contributed a significant amount of code to the file). 1893926Ssaidi@eecs.umich.edu 1903926Ssaidi@eecs.umich.eduNote: If you do not follow these guidelines, the gerrit review site will 1913926Ssaidi@eecs.umich.eduautomatically reject your patch. 1923926Ssaidi@eecs.umich.eduIf this happens, update your changeset descriptions to match the required style 1933926Ssaidi@eecs.umich.eduand resubmit. The following is a useful git command to update the most recent 1943926Ssaidi@eecs.umich.educommit (HEAD). 1953926Ssaidi@eecs.umich.edu 1963926Ssaidi@eecs.umich.edu``` 1973926Ssaidi@eecs.umich.edu git commit --amend 1983926Ssaidi@eecs.umich.edu``` 1993123Sgblack@eecs.umich.edu 2003123Sgblack@eecs.umich.eduRunning tests 2013123Sgblack@eecs.umich.edu============= 2023123Sgblack@eecs.umich.edu 2033123Sgblack@eecs.umich.eduBefore posting a change to the code review site, you should always run the 2043123Sgblack@eecs.umich.eduquick tests! 2053123Sgblack@eecs.umich.eduSee TESTING.md for more information. 2063123Sgblack@eecs.umich.edu 2073123Sgblack@eecs.umich.eduPosting a review 2083123Sgblack@eecs.umich.edu================ 2093123Sgblack@eecs.umich.edu 2103123Sgblack@eecs.umich.eduIf you have not signed up for an account on the Gerrit review site 2113123Sgblack@eecs.umich.edu(https://gem5-review.googlesource.com), you first have to create an account. 2123123Sgblack@eecs.umich.edu 2133123Sgblack@eecs.umich.eduSetting up an account 2143123Sgblack@eecs.umich.edu--------------------- 2153123Sgblack@eecs.umich.edu 1. Go to https://gem5.googlesource.com/ 2163123Sgblack@eecs.umich.edu 2. Click "Sign In" in the upper right corner. Note: You will need a Google 2173123Sgblack@eecs.umich.edu account to contribute. 2183123Sgblack@eecs.umich.edu 3. After signing in, click "Generate Password" and follow the instructions. 2193123Sgblack@eecs.umich.edu 2203123Sgblack@eecs.umich.eduSubmitting a change 2213123Sgblack@eecs.umich.edu------------------- 2223123Sgblack@eecs.umich.edu 2233123Sgblack@eecs.umich.eduIn gerrit, to submit a review request, you can simply push your git commits to 2243123Sgblack@eecs.umich.edua special named branch. For more information on git push see 2253123Sgblack@eecs.umich.eduhttps://git-scm.com/docs/git-push. 2263123Sgblack@eecs.umich.edu 2273123Sgblack@eecs.umich.eduThere are three ways to push your changes to gerrit. 2283123Sgblack@eecs.umich.edu 2293123Sgblack@eecs.umich.eduPush change to gerrit review 2303123Sgblack@eecs.umich.edu---------------------------- 2313123Sgblack@eecs.umich.edu 2323123Sgblack@eecs.umich.edu``` 2333123Sgblack@eecs.umich.edu git push origin HEAD:refs/for/master 2343123Sgblack@eecs.umich.edu``` 2353123Sgblack@eecs.umich.edu 2363123Sgblack@eecs.umich.eduAssuming origin is https://gem5.googlesource.com/public/gem5 and you want to 2373123Sgblack@eecs.umich.edupush the changeset at HEAD, this will create a new review request on top of the 2383123Sgblack@eecs.umich.edumaster branch. More generally, 2393123Sgblack@eecs.umich.edu 2403123Sgblack@eecs.umich.edu``` 2413123Sgblack@eecs.umich.edu git push <gem5 gerrit instance> <changeset>:refs/for/<branch> 2423123Sgblack@eecs.umich.edu``` 2433123Sgblack@eecs.umich.edu 2443123Sgblack@eecs.umich.eduSee https://gerrit-review.googlesource.com/Documentation/user-upload.html for 2453123Sgblack@eecs.umich.edumore information. 2463123Sgblack@eecs.umich.edu 2473123Sgblack@eecs.umich.eduPushing your first change 2483123Sgblack@eecs.umich.edu-------------------------- 2493123Sgblack@eecs.umich.eduThe first time you push a change you may get the following error: 2503804Ssaidi@eecs.umich.edu 2513123Sgblack@eecs.umich.edu``` 2523123Sgblack@eecs.umich.edu remote: ERROR: [fb1366b] missing Change-Id in commit message footer 2533123Sgblack@eecs.umich.edu ... 2543123Sgblack@eecs.umich.edu``` 2553123Sgblack@eecs.umich.edu 2563123Sgblack@eecs.umich.eduWithin the error message, there is a command line you should run. For every new 2573123Sgblack@eecs.umich.educlone of the git repo, you need to run the following command to automatically 2583824Ssaidi@eecs.umich.eduinsert the change id in the the commit (all on one line). 2593824Ssaidi@eecs.umich.edu 2603824Ssaidi@eecs.umich.edu``` 2613824Ssaidi@eecs.umich.edu curl -Lo `git rev-parse --git-dir`/hooks/commit-msg \ 2623824Ssaidi@eecs.umich.edu https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; \ 2633824Ssaidi@eecs.umich.edu chmod +x `git rev-parse --git-dir`/hooks/commit-msg 2643824Ssaidi@eecs.umich.edu``` 2653804Ssaidi@eecs.umich.edu 2663123Sgblack@eecs.umich.eduIf you receive the above error, simply run this command and then amend your 2673804Ssaidi@eecs.umich.educhangeset. 2683823Ssaidi@eecs.umich.edu 2693804Ssaidi@eecs.umich.edu``` 2703804Ssaidi@eecs.umich.edu git commit --amend 2713804Ssaidi@eecs.umich.edu``` 2723804Ssaidi@eecs.umich.edu 2733804Ssaidi@eecs.umich.eduPush change to gerrit as a draft/private 2743804Ssaidi@eecs.umich.edu---------------------------------------- 2753804Ssaidi@eecs.umich.edu 2763804Ssaidi@eecs.umich.eduSee https://gerrit-review.googlesource.com/Documentation/intro-user.html#private-changes 2773123Sgblack@eecs.umich.edufor details on private gerrit changes. 2783123Sgblack@eecs.umich.edu 2793804Ssaidi@eecs.umich.edu``` 2803123Sgblack@eecs.umich.edu git push origin HEAD:refs/for/master%private 2813804Ssaidi@eecs.umich.edu``` 2823123Sgblack@eecs.umich.edu 2833804Ssaidi@eecs.umich.eduOnce you have pushed your change as "private", you can log onto [gerrit] 2843804Ssaidi@eecs.umich.edu(https://gem5-review.googlesource.com) and once you're happy with the commit 2853804Ssaidi@eecs.umich.educlick the "unmark private" which may be hidden in the "more options" dropdown 2863804Ssaidi@eecs.umich.eduin the upper right corner. 2873804Ssaidi@eecs.umich.edu 2883804Ssaidi@eecs.umich.eduPush change bypassing gerrit 2893804Ssaidi@eecs.umich.edu----------------------------- 2903804Ssaidi@eecs.umich.edu 2913804Ssaidi@eecs.umich.eduOnly maintainers can bypass gerrit review. This should very rarely be used. 2923804Ssaidi@eecs.umich.edu 2933804Ssaidi@eecs.umich.edu``` 2943804Ssaidi@eecs.umich.edu git push origin HEAD:refs/heads/master 2953804Ssaidi@eecs.umich.edu``` 2963804Ssaidi@eecs.umich.edu 2973825Ssaidi@eecs.umich.eduOther gerrit push options 2983825Ssaidi@eecs.umich.edu------------------------- 2993825Ssaidi@eecs.umich.edu 3003825Ssaidi@eecs.umich.eduThere are a number of options you can specify when uploading your changes to 3013825Ssaidi@eecs.umich.edugerrit (e.g., reviewers, labels). The gerrit documentation has more 3023825Ssaidi@eecs.umich.eduinformation. 3033825Ssaidi@eecs.umich.eduhttps://gerrit-review.googlesource.com/Documentation/user-upload.html 3043804Ssaidi@eecs.umich.edu 3053804Ssaidi@eecs.umich.edu 3063123Sgblack@eecs.umich.eduReviewing patches 307================= 308 309Reviewing patches is done on our gerrit instance at 310https://gem5-review.googlesource.com/. 311 312After logging in with your Google account, you will be able to comment, review, 313and push your own patches as well as review others' patches. All gem5 users are 314encouraged to review patches. The only requirement to review patches is to be 315polite and respectful of others. 316 317There are multiple labels in Gerrit that can be applied to each review detailed 318below. 319 * Code-review: This is used by any gem5 user to review patches. When reviewing 320 a patch you can give it a score of -2 to +2 with the following semantics. 321 * -2: This blocks the patch. You believe that this patch should never be 322 committed. This label should be very rarely used. 323 * -1: You would prefer this is not merged as is 324 * 0: No score 325 * +1: This patch seems good, but you aren't 100% confident that it should be 326 pushed. 327 * +2: This is a good patch and should be pushed as is. 328 * Maintainer: Currently only PMC members are maintainers. At least one 329 maintainer must review your patch and give it a +1 before it can be merged. 330 * Verified: This is automatically generated from the continuous integrated 331 (CI) tests. Each patch must receive at least a +1 from the CI tests before 332 the patch can be merged. The patch will receive a +1 if gem5 builds and 333 runs, and it will receive a +2 if the stats match. 334 * Style-Check: This is automatically generated and tests the patch against the 335 gem5 code style (http://www.gem5.org/Coding_Style). The patch must receive a 336 +1 from the style checker to be pushed. 337 338Note: Whenever the patch creator updates the patch all reviewers must re-review 339the patch. There is no longer a "Fix it, then Ship It" option. 340 341Once you have received reviews for your patch, you will likely need to make 342changes. To do this, you should update the original git changeset. Then, you 343can simply push the changeset again to the same Gerrit branch to update the 344review request. 345 346``` 347 git push origin HEAD:refs/for/master 348``` 349 350Note: If you have posted a patch and don't receive any reviews, you may need to 351prod the reviewers. You can do this by adding a reply to your changeset review 352on gerrit. It is expected that at least the maintainer will supply a review for 353your patch. 354 355Committing changes 356================== 357 358Each patch must meet the following criteria to be merged: 359 * At least one review with +2 360 * At least one maintainer with +1 361 * At least +1 from the CI tests (gem5 must build and run) 362 * At least +1 from the style checker 363 364Once a patch meets the above criteria, the submitter of the patch will be able 365to merge the patch by pressing the "Submit" button on Gerrit. When the patch is 366submitted, it is merged into the public gem5 branch. 367