Difference between revisions of "Commit Access"

Revision as of 18:11, 6 November 2009

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 80 column line of text describing the changeset, followed by whatever further detail. example:

SCons: fixed the way the build system handled ISAs
Please keep your 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. MQ helped you to make your changesets into useful logical pieces that other people can review. Now you can use the http://mercurial.selenic.com/wiki/PatchbombExtension which provides the hg email command to send out your changesets for review.
  • If you "own" a part of the tree, you are the final authority on that code, but it's still advised that you seek feedback. More eyeballs on code means fewer bugs
• 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 Style Guide. 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.