Development:Committing - Revision history

Sardisson: /* Figuring out what patches (commits) you are pushing to the remote repository */ add the caveat here

2011-07-11T04:56:22Z

Figuring out what patches (commits) you are pushing to the remote repository: add the caveat here

Sardisson: /* Add a hook to ensure complete checkin messages */ no after-the-fact correction

2010-08-16T19:47:20Z

Add a hook to ensure complete checkin messages: no after-the-fact correction

Sardisson: /* Figuring out what patches (commits) you are pushing to the remote repository */ and yet, it is echoURL

2010-06-05T04:34:15Z

Figuring out what patches (commits) you are pushing to the remote repository: and yet, it is echoURL

Sardisson: /* Mercurial */ add echoURL

2010-06-05T04:33:41Z

Mercurial: add echoURL

Sardisson: edit this to be more stand-alone for committers and add some additional info

2010-05-27T01:38:32Z

edit this to be more stand-alone for committers and add some additional info

Sardisson: Commit existing "Checking In" section of Development:Coding wholesale; editing to come

2010-05-27T01:07:00Z

Commit existing "Checking In" section of Development:Coding wholesale; editing to come

New page

== Checking In ==
After a patch has '''review+''' from two reviewers and '''superreview+''' from one of the Camino leads, it needs to be checked in.

Check-ins for Camino can be made by any of the super-reviewers listed above as well as ardissone, froodian, hwaara and kreeger (note that froodian, hwaara, kreeger, and smfr are not currently checking in Camino patches, nor, with some exceptions, will pinkerton or mento check in patches they have not written).

If no one is around to check in your patch after it has received the requisite approvals, add <tt>checkin-needed</tt> to the bug's Keyword field and one of the committers should notice and land your patch within a day or so. If they do not, make a comment in the bug or on [irc://irc.mozilla.org#camino IRC].

Also note that the <tt>mozilla/camino</tt> directory hierarchy is open for approved Camino check-ins regardless of the state of various trees and branches, with a few exceptions, such as tagging of major branches, red Camino tinderboxen, missing Camino perf or nightly tinderboxen, etc.

'''N.B''' When the Camino tree is closed while the Mozilla tree is closed, there is typically a note on the [http://tinderbox.mozilla.org/showbuilds.cgi?tree=Camino Camino tinderbox] explaining the closure, and the closure is often mentioned in the “topic” in the [irc://irc.mozilla.org#camino #camino] channel on IRC. '''However''', when the opposite is true—Mozilla is closed and Camino is open—there is typically no indication of the fact. If you are unsure of the state of the Camino tree, ask on in the [irc://irc.mozilla.org#camino #camino] channel on IRC.

===Checkin tips for new (and old) committers===

====Mercurial====

Remember that Hg is a distributed VCS, so that most operations are local. In particular, where “committing” to the official repository was a single operation with CVS (<code>cvs commit</code>), it is a pair of operations with Hg (the local-only <code>hg commit</code> and the local-to-remote <code>hg push</code>).

=====Configuration changes to allow you to check code into the official repository=====

In order to be able to push changes to a remote hg repository, you will need to make a pair of configuration changes:

# If you do not already have a <code>~/.ssh/config</code> file to help manage your ssh connections, create the file using your favorite text editor. Once the file exists, insert the following lines:<pre><nowiki>Host hg.mozilla.org
User user@domain.tld</nowiki></pre> (where ''user@domain.tld'' is the email address associated with your Mozilla Hg/LDAP account)
# In each local clone from which you wish to push changes (e.g., <code>mozilla-1.9.2</code> and <code>camino</code>), edit the <code>.hg/hgrc</code> file and add a <code>default-push</code> line. The <code>default-push</code> line should look exactly the same as the <code>default</code> line, except you should replace <code>default</code>’s <code>http://</code> with <code>ssh://</code>. For example, the <code>.hg/hgrc</code> file for the <code>camino</code> repository should look like this:<pre><nowiki>[paths]
default = http://hg.mozilla.org/camino/
default-push = ssh://hg.mozilla.org/camino/</nowiki></pre>

=====Add a hook to ensure complete checkin messages=====

For some reason Camino committers appear far more likely to drop a required part of the commit message with Hg commits than we did with CVS. An easy way to prevent bad commit messages is to use a “hook” that checks your commit message for required data and aborts the commit with a helpful error when the data is missing.

Smokey has written a hook that ensures commit messages contain the bug number and at least one reviewer or superreviewer: [http://hg.mozilla.org/users/alqahira_ardisson.org/misc/file/tip/bugnum bugnum]. By default the <code>bugnum</code> hook only enforces these commit message rules for <code>mozilla-*</code> and <code>camino</code>, so you can use the script as a global hook and still commit to other Hg repositories that don’t require bug numbers or reviews, or you can customize the hook to add additional repositories to the <code>grep</code> pattern in order to enforce the rules on additional repositories.

# Install the <code>bugnum</code> script somewhere and make sure that it is executable.
# Add the following lines to your <code>~/.hgrc</code> file:<pre><nowiki>[hooks]
pretxncommit.bugnum = /path/to/bugnum $HG_NODE</nowiki></pre> (If, for some reason, you don’t want a global hook, you can instead add these lines to the <code>.hg/hgrc</code> file inside each individual repository where you want to use the hook.)

For more about Hg hooks, see [http://hgbook.red-bean.com/read/handling-repository-events-with-hooks.html Chapter 10. Handling repository events with hooks] in the Hg book.

=====Checking in patches from others=====

Mercurial has a way of recording the actual patch author even when someone else is committing and pushing the patch. When you’re committing a patch written by someone else, use the following commit command syntax:<pre><nowiki>hg commit -u "Patch Author <camino.dev@example.org>" -m "Complete commit message" file1 file2</nowiki></pre>

If you find yourself committing patches for someone else frequently, you can add an alias to your <code>~/.hgrc</code> file to save you some typing:<pre><nowiki>[alias]
patchGuy = commit -u "Patch Author <camino.dev@example.org>"</nowiki></pre>

Then commit all of Patch Author’s patches using <code>$ hg patchGuy -m "Complete commit message" file1 file2</code>.

=====Figuring out what patches (commits) you are pushing to the remote repository=====

Once you’ve committed some patches and are ready to push them to the official repository, you can sanity-check what you’re about to send by using the <code>hg outgoing</code> command. If the list of patches (commits) looks correct, <code>hg push</code> will send them to the remote repository. Be sure to paste the changeset URLs in the bug when resolving it!

====CVS====

=====Checking in nibs=====
Sometimes a person who doesn't have CVS access will post a new or updated nib on a bug that needs to be checked in. The problem with this is that since a nib is technically a directory, there is a CVS folder inside the nib. If you attempt to check in a nib that has been changed by someone who has the <tt>CVSROOT</tt> set as "<tt>:pserver:anonymous@cvs-mirror.mozilla.org:/cvsrooot</tt>" (''e.g.'', everyone without cvs write access), you will receive an authorization error from cvs. The problem is that the <tt>CVS/Root</tt> file is set as the anonymous <tt>CVSROOT</tt>, not your "<tt>user%email.com@cvs.mozilla.org:/cvsroot</tt>" <tt>CVSROOT</tt>.

The easiest way to fix this problem is to copy a <code>Root</code> file from one of the directories you have pulled to and paste it inside the <tt>Something.nib/CVS</tt> folder.

Alternatively, instead of dropping that person’s nib in place, use <code> cp /path/to/other/nib/*.nib /path/to/your/tree/nib; touch /path/to/your/nib</code> to copy their nib files into your tree.

=====Trunk/branch mismatches=====
Sometimes (due mostly to Gecko changes on the trunk) the trunk and branch versions of a patch will diverge and you can't use cross-commit to land both places. '''If you're confident the branch patch has been well-tested''' and don't have a branch tree, you can pull just the files you need to commit (rather than pull an entire tree).

# Set up your cvs environment as normal (i.e., <code>export cvsroot</code>)
# <code>cvs co -r MOZILLA_1_8_BRANCH -d myfolder mozilla/camino/src/browser/foo mozilla/camino/PreferencePanes/Naviagtion/bar</code>
#: where <code>MOZILLA_1_8_BRANCH</code> is the branch tag, <code>myfolder</code> is the folder in which you want the stub tree to live, and <code>foo</code> and <code>bar</code> are the files contained in the patch
# Apply the patch and commit the files "as normal"

=====Backing out a patch=====
Sometimes you accidentally commit something that shouldn't have landed yet, or sometimes (hopefully rarely) you commit something that breaks the tree and needs to be backed out. To back out a patch, follow these steps:

# If you need to back out something only on the branch and have no branch tree (i.e., you check in using cross-commit), follow the steps above to grab a "stub" branch tree of the files the patch touched.
# Consult bonsai for the correct backout command(s) to pull files (one per file) to run
#: The "Show commands which could be used to back out these changes" link at the top of the appropriate bonsai page will give you the appropriate command, in the form of<br> <code>cvs update -j1.17.2.4 -j1.17.2.3 mozilla/camino/src/embedding/CHClickListener.mm</code><br>There will be one command per file (this particular example is a branch file, as you can see from the multiple sub-versions; the current [bad] version of the file is listed first and the previous [good] version is second)
# <code>touch</code> each file
# <code>cvs diff -u</code> the file(s) to sanity-check that the bad changes have been reverted in your local copy of the files
# <code>cvs commit</code> "as normal"; this will commit a new copy of the file(s) with the incorrect change backed out

=====Adding new files=====
* <code>cvs add</code>
* <code>cvs add -kb</code> for any binary files, including images, UTF-16-encoded files (e.g., <code>.strings</code> files from external projects), and <code>keyedobjects.nib</code> files inside .nibs.

=====Adding new nibs=====
* <code>cvs add</code> the wrapper directory
* <code>cvs add -kb</code> on '''keyedobjects.nib'''
* <code>cvs add</code> on the remaining .nib files inside the wrapper directory
<pre>[Qalaat-Samaan:trunk/mozilla/camino] smokey% cvs add resources/localized/English.lproj/SafeBrowsingBar.nib
? resources/localized/English.lproj/SafeBrowsingBar.nib/classes.nib
? resources/localized/English.lproj/SafeBrowsingBar.nib/info.nib
? resources/localized/English.lproj/SafeBrowsingBar.nib/keyedobjects.nib
Directory /cvsroot/mozilla/camino/resources/localized/English.lproj/SafeBrowsingBar.nib added to the repository
[Qalaat-Samaan:trunk/mozilla/camino] smokey% cvs add -kb resources/localized/English.lproj/SafeBrowsingBar.nib/keyedobjects.nib
cvs add: scheduling file `resources/localized/English.lproj/SafeBrowsingBar.nib/keyedobjects.nib' for addition
cvs add: use 'cvs commit' to add this file permanently
[Qalaat-Samaan:trunk/mozilla/camino] smokey% cvs add resources/localized/English.lproj/SafeBrowsingBar.nib/classes.nib resources/localized/English.lproj/SafeBrowsingBar.nib/info.nib
cvs add: scheduling file `resources/localized/English.lproj/SafeBrowsingBar.nib/classes.nib' for addition
cvs add: scheduling file `resources/localized/English.lproj/SafeBrowsingBar.nib/info.nib' for addition
cvs add: use 'cvs commit' to add these files permanently</pre>

@@ Line 57: / Line 57: @@
 Once you’ve committed some patches and are ready to push them to the official repository, you can sanity-check what you’re about to send by using the <code>hg outgoing</code> command.  If the list of patches (commits) looks correct, <code>hg push</code> will send them to the remote repository.
-Be sure to paste the changeset URLs in the bug when resolving it (the [http://hg.mozilla.org/users/alqahira_ardisson.org/misc/file/tip/echoURL echoURL] hook can help with that)!
+Be sure to paste the changeset URLs in the bug when resolving it (the [http://hg.mozilla.org/users/alqahira_ardisson.org/misc/file/tip/echoURL echoURL] hook can help with that, at least for the first changeset of a push)!
 ===CVS===

@@ Line 57: / Line 57: @@
 Once you’ve committed some patches and are ready to push them to the official repository, you can sanity-check what you’re about to send by using the <code>hg outgoing</code> command.  If the list of patches (commits) looks correct, <code>hg push</code> will send them to the remote repository.
-Be sure to paste the changeset URLs in the bug when resolving it (the [http://hg.mozilla.org/users/alqahira_ardisson.org/misc/file/tip/bugnum echoURL] hook can help with that)!
+Be sure to paste the changeset URLs in the bug when resolving it (the [http://hg.mozilla.org/users/alqahira_ardisson.org/misc/file/tip/echoURL echoURL] hook can help with that)!
 ===CVS===

@@ Line 34: / Line 34: @@
 ====Add a hook to ensure complete checkin messages====
-For some reason Camino committers appear far more likely to drop a required part of the commit message with Hg commits than we did with CVS.  An easy way to prevent bad commit messages is to use a “hook” that checks your commit message for required data and aborts the commit with a helpful error when the data is missing.
+For some reason Camino committers appear far more likely to drop a required part of the commit message with Hg commits than we did with CVS.  An easy way to prevent bad commit messages is to use a “hook” that checks your commit message for required data and aborts the commit with a helpful error when the data is missing (particularly since Hg commit messages cannot be corrected after the fact, unlike with CVS).
 Smokey has written a hook that ensures commit messages contain the bug number and at least one reviewer or superreviewer: [http://hg.mozilla.org/users/alqahira_ardisson.org/misc/file/tip/bugnum bugnum].  By default the <code>bugnum</code> hook only enforces these commit message rules for <code>mozilla-*</code> and <code>camino</code>, so you can use the script as a global hook and still commit to other Hg repositories that don’t require bug numbers or reviews, or you can customize the hook to add additional repositories to the <code>grep</code> pattern in order to enforce the rules on additional repositories.

@@ Line 1: / Line 1: @@
-== Checking In ==
+After a patch has '''review+''' from two reviewers and '''superreview+''' from one of the Camino leads, it needs to be committed to one or more of Camino’s code repositories.
-Check-ins for Camino can be made by any of the super-reviewers listed above as well as ardissone, froodian, hwaara and kreeger (note that froodian, hwaara, kreeger, and smfr are not currently checking in Camino patches, nor, with some exceptions, will pinkerton or mento check in patches they have not written).
+Check-ins for Camino can be made by any of the super-reviewers listed [[Development:Reviewing#.E2.80.9CSuper.E2.80.9D_Reviews|here]], as well as ardissone, froodian, hwaara and kreeger (note that froodian, hwaara, kreeger, and smfr are not currently checking in Camino patches, nor, with some exceptions, will pinkerton or mento check in patches they have not written).
-If no one is around to check in your patch after it has received the requisite approvals, add <tt>checkin-needed</tt> to the bug's Keyword field and one of the committers should notice and land your patch within a day or so.  If they do not, make a comment in the bug or on [irc://irc.mozilla.org#camino IRC].
+==Checking In==
-Also note that the <tt>mozilla/camino</tt> directory hierarchy is open for approved Camino check-ins regardless of the state of various trees and branches, with a few exceptions, such as tagging of major branches, red Camino tinderboxen, missing Camino perf or nightly tinderboxen, etc.
+Once code written by contributors who do not have commit access has received requisite reviews (and perhaps approvals, too), it falls to Camino committers to check the new code into the repository.  Sometimes one of the committers is following the bug and will land the patch as soon as the committer can watch the tree.  Other times the patch author may need to add <tt>checkin-needed</tt> to the bug's Keyword field in order to notify the committers that the patch is ready to land.
 '''N.B''' When the Camino tree is closed while the Mozilla tree is closed, there is typically a note on the [http://tinderbox.mozilla.org/showbuilds.cgi?tree=Camino Camino tinderbox] explaining the closure, and the closure is often mentioned in the “topic” in the [irc://irc.mozilla.org#camino #camino] channel on IRC.  '''However''', when the opposite is true—Mozilla is closed and Camino is open—there is typically no indication of the fact.  If you are unsure of the state of the Camino tree, ask on in the [irc://irc.mozilla.org#camino #camino] channel on IRC.
-===Checkin tips for new (and old) committers===
+==Checkin tips for new (and old) committers==
-====Mercurial====
+===Mercurial===
 Remember that Hg is a distributed VCS, so that most operations are local.  In particular, where “committing” to the official repository was a single operation with CVS (<code>cvs commit</code>), it is a pair of operations with Hg (the local-only <code>hg commit</code> and the local-to-remote <code>hg push</code>).
-=====Configuration changes to allow you to check code into the official repository=====
+====Configuration changes to allow you to check code into the official repository====
 In order to be able to push changes to a remote hg repository, you will need to make a pair of configuration changes:
@@ Line 26: / Line 32: @@
 default-push = ssh://hg.mozilla.org/camino/</nowiki></pre>
-=====Add a hook to ensure complete checkin messages=====
+====Add a hook to ensure complete checkin messages====
 For some reason Camino committers appear far more likely to drop a required part of the commit message with Hg commits than we did with CVS.  An easy way to prevent bad commit messages is to use a “hook” that checks your commit message for required data and aborts the commit with a helpful error when the data is missing.
@@ Line 38: / Line 44: @@
 For more about Hg hooks, see [http://hgbook.red-bean.com/read/handling-repository-events-with-hooks.html Chapter 10. Handling repository events with hooks] in the Hg book.
-=====Checking in patches from others=====
+====Checking in patches from others====
 Mercurial has a way of recording the actual patch author even when someone else is committing and pushing the patch.  When you’re committing a patch written by someone else, use the following commit command syntax:<pre><nowiki>hg commit -u "Patch Author <camino.dev@example.org>" -m "Complete commit message" file1 file2</nowiki></pre>
@@ Line 47: / Line 53: @@
 Then commit all of Patch Author’s patches using <code>$ hg patchGuy -m "Complete commit message" file1 file2</code>.
-=====Figuring out what patches (commits) you are pushing to the remote repository=====
+====Figuring out what patches (commits) you are pushing to the remote repository====
-Once you’ve committed some patches and are ready to push them to the official repository, you can sanity-check what you’re about to send by using the <code>hg outgoing</code> command.  If the list of patches (commits) looks correct, <code>hg push</code> will send them to the remote repository.  Be sure to paste the changeset URLs in the bug when resolving it!
+Be sure to paste the changeset URLs in the bug when resolving it!
-====CVS====
+===CVS===
-=====Checking in nibs=====
+====Checking in nibs====
 Sometimes a person who doesn't have CVS access will post a new or updated nib on a bug that needs to be checked in. The problem with this is that since a nib is technically a directory, there is a CVS folder inside the nib. If you attempt to check in a nib that has been changed by someone who has the <tt>CVSROOT</tt> set as "<tt>:pserver:anonymous@cvs-mirror.mozilla.org:/cvsrooot</tt>" (''e.g.'', everyone without cvs write access), you will receive an authorization error from cvs. The problem is that the <tt>CVS/Root</tt> file is set as the anonymous <tt>CVSROOT</tt>, not your "<tt>user%email.com@cvs.mozilla.org:/cvsroot</tt>" <tt>CVSROOT</tt>.
@@ Line 60: / Line 68: @@
 Alternatively, instead of dropping that person’s nib in place, use <code> cp /path/to/other/nib/*.nib /path/to/your/tree/nib; touch /path/to/your/nib</code> to copy their nib files into your tree.
-=====Trunk/branch mismatches=====
+====Trunk/branch mismatches====
 Sometimes (due mostly to Gecko changes on the trunk) the trunk and branch versions of a patch will diverge and you can't use cross-commit to land both places.  '''If you're confident the branch patch has been well-tested''' and don't have a branch tree, you can pull just the files you need to commit (rather than pull an entire tree).
@@ Line 68: / Line 76: @@
 # Apply the patch and commit the files "as normal"
-=====Backing out a patch=====
+====Backing out a patch====
 Sometimes you accidentally commit something that shouldn't have landed yet, or sometimes (hopefully rarely) you commit something that breaks the tree and needs to be backed out.  To back out a patch, follow these steps:
@@ Line 78: / Line 86: @@
 # <code>cvs commit</code> "as normal"; this will commit a new copy of the file(s) with the incorrect change backed out
-=====Adding new files=====
+====Adding new files====
 * <code>cvs add</code>
 * <code>cvs add -kb</code> for any binary files, including images, UTF-16-encoded files (e.g., <code>.strings</code> files from external projects), and <code>keyedobjects.nib</code> files inside .nibs.
-=====Adding new nibs=====
+====Adding new nibs====
 * <code>cvs add</code> the wrapper directory
 * <code>cvs add -kb</code> on '''keyedobjects.nib'''