RFC: HOWTO: Cherrypicking patches from "xemacs"

[Stephen J. Turnbull]

Recently the issue of how to cherrypick patches from "xemacs" came up
(see the thread "Re: cython-mode.el").  I propose to add the following
to the "hg-access.html" page to address the need.  Comments welcome.

========================================================================
Cherrypicking from the review queue
-----------------------------------

Users of the "xemacs-beta" branch may occasionally want to cherrypick
a specific patch from another branch because it hasn't landed in
"xemacs-beta" yet.  This could be due to ordinary lags for review, or
perhaps it has been queried and the discussion is dragging out, or
perhaps it was vetoed.  Anyway, you want it and you want it now.

First you need to identify the patch.  You will need to get a checkout
of the "xemacs" branch.  All patches intended for the mainline will go
there.  It's probably a good idea to check it out as a sibling of your
"xemacs-beta" checkout.  Once you have a checkout of the "xemacs"
branch, use the "hg -v log" command *in that workspace* to view the
ChangeLogs and identify the patch of interest.  (Use "hg help log" to
get information about options to limit or filter output.)  It will
look something like this:

------------------------------------------------------------------------
changeset:   4433:1bf48c59700e
tag:         tip
user:        Stephen J. Turnbull <stephen at xemacs.org>
date:        Wed Mar 05 01:12:53 2008 -0800
files:       src/ChangeLog src/glyphs-gtk.c
description:
Fix old use of rvalue on lhs to placate gcc >4.0.
<d9ae65bd0803040244s13437988ka08bae763d28801f at mail.gmail.com>
------------------------------------------------------------------------

In the following, REV stands for the hash code following the colon in
the "changeset" field (in the example, "1bf48c59700e").

We assume that the "xemacs" and "xemacs-beta" workspaces are siblings,
and furthermore that those are the names you gave them.  Your
workspace should be "hg status" clean (no pending modifications or
file additions or removal reported).  On Unix, a simple method is the
following.  From "xemacs-beta", do

$ ( cd ../xemacs; hg export REV ) | patch -p1

and you're done.  patch will probably complain that it was unable to
patch the ChangeLogs, but you don't really care about them.  Just
throw away the .rej and .orig files.  If patch complains about any
other files, revert to your "clean" state with "hg update -C", and use
the "transplant" method described below -- a non-trivial merge is
needed.  (It probably doesn't do much by itself, but in this case you
really do want the additional history it generates in Mercurial.)

The advantage to the "patch" method just described is that when the
patch lands on the "xemacs-beta" branch, there is no Mercurial history
of what you've done.  Regardless of whether there is history or not,
when you next "hg pull", Mercurial *may report a conflict* because the
files are locally changed in the same place.  If there is no history,
you just do "hg update -C" and Mercurial will overwrite the cherry-
picked change with the same change from the "xemacs-beta" repo,
which is exactly what you want, and you have a clean history.

This method works best if you do not have local modifications "close"
to the patch you are cherrypicking.

An alternative method is to use the Mercurial "transplant" extension.
First, activate the "transplant" extension by putting this into your
~/.hgrc:

[extensions]
hgext.transplant=

Now change to the "xemacs-beta" workspace and do:

$ hg branch cherries        # label your local branch
                            # omit if you already have a cherries branch
$ hg branch reviewq         # a branch to hold the review queue patches
# $ hg update -C reviewq    # instead of hg branch once the reviewq
                            # branch has been created
$ hg pull ../xemacs         # get the patches
                            # merely pulling does not change the default source
                            # maybe there's some way?
$ hg update -C cherries     # back to branch
$ hg transplant --log REV   # remember REV from the log above?

for every revision you want to cherry-pick.  (The --log option adds a
cross-reference to REV in the log message for the commit that
transplant creates.)

Another way to use the transplant extension avoids having a local copy
of the review queue repo "xemacs".  In the "xemacs-beta" workspace, do:

$ hg branch cherries
# $ hg update -C cherries   # instead of hg branch once the cherries
                            # branch has been created
$ hg transplant --log --source http://hg.debian.org/hg/xemacs/xemacs REV

In this case you can get the REV information by visiting
http://hg.debian.org/hg/xemacs/xemacs in an ordinary web browser.

The transplant extension does update the Mercurial history of the
branch.  According to the transplant documentation [at selenic.com,
url to be provided], this can be annoying if you repeatedly
cherrypick, but not all of the patches you want make it into
"xemacs-beta" in a timely fashion, as Mercurial will repeatedly
complain about conflicts.  So, use of the transplant extension may be
somewhat more complex than just using patch.  On the other hand, if
you have other local modifications, then even if you mess up, you'll
have all history needed to reconstruct your favorite configuration of
XEmacs in the workspace.
========================================================================