tests: arch-power: Add 64-bit hello binaries
[gem5.git] / CONTRIBUTING.md
1 If you've made changes to gem5 that might benefit others, we strongly encourage
2 you to contribute those changes to the public gem5 repository. There are
3 several reasons to do this:
4 * Share your work with others, so that they can benefit from new functionality.
5 * Support the scientific principle by enabling others to evaluate your
6 suggestions without having to guess what you did.
7 * Once your changes are part of the main repo, you no longer have to merge
8 them back in every time you update your local repo. This can be a huge time
9 saving!
10 * Once your code is in the main repo, other people have to make their changes
11 work with your code, and not the other way around.
12 * Others may build on your contributions to make them even better, or extend
13 them in ways you did not have time to do.
14 * You will have the satisfaction of contributing back to the community.
16 The main method for contributing code to gem5 is via our code review website:
17 https://gem5-review.googlesource.com/. This documents describes the details of
18 how to create code changes, upload your changes, have your changes
19 reviewed, and finally push your changes to gem5. More information can be found
20 from the following sources:
21 * http://gem5.org/contributing
22 * https://gerrit-review.googlesource.com/Documentation/index.html
23 * https://git-scm.com/book
26 High-level flow for submitting changes
27 ======================================
29 +-------------+
30 | Make change |
31 +------+------+
32 |
33 |
34 v
35 +-------------+
36 | Run tests |<--------------+
37 +------+------+ |
38 | |
39 | |
40 v |
41 +------+------+ |
42 | Post review | |
43 +------+------+ |
44 | |
45 v |
46 +--------+---------+ |
47 | Wait for reviews | |
48 +--------+---------+ |
49 | |
50 | |
51 v |
52 +----+----+ No +------+------+
53 |Reviewers+--------->+ Update code |
54 |happy? | +------+------+
55 +----+----+ ^
56 | |
57 | Yes |
58 v |
59 +----+-----+ No |
60 |Maintainer+----------------+
61 |happy? |
62 +----+-----+
63 |
64 | Yes
65 v
66 +------+------+
67 | Submit code |
68 +-------------+
70 After creating your change to gem5, you can post a review on our Gerrit
71 code-review site: https://gem5-review.googlesource.com. Before being able to
72 submit your code to the mainline of gem5, the code is reviewed by others in the
73 community. Additionally, the maintainer for that part of the code must sign off
74 on it.
76 Cloning the gem5 repo to contribute
77 ===================================
79 If you plan on contributing, it is strongly encouraged for you to clone the
80 repository directly, and checkout the `develop` branch from our gerrit instance
81 at https://gem5.googlesource.com/.
83 To clone the gem5 repository:
85 ```
86 git clone https://gem5.googlesource.com/public/gem5
87 ```
89 By default, the stable branch is checked out. The stable branch contains the
90 latest released version of gem5. To obtain code still under-development (and
91 which contributions can be made):
93 ```
94 cd gem5
95 git checkout --track origin/develop
96 ```
98 Changes should be made to this develop branch. Changes to the stable branch
99 will be blocked. Once a change on the develop branch is properly incorporated
100 into the gem5 repo it will be merged into the stable branch upon the next
101 release of gem5. New releases of gem5 occur three times a year. Ergo, changes
102 made to the develop branch should appear on the stable branch within three to
103 four months as part of a stable release.
105 Other gem5 repositories
106 -----------------------
108 There are a few repositories other than the main gem5 development repository.
110 * public/m5threads: The code for a pthreads implementation that works with
111 gem5's syscall emulation mode.
112 * public/gem5-resources: Resources to enable computer architecture research
113 with gem5. See the README.md file in the gem5-resources repository for more
114 information.
115 * public/gem5-website: The gem5.org website source. See the README.md file in
116 the gem5-website repository for more information.
118 Making changes to gem5
119 ======================
121 It is strongly encouraged to use git branches when making changes to gem5.
122 Additionally, keeping changes small and concise and only have a single logical
123 change per commit.
125 Unlike our previous flow with Mercurial and patch queues, when using git, you
126 will be committing changes to your local branch. By using separate branches in
127 git, you will be able to pull in and merge changes from mainline and simply
128 keep up with upstream changes.
130 We use a rebase-always model for contributions to the develop branch of gem5.
131 In this model, the changes are rebased on top of the tip of develop instead of
132 merged. This means that to contribute, you will have to frequently rebase any
133 feature branches on top of develop. If you see a "merge conflict" in gerrit, it
134 can often be solved with a simple rebase. To find out more information about
135 rebasing and git, see the [git book].
137 [git book]: https://git-scm.com/book/en/v2/Git-Branching-Rebasing
139 Requirements for change descriptions
140 ------------------------------------
141 To help reviewers and future contributors more easily understand and track
142 changes, we require all change descriptions be strictly formatted.
144 A canonical commit message consists of three parts:
145 * A short summary line describing the change. This line starts with one or
146 more keywords (found in the MAINTAINERS file) separated by commas followed
147 by a colon and a description of the change. This line should be no more than
148 65 characters long since version control systems usually add a prefix that
149 causes line-wrapping for longer lines.
150 * (Optional, but highly recommended) A detailed description. This describes
151 what you have done and why. If the change isn't obvious, you might want to
152 motivate why it is needed. Lines need to be wrapped to 72 characters or
153 less.
154 * Tags describing patch metadata. You are highly recommended to use
155 tags to acknowledge reviewers for their work. Gerrit will automatically add
156 most tags.
158 Tags are an optional mechanism to store additional metadata about a patch and
159 acknowledge people who reported a bug or reviewed that patch. Tags are
160 generally appended to the end of the commit message in the order they happen.
161 We currently use the following tags:
162 * Signed-off-by: Added by the author and the submitter (if different).
163 This tag is a statement saying that you believe the patch to be correct and
164 have the right to submit the patch according to the license in the affected
165 files. Similarly, if you commit someone else's patch, this tells the rest
166 of the world that you have have the right to forward it to the main
167 repository. If you need to make any changes at all to submit the change,
168 these should be described within hard brackets just before your
169 Signed-off-by tag. By adding this line, the contributor certifies the
170 contribution is made under the terms of the Developer Certificate of Origin
171 (DCO) [https://developercertificate.org/].
172 * Reviewed-by: Used to acknowledge patch reviewers. It's generally considered
173 good form to add these. Added automatically.
174 * Reported-by: Used to acknowledge someone for finding and reporting a bug.
175 * Reviewed-on: Link to the review request corresponding to this patch. Added
176 automatically.
177 * Change-Id: Used by Gerrit to track changes across rebases. Added
178 automatically with a commit hook by git.
179 * Tested-by: Used to acknowledge people who tested a patch. Sometimes added
180 automatically by review systems that integrate with CI systems.
181 * Issue-On: Used to link a commit to an issue in gem5's [issue tracker]. The
182 format should be https://gem5.atlassian.net/browse/GEM5-<NUMBER>
184 [issue tracker]: https://gem5.atlassian.net/
186 Other than the "Signed-off-by", "Issue-On", "Reported-by", and "Tested-by"
187 tags, you generally don't need to add these manually as they are added
188 automatically by Gerrit.
190 It is encouraged for the author of the patch and the submitter to add a
191 Signed-off-by tag to the commit message. By adding this line, the contributor
192 certifies the contribution is made under the terms of the Developer Certificate
193 of Origin (DCO) [https://developercertificate.org/].
195 If your change relates to a [Jira Issue](https://gem5.atlassian.net), it is
196 advised that you provide a link to the issue in the commit message (or messages
197 if the Jira Issue relates to multiple commits). Though optional, doing this
198 can help reviewers understand the context of a change.
200 It is imperative that you use your real name and your real email address in
201 both tags and in the author field of the changeset.
203 For significant changes, authors are encouraged to add copyright information
204 and their names at the beginning of the file. The main purpose of the author
205 names on the file is to track who is most knowledgeable about the file (e.g.,
206 who has contributed a significant amount of code to the file). The
207 `util/update-copyright.py` helper script can help to keep your copyright dates
208 up-to-date when you make further changes to files which already have your
209 copyright but with older dates.
211 Note: If you do not follow these guidelines, the gerrit review site will
212 automatically reject your patch.
213 If this happens, update your changeset descriptions to match the required style
214 and resubmit. The following is a useful git command to update the most recent
215 commit (HEAD).
217 ```
218 git commit --amend
219 ```
221 Running tests
222 =============
224 Before posting a change to the code review site, you should always run the
225 quick tests!
226 See TESTING.md for more information.
228 Posting a review
229 ================
231 If you have not signed up for an account on the Gerrit review site
232 (https://gem5-review.googlesource.com), you first have to create an account.
234 Setting up an account
235 ---------------------
236 1. Go to https://gem5.googlesource.com/
237 2. Click "Sign In" in the upper right corner. Note: You will need a Google
238 account to contribute.
239 3. After signing in, click "Generate Password" and follow the instructions.
241 Submitting a change
242 -------------------
244 In gerrit, to submit a review request, you can simply push your git commits to
245 a special named branch. For more information on git push see
246 https://git-scm.com/docs/git-push.
248 There are three ways to push your changes to gerrit.
250 Push change to gerrit review
251 ----------------------------
253 ```
254 git push origin HEAD:refs/for/develop
255 ```
257 Assuming origin is https://gem5.googlesource.com/public/gem5 and you want to
258 push the changeset at HEAD, this will create a new review request on top of the
259 develop branch. More generally,
261 ```
262 git push <gem5 gerrit instance> <changeset>:refs/for/<branch>
263 ```
265 See https://gerrit-review.googlesource.com/Documentation/user-upload.html for
266 more information.
268 Pushing your first change
269 --------------------------
270 The first time you push a change you may get the following error:
272 ```
273 remote: ERROR: [fb1366b] missing Change-Id in commit message footer
274 ...
275 ```
277 Within the error message, there is a command line you should run. For every new
278 clone of the git repo, you need to run the following command to automatically
279 insert the change id in the the commit (all on one line).
281 ```
282 curl -Lo `git rev-parse --git-dir`/hooks/commit-msg \
283 https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; \
284 chmod +x `git rev-parse --git-dir`/hooks/commit-msg
285 ```
287 If you receive the above error, simply run this command and then amend your
288 changeset.
290 ```
291 git commit --amend
292 ```
294 Push change to gerrit as a Work In Progress
295 -------------------------------------------
297 It is acceptable to push commits as "Work In Progress" (WIP) changes within
298 gerrit. WIP changes are publicly visible though no one will be able to review
299 the changes or be directly notified they have been submitted. WIP changes can
300 be useful for backing up code currently under-development or for sharing
301 incomplete code with the wider community (i.e., the link to the gerrit change
302 may be shared, and others may download the change, comment on it, and track
303 alterations over time).
305 See https://gerrit-review.googlesource.com/Documentation/intro-user.html#wip
306 for details on WIP gerrit changes.
308 To push a change as a WIP:
310 ```
311 git push origin HEAD:refs/for/develop%wip
312 ```
314 Once you have pushed your change as a WIP, you can log onto [gerrit](
315 https://gem5-review.googlesource.com) and view it. Once you're happy with the
316 change you can add reviewers which shall move your change from WIP status
317 to be considered for submission by the wider gem5 community. Switching from a
318 WIP to a regular change does not notify the gem5 community, via the gem5-dev
319 mailing-list, that a change has been submitted (as would occur if a change were
320 submitted directly for review). It is therefore important to include reviewers
321 and CC those who you wish to view the change (they will be notified
322 automatically via email).
324 Push change bypassing gerrit
325 -----------------------------
327 Only maintainers can bypass gerrit review. This should very rarely be used.
329 ```
330 git push origin HEAD:refs/heads/develop
331 ```
333 Other gerrit push options
334 -------------------------
336 There are a number of options you can specify when uploading your changes to
337 gerrit (e.g., reviewers, labels). The gerrit documentation has more
338 information.
339 https://gerrit-review.googlesource.com/Documentation/user-upload.html
341 Branches
342 ========
344 By default, contributions to gem5 should be made on the develop branch. The
345 stable branch is maintained as a stable release branch (i.e., it can be pulled
346 to obtain the latest official release of gem5). Creation of additional branches
347 is generally discouraged due to their tendency to bloat git repositories with
348 abandoned code. However, the creation of new branches is permitted for
349 development of a specific feature or improvement if one or more of the
350 following criteria are met:
352 1. The feature/improvement is likely to be of a large size, consisting of many
353 commits, with little logic in these commits being contributed separately.
354 2. The feature/improvement will be developed over a long period of time.
355 3. There is sufficient reason that a feature/improvement should not be part
356 of the next gem5 release (e.g., the change should be held within a feature
357 branch until ready for the next release, at which point it will be merged
358 into the develop branch).
360 If a branch is required it can only be created by a project maintainer.
361 Therefore, if a gem5 contributor desires a separate branch for their work, they
362 should request one from the maintainer of the component the work relates to
363 (see MAINTAINERS for the list of maintainers and the components they are
364 responsible for). **The maintainer shall use their discretion to determine
365 whether the creation of a branch is necessary**. If approved, the maintainer
366 shall create the branch which the contributor may then use.
368 Development on a branch within Gerrit functions in exactly the same way as
369 contributing to the develop branch. When contributors to a branch are
370 satisfied, they should create a merge commit into the develop branch. The
371 maintainer should then be notified that the branch they created can now be
372 deleted.
374 **Abandonment of changes within branches may result in these branches being
375 removed from the repository. All branches within a repo should be under active
376 development.**
378 Reviewing patches
379 =================
381 Reviewing patches is done on our gerrit instance at
382 https://gem5-review.googlesource.com/.
384 After logging in with your Google account, you will be able to comment, review,
385 and push your own patches as well as review others' patches. All gem5 users are
386 encouraged to review patches. The only requirement to review patches is to be
387 polite and respectful of others.
389 There are multiple labels in Gerrit that can be applied to each review detailed
390 below.
391 * Code-review: This is used by any gem5 user to review patches. When reviewing
392 a patch you can give it a score of -2 to +2 with the following semantics.
393 * -2: This blocks the patch. You believe that this patch should never be
394 committed. This label should be very rarely used.
395 * -1: You would prefer this is not merged as is
396 * 0: No score
397 * +1: This patch seems good, but you aren't 100% confident that it should be
398 pushed.
399 * +2: This is a good patch and should be pushed as is.
400 * Maintainer: Currently only PMC members are maintainers. At least one
401 maintainer must review your patch and give it a +1 before it can be merged.
402 * Verified: This is automatically generated from the continuous integrated
403 (CI) tests. Each patch must receive at least a +1 from the CI tests before
404 the patch can be merged. The patch will receive a +1 if gem5 builds and
405 runs, and it will receive a +2 if the stats match.
406 * Style-Check: This is automatically generated and tests the patch against the
407 gem5 code style
408 (http://www.gem5.org/documentation/general_docs/development/coding_style/).
409 The patch must receive a +1 from the style checker to be pushed.
411 Note: Whenever the patch creator updates the patch all reviewers must re-review
412 the patch. There is no longer a "Fix it, then Ship It" option.
414 Once you have received reviews for your patch, you will likely need to make
415 changes. To do this, you should update the original git changeset. Then, you
416 can simply push the changeset again to the same Gerrit branch to update the
417 review request.
419 ```
420 git push origin HEAD:refs/for/develop
421 ```
423 Committing changes
424 ==================
426 Each patch must meet the following criteria to be merged:
427 * At least one review with +2
428 * At least one maintainer with +1
429 * At least +1 from the CI tests (gem5 must build and run)
430 * At least +1 from the style checker
432 Once a patch meets the above criteria, the submitter of the patch will be able
433 to merge the patch by pressing the "Submit" button on Gerrit. When the patch is
434 submitted, it is merged into the public gem5 branch.
436 Review moderation and guidelines
437 --------------------------------
439 Once a change is submitted, reviewers shall review the change. This may require
440 several iterations before a merge. Comments from reviewers may include
441 questions, and requests for alterations to the change prior to merging. The
442 overarching philosophy in managing this process is that there should be
443 politeness and clear communication between all parties at all times, and,
444 whenever possible, permission should be asked before doing anything that may
445 inconvenience another party. Included below are some guidelines we expect
446 contributors and reviewers to follow.
448 * In all forms of communication, contributors and reviewers must be polite.
449 Comments seen as being needlessly hostile or dismissive will not be
450 tolerated.
451 * Change contributors should respond to, or act upon, each item of feedback
452 given by reviewers. If there is disagreement with a piece of
453 feedback, a sufficiently detailed reason for this disagreement should
454 be given. Polite discussion, and sharing of information and expertise
455 is strongly encouraged.
456 * Contributors are advised to assign reviewers when submitting a change.
457 Anyone who contributes to gem5 can be assigned as a reviewer. However,
458 all changes must be accepted by at least one maintainer prior to a
459 merge, ergo assigning of at least one maintainer as a reviewer is
460 strongly recommended. Please see MAINTAINERS for a breakdown of
461 gem5 maintainers and which components they claim responsibility for.
462 Maintainers should be chosen based on which components the change is
463 targeting. Assigning of reviewers is not strictly enforced, though not
464 assigning reviewers may slow the time in which a change is reviewed.
465 * If a contributor posts a change and does not receive any reviews after two
466 working days (excluding regional holidays), it is acceptable to "prod"
467 reviewers. This can be done by adding a reply to the changeset review
468 (e.g., "Would it be possible for someone to review my change?"). If the
469 contributor has yet to assign reviewers, they are strongly advised to do so.
470 Reviewers will get notified when assigned to referee a change.
471 * By default, the original contributor is assumed to own a change. I.e.,
472 they are assumed to be the sole party to submit patchsets. If someone
473 other than the original contributor wishes to submit patchsets to a
474 change on the original contributor's behalf, they should first ask
475 permission. If two working days pass without a response, a patchset may be
476 submitted without permission. Permission does not need to be asked to submit
477 a patchset consisting of minor, inoffensive, changes such a typo and format
478 fixes.
479 * Once a change is ready to merge, it enters a "Ready to Submit" state. The
480 original contributor should merge their change at this point, assuming they
481 are content with the commit in its present form. After two working days, a
482 reviewer may message a contributor to remind them of the change being in a
483 "Ready to Submit" state and ask if they can merge the change on the
484 contributors behalf. If a further two working days elapse without a
485 response, the reviewer may merge without permission. A contributor may keep
486 a change open for whatever reason though this should be communicated to the
487 reviewer when asked.
488 * After a month of inactivity from a contributor on an active change, a
489 reviewer may post a message on the change reminding the submitter, and
490 anyone else watching the change, of its active status and ask if they are
491 still interested in eventually merging the change. After two weeks of no
492 response the reviewer reserves the right to abandon the change under the
493 assumption there is no longer interest.
494 * The final arbiter in any dispute between reviewers and/or contributors
495 is the PMC (PMC members are highlighted in MAINTAINERS). Disputes requiring
496 intervention by the PMC are undesirable. Attempts should be made to resolve
497 disagreements via respectful and polite discourse before being escalated to
498 this level.
500 Releases
501 ========
503 gem5 releases occur 3 times per year. The procedure for releasing gem5 is as
504 follows:
506 1. Developers will be notified, via the gem5-dev mailing list, that a new
507 release of gem5 will occur. This should be no sooner than 2 weeks prior to the
508 creation of the staging branch (the first step in releasing a new version of
509 gem5). This gives time for developers to ensure their changes for the next
510 release are submitted to the develop branch.
511 2. When a release is ready, a new staging branch shall be created by a project
512 maintainer, from develop, with the name "release-staging-{VERSION}". The
513 gem5-dev mailing list will be notified that the staging branch will be merged
514 into the stable branch after two weeks, thus marking the new release.
515 3. The staging branch will have the full suite of gem5 tests run on it to
516 ensure all tests pass and the to-be-released code is in a decent state.
517 4. If a user submits a changeset to the staging branch, it will be considered
518 and undergo the standard Gerrit review process. However, only alterations that
519 cannot wait until the following release will be accepted for submission into
520 the branch (i.e., submissions to the staging branch for "last minute"
521 inclusions to the release should be of a high priority, such as a critical bug
522 fix). The project maintainers will use their discretion in deciding whether a
523 change may be submitted directly to the staging branch. All other submissions
524 to gem5 will continue to be made to the develop branch. Patches submitted
525 into the staging branch do not need to be re-added to the develop branch.
526 5. Once signed off by members of the PMC the staging branch shall be merged
527 into the stable and develop branch. The staging branch will then be deleted.
528 6. The stable branch shall be tagged with the correct version number for that
529 release. gem5 conforms to a "v{YY}.{MAJOR}.{MINOR}.{HOTFIX}" versioning system.
530 E.g., the first major release of 2022 will be "v22.0.0.0", followed by
531 "v22.1.0.0". All the releases (with the exception of hotfixes) are considered
532 major releases. For the meantime, there are no minor releases though we keep
533 the minor release numbers in case this policy changes in the future.
534 7. The gem5-dev and gem5-user mailing lists shall be notified of the new gem5
535 release.
537 Hotfixes
538 --------
540 There may be circumstances in which a change to gem5 is deemed critical and
541 cannot wait for an official release (e.g., a high-priority bug fix). In these
542 circumstances a hotfix shall be made.
544 First, if a developer suspects a hotfix may be necessary then the issue
545 should be discussed on the gem5-dev mailing list. The community will decide
546 whether the issue is worthy of a hotfix, and the final decision should be
547 made by members of the PMC if there is no consensus. Assuming the hotfix is
548 permitted, the following steps will be taken:
550 1. A new branch with the prefix "hotfix-" will be created from the stable
551 branch. Only gem5 maintainers can create branches. If a non-maintainer requires
552 the creation of a hotfix branch then they should contact a gem5 maintainer.
553 2. The change shall be submitted to the hotfix branch via gerrit. Full review,
554 as with any other change, will be required.
555 3. Once fully submitted, the hotfix branch shall be merged into both the
556 develop and the stable branch by a gem5 maintainer.
557 4. The stable branch will be tagged with the new version number; the same as
558 the last but with an incremented hotfix number (e.g., "v20.2.0.0" would
559 transition to "v20.2.0.1").
560 4. The hotfix branch will then be deleted.
561 5. The gem5-dev and the gem5-user mailing lists shall be notified of this
562 hotfix.