Labs/Bespin/DeveloperGuide/UsingMercurial: Difference between revisions

Latest revision as of 18:33, 9 November 2009

Here are some tips about using Mercurial, based on our experiences managing the Bespin project with it.

Getting Started

Our main code repository is hosted at http://hg.mozilla.org/labs/bespinclient. You can pull from that by:

Downloading Mercurial
Configuring your environment. For example you will at least want to setup a username. I use:

[ui]
username = Dion Almaer <dion@mozilla.com>

[extensions]
rebase =
hgext.extdiff =

[extdiff]
cmd.opendiff = opendiff-w

[merge-tools]
filemerge.executable = opendiff-w
filemerge.args = $local $other -ancestor $base -merge $output

Setup a bitbucket.org account that you can use as your repository
- clone Bespin from our repo to yours and then checkout THAT repo locally to work on

Read up:
- Mozilla on Mercurial
- Mercurial Definitive Guide

Best Practices

Use "hg pull --rebase"
- You need the "rebase =" line in your config
- It will automatically handle merging, so instead of manually doing hg pull / hg merge, just do hg pull --rebase and let it do its job. By rebasing, we don't end up with lots of merge commits in the history.

Look ahead
- You can fetch away at will, but you can also run "hg incoming http://..." to see what would get pulled in. I have sometimes done this to release that there are a bunch of branches in there, and then I change my pull to only pull the tip default branch

Eek, broken! How do I get back!
- If you do a fetch/pull and something messes up (or any operation) you can do a "hg rollback" to revert back

When checking in, use the bug number at the beginning of the message and then the web view will auto link to the bug.
- E.g. hg ci -m "487459: Fixes the selection bug in Safari with -webkit-user-select: none;"

Contributing Back

When you are ready to send code back to the main repository, please take a look at Contributing to Bespin.

@@ Line 1: / Line 1: @@
-We have had some pain working with Mercurial, so thought it best to write up the best practices on how to work with it as relating to the Bespin project.
+Here are some tips about using Mercurial, based on our experiences managing the Bespin project with it.
-For now I will put up some notes, and then we will groom these more:
 ==== Getting Started ====
-Our main code repository is hosted at http://hg.mozilla.org/labs/bespin. You can pull from that by:
+Our main code repository is hosted at http://hg.mozilla.org/labs/bespinclient. You can pull from that by:
 * [http://www.selenic.com/mercurial/wiki/ Downloading Mercurial]
@@ Line 14: / Line 12: @@
   [extensions]
-  fetch =
+  rebase =
   hgext.extdiff =
@@ Line 26: / Line 24: @@
 * Setup a bitbucket.org account that you can use as your repository
 ** clone Bespin from our repo to yours and then checkout THAT repo locally to work on
+* Read up:
+** [https://developer.mozilla.org/en/Mozilla_Source_Code_%28Mercurial%29 Mozilla on Mercurial]
+** [http://hgbook.red-bean.com/ Mercurial Definitive Guide]
 ==== Best Practices ====
-* Use "hg fetch"
+* Use "hg pull --rebase"
-** You need the "fetch =" line in your config
+** You need the "rebase =" line in your config
-** It will automatically handle merging, so instead of manually doing hg pull / hg merge, just do hg fetch and let it do its job
+** It will automatically handle merging, so instead of manually doing hg pull / hg merge, just do hg pull --rebase and let it do its job. By rebasing, we don't end up with lots of merge commits in the history.
-* Do not use branches
-** hg is poor with branches, so we have learned to instead create other cloned repos for large chunks of work, and merge from repo to repo
 * Look ahead
@@ Line 41: / Line 40: @@
 * Eek, broken! How do I get back!
 ** If you do a fetch/pull and something messes up (or any operation) you can do a "hg rollback" to revert back
+* When checking in, use the bug number at the beginning of the message and then the web view will auto link to the bug.
+** E.g. hg ci -m "487459: Fixes the selection bug in Safari with -webkit-user-select: none;"
 ==== Contributing Back ====
-When you are ready to get code back to the main repo, consider the following:
+When you are ready to send code back to the main repository, please take a look at [[Labs/Bespin/Contributing|Contributing to Bespin]].
-* First, fetch from the main repo and merge the latest with your own code
-* Test your code (we need automated tests!)
-* Send us a pull request:
-** Update a bug saying "I am ready for a pull on changeset XXXX on my repo at http://bitbucket.org/...."
-** Ping us on IRC
-** Optionally, you could attach a bundle, but we *much* prefer a pull request