Commit Access

So, you have commit access to the M5 repository. That's fantastic, we're glad that you're willing to help out. We're relatively light on process, but there are some important things that you need to know before you go changing the repository.

Short Summary

1. Learn how to use Mercurial (HG) and Mercurial Queues (MQ)
2. Break up your changes into meaningful, self contained pieces (and use MQ to help)
3. Create meaningful commit messages and make sure that your name is on them
4. Read your patches hg diff, hg qdiff, hg export, and .hg/patches
5. Get code reviews hg email
6. Make sure everything compiles
7. Make sure regressions pass
8. Commit your changes/Finish your patches hg commit or hg qfinish
9. Check what you're pushing before you push hg outgoing
10. Contribute your changes hg push

Details

• Learn how to use mercurial. If you don't know what you're doing, please ask questions and ask for help. The tool does take some getting used to, but breaking the tree is not something that is fun to clean up.
• When you've got something that you want to commit, think about what it does and who it might affect. Is it self contained? Can it be broken up into more logical segments?
  • M5 is a big project and there are a lot of people working on it. No one person knows everything, so we rely on the revision history and on comments to understand what is going on in the code. It is very important that you make change sets self contained. It is far easier to understand a series of ten 200 line changesets and what they do compared to a single 2000 change set that does a whole lot of stuff. This will also help you as a developer. If you keep your changesets small and self contained and you read them regularly, you will find your own bugs before you commit them.
  • You really really really should use Mercurial Queues (MQ). It makes this whole process so much easier. MQ does take a little bit to get used to, but I guarantee they make life easier for everyone. More info and a tutorial are available.
  • Please don't forget to put commit messages on your patch. The -m option to hg qref will allow you to do this. Commit messages should have a keyword, followed by a colon followed by a single line of text summarizing the changeset, followed optionally by additional lines with further detail. The first line should be no more than 65 characters, since it's preceded by summary: in the brief hg log output. For example:

SCons: fixed the way the build system handled ISAs
Note the keyword and colon on the first line, and that it's < 65 chars.
Please keep your detailed commit comments to 80 columns.  These comments
will likely have to be wrapped manually, but that's not so bad a thing
to have to do.

• Now that you've made small, self contained changesets, you should seek feedback from people. We have our own Reviewboard server for this process. You can use the Reviewboard Extension which provides the hg postreview command to send out your changesets for review. Some Tips:
  • If you want to post a review for the changeset at the tip, use "hg postreview -o"
  • If you want to update a review for the changeset at the tip, use "hg postreview -o -u -e <number>", where <number> is the review number on reviewboard.
  • Everything is easier if you are using Mercurial Queues as you can use "hg qpush" and "hg qpop" to get your diff to the tip and then use the postreview commands above.
• Now that you've gotten feedback and incorporated it into your changesets, you can hg qfinish the relevant patches to turn them into changesets. Before you do this, ask yourself: Have I compiled this code in all ISAs and emulations that it could affect? Have I run the regression tests that are relevant? (You should run at least the quick regressions and the long too if you think you're going to change anything.) You really should avoid breaking the tree with trivial things that can be caught by these two steps.
• Ok, so you're ready to push your changesets to the repository. One last step. Run hg outgoing. Are you about to push what you think you are? Do the commit messages all make sense? Ok, go ahead and hg push
• We want to be able to identify everyone who makes a change to the repository, so we need your name to show up in a consistent manner in the repository. Please dd this to your $HOME/.hgrc file before you start making changesets (hg commit or hg qfinish)

[ui]
username=Nathan Binkert <nate@binkert.org>

• Please try to follow the Coding Style. They make search and replace much more effective. It also makes it easier for developers to follow code if it all has a similar look. I'm sure that there are things that you hate about the style. I've never worked on a project where everyone liked the style, unless they've all worked on the project for a long time and just gotten used to it.