Mercurial, consistent merges, and submission convenience

[Thomas Arendsen Hein]

* John Goerzen <jgoerzen at complete.org> [20070225 17:59]:
> On 2007-02-25, Thomas Arendsen Hein <thomas at intevation.de> wrote:
> > - The patch header contains the parent node, but you have to update
> >   to this node manually.
> 
> What happens if I don't?  Perhaps because the submitter's repo isn't
> public anywhere?  Will the submitter have trouble pulling from me in the
> future?

Yes, this could happen, even more if the one who integrates the
patch makes some last-minute modifications.

The recommended workflow is that you have one local clone per
feature you're working on. If the feature was accepted upstream, you
can simply throw it away.

> > - "hg export --git" preserves copy/move/executable and even binariy
> >   content by using the extended git patch format.
> 
> Does it preserve the parent node ID as well?

The --git flag only affects the patch, not the #HG headers. So you
still have to manually update to the stored parent revision (if
available).

> Could the email extension be set to use this mode by default?  It seems
> much more useful.

You could either add

[diff]
git = 1

to your ~/.hgrc (or repository's .hg/hgrc) to enable git patch
format for all commands printing diffs, or

[defaults]
email = --git

to always pass the --git flag when using the email subcommand.

I hope that there will be a way to specify using git format only if
necessary in the future, see
http://www.selenic.com/mercurial/bts/issue491

> >>    Why, then, does hg email use hg export instead of hg bundle?
> >
> > Because you can't expect the whole world to use Mercurial. Plain
> > (non-git) patches are accepted by almost any project.
> 
> Ah, I see.  A different paradigm.  Mercurial assumes that upstream isn't
> using Mercurial, and Darcs assumes it is.

'hg export' and 'hg email' don't assume that it is but provide extra
headers in case it is.

> Actually, darcs has no direct
> equivolent of hg email (though "darcs diff" is pretty close to hg
> export).

'hg email' is just an extensions to combine 'hg export' with
automatic sending of mails.

> >> 2) An equivolent to "darcs send".
> >> 
> >>    Finally, if the remote repo has specified an email address for the
> >>    maintainer, darcs can automatically look up the email address to send
> >>    the bundle to, and sent it away.
> >
> > Mercurial doesn't have this "maintainer email address" field.
> 
> But perhaps it could be added to a well-known location, as with hg tag
> --local?

Look at hgext/patchbomb.py for what you can add to .hg/hgrc:

[email]
from = My Name <my at email>
to = recipient1, recipient2, ...
cc = cc1, cc2, ...
bcc = bcc1, bcc2, ...

Of course you have to set 'to' manually.

> The key is to make the file not come across with cloning.  That is, it's
> not part of the versioned data of the repo, but part of the metadata
> about that repo.  I'd think that something along the lines of "hg tag
> --local", where it stores the local tags in .hg/localtags, would be in
> order.  If you have, say, .hg/email, looking something like:
> 
> address=foo at example.com
> bundles=true
> 
> This should be trivial for the Mercurial client to download from a
> public repo at the time of an "hg send".  Mercurial will have to go out
> over the network at "hg send" time anyway to determine what changesets
> need to be sent.

It is part of Mercurial's core design that only versioned data is
transfered. Everything else is local to a repository.

And as I wrote, local clones of local clones cloned from upstream is
quite usual for Mercurial. I even explicitly recommend this.

> But if this is an extension, it is just another barrier to Joe Random
> Hacker being able to quickly pick up my tree, hack, keep up-to-date,
> etc.

'hg email' already is an extension, additionally any command that
tries to send email has to be configured by the user to either
confirm that /usr/lib/sendmail is ok or which SMTP host has to be
used.

The "trivial" way to tell beginners is using "hg outgoing" to see
which changesets should be sent and "hg export" to generate ASCII
representations of them. (Or just do "hg export tip" if you only did
one change)

> I want a programmer that has no prior experience with my VCS of choice
> to be able to trivially install the VCS, check out my tree, hack, and
> send me patches.  The easier I make it on the public, the more patches I
> receive.

hg clone http://hg.example.com/repo
cd repo
# hack code
hg commit
hg export -o file tip
# Mail this file.

This is as easy as sending the output of "darcs diff" and for a
one-shot patch probably easier than configuring "hg email" or "darcs
send" for which mail method to use.

(See the list archive for why we don't default on using sendmail by
default)

> I link to my "5-Minute Guide to Contributing With Darcs" from my project
> websites.  It's at http://software.complete.org/site/wiki/DarcsGuide

The Mercurial equivalent is:
http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart

> If I have to tell people how to download and install an extension
> (across various different OSs at that), edit their .hgrc to enable it,
> and *then* finally they can submit...  well, that's not as easy for
> them.

Darcs assumes that sendmail works out of the box and email is the
preferred way of submitting patches. We even had cases of people
joining the IRC channel after using Mercurial for a very short time
and sending patches via http://lisp.paste.org :-)

> > qpop is part if mq, which is an extension which violates the
> > append-only paradigm of Mercurial.
> 
> I think it would be very good to document this prominently on the wiki.
> As I don't really even use hg yet, perhaps someone that actually knows
> what's going on could do that.  But I'm willing to give it a shot.

http://www.selenic.com/mercurial/wiki/index.cgi/MqExtension might be
a good place. See http://www.selenic.com/mercurial/bts/issue46 for
terms to reuse.

> That also should be prominently displayed on the wiki.  With that
> restriction, what does mq actually offer that quilt doesn't?

mq is just quilt for hg ... it is even compatible with quilt, so you
can work together with people using quilt.

But together with Mercurial it is much faster and easier to use.

> > The second alternative is of course to publish your patch queue
> > (.hg/patches) directly.
> 
> Yes, I will have to think this one through.  I haven't fully grasped how
> that would work yet.

You know that you can make this an hg repo with 'hg qinit -c' and
use 'hg qcommit' to commit your queue?

Again no magic: .hg/patches will be just a plain hg repository.

But beware: 3-way-merge of diffs is nothing you really want :)

> > With mq you have the qrefresh command to change patches until you
> > and/or upstream like them. With transplant you can cherrypick or
> > rebase existing patches but not modify patches.
> 
> Hrm, maybe I'm being dense, but what is the difference between rebasing
> and modifying?  I would have thought that rebasing could, in fact,
> modify (to fix merge conflicts, etc.)

Rebasing is special as you usually don't modify what a changeset is
supposed to do. With mq you can even fold patches together (qfold)
or edit their description (qrefresh -e).

> Does TransplantExtension use have the same potential drawbacks on
> collaboration with others as mq does?  Again, I'm guessing yes;
> git-rebase certainly has that drawback.

Different things: With TransplantExtension you usually don't throw
away the old patch queue when you make changes as you're doing with
mq. We use it this way for crew vs. crew-stable (simplyfied):

cd crew-stable
hg transplant -s ../crew
(choose the changesets to be transplanted from crew)
cd ../crew
hg pull ../crew-stable
hg merge
hg commit -m 'merge with crew-stable'

During the merge you throw away everything that was transplanted
from crew to crew-stable ... the easiest way for this is to merge
before transplanting and to use
  HGMERGE=true hg merge
  hg revert --all tip
  hg commit
to ignore everything coming in from the other branch.

> > You could backout your cherrypicked 10 and then pull+merge as usual.
> >
> > Or use the TransplantExtension which is designed to do cherry
> > picking. It adds a mark to transplanted changesets (visible with
> > 'hg log --debug' in the transplant_source extra field).
> 
> Interesting.  I re-read the TransplantExtension page on the wiki, as
> well as its help information.  I am confused about how its merging
> relates to regular hg merge; transplant has a --merge, hg has a merge,
> and it's not clear to me exactly the difference between various hg
> transplant --all commands and a normal hg fetch.

I never used transplant --merge and --all and I don't know what
they're supposed to do. Never needed them and therefore never looked
at them :)

Thomas

-- 
thomas at intevation.de - http://intevation.de/~thomas/ - OpenPGP key: 0x5816791A
Intevation GmbH, Osnabrück - Registereintrag: Amtsgericht Osnabrück, HR B 18998
Geschäftsführer: Frank Koormann, Bernhard Reiter, Dr. Jan-Oliver Wagner