|
|
| (25 intermediate revisions by 7 users not shown) |
| Line 1: |
Line 1: |
| − | 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.
| + | #REDIRECT [[Submitting Contributions]] |
| − | | |
| − | === Short Summary ===
| |
| − | # Learn how to use Mercurial (HG) and Mercurial Queues (MQ) | |
| − | # Break up your changes into meaningful, self contained pieces (and use MQ to help)
| |
| − | # Create meaningful commit messages and make sure that your name is on them
| |
| − | # Read your patches <tt>hg diff</tt>, <tt>hg qdiff</tt>, <tt>hg export</tt>, and <tt>.hg/patches</tt>
| |
| − | # Get code reviews <tt>hg email</tt>
| |
| − | # Make sure everything compiles
| |
| − | # Make sure regressions pass
| |
| − | # Commit your changes/Finish your patches <tt>hg commit</tt> or <tt>hg qfinish</tt>
| |
| − | # Check what you're pushing before you push <tt>hg outgoing</tt>
| |
| − | # Contribute your changes <tt>hg push</tt>
| |
| − | | |
| − | === Details ===
| |
| − | * Learn how [http://mercurial.selenic.com/wiki/Tutorial to] [http://hgbook.red-bean.com/read/ use] [http://mercurial.selenic.com/guide/ 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 [http://mercurial.selenic.com/wiki/MqExtension 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. [http://hgbook.red-bean.com/read/managing-change-with-mercurial-queues.html More] [http://hgbook.red-bean.com/read/advanced-uses-of-mercurial-queues.html info] and a [http://mercurial.selenic.com/wiki/MqTutorial tutorial] are available.
| |
| − | ** Please don't forget to put commit messages on your patch. The <tt>-m</tt> option to <tt>hg qref</tt> 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:
| |
| − | <pre>
| |
| − | 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.
| |
| − | </pre>
| |
| − | * 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 Patchbomb Extension] which provides the <tt>hg email</tt> 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 <tt>hg qfinish</tt> 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 <tt>hg outgoing</tt>. Are you about to push what you think you are? Do the commit messages all make sense? Ok, go ahead and <tt>hg push</tt>
| |
| − | * 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 <tt>$HOME/.hgrc</tt> file before you start making changesets (<tt>hg commit</tt> or <tt>hg qfinish</tt>)
| |
| − | <pre>
| |
| − | [ui]
| |
| − | username=Nathan Binkert <nate@binkert.org>
| |
| − | </pre>
| |
| − | * 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.
| |
