mention limitations and/or alternatives to hg graft

[cjerdonek]

BPO	16930
Nosy	@brettcannon, @terryjreedy, @ncoghlan, @pitrou, @ned-deily, @ezio-melotti, @merwok, @cjerdonek, @willingc
Dependencies	bpo-14468: Update cloning guidelines in devguide

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/willingc'
closed_at = <Date 2016-07-22.19:52:05.375>
created_at = <Date 2013-01-11.08:38:39.194>
labels = ['type-feature', 'docs']
title = 'mention limitations and/or alternatives to hg graft'
updated_at = <Date 2016-07-22.19:52:05.373>
user = 'https://github.com/cjerdonek'

bugs.python.org fields:

activity = <Date 2016-07-22.19:52:05.373>
actor = 'brett.cannon'
assignee = 'willingc'
closed = True
closed_date = <Date 2016-07-22.19:52:05.375>
closer = 'brett.cannon'
components = ['Devguide']
creation = <Date 2013-01-11.08:38:39.194>
creator = 'chris.jerdonek'
dependencies = ['14468']
files = []
hgrepos = []
issue_num = 16930
keywords = []
message_count = 18.0
messages = ['179650', '179720', '179757', '179759', '183024', '183076', '183126', '183134', '183136', '183139', '183140', '183142', '183174', '183205', '183209', '183214', '183228', '271020']
nosy_count = 9.0
nosy_names = ['brett.cannon', 'terry.reedy', 'ncoghlan', 'pitrou', 'ned.deily', 'ezio.melotti', 'eric.araujo', 'chris.jerdonek', 'willingc']
pr_nums = []
priority = 'normal'
resolution = 'out of date'
stage = 'needs patch'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue16930'
versions = []

[cjerdonek]

In various places, the devguide recommends hg graft, but it appears it might not be possible to use on some systems or in certain situations. For example, when I tried grafting a trivial change from 2.7 to 3.2 on Mac OS X, I got the following fatal error:

$ hg graft 2.7
grafting revision 81391
abort: case-folding collision between Lib/ConfigParser.py and Lib/configparser.py

Here is some related information: http://mercurial.selenic.com/wiki/FixingCaseCollisions

At the least, we might want to add a note saying that hg graft may not work on certain systems (and name those systems).

[ned-deily]

Keep in mind that the issue isn't which operating system is used; it's whether the file system(s) on which the hg repo resides is (are) case-insensitive or case-sensitive. Most modern operating systems (including OS X) support both file system types and on Unix-y systems, at least, you can even encounter a mixture of case-sensitive and -insensitive file systems within a particular absolute path, i.e. if the path includes mount points to different file systems.

[terryjreedy]

Windows preserves case when writing a filename but ignores it when searching and opening filenames. IE, if I have tem.py and try to save TEM.py (from IDLE), it says 'tem.py exists, overwrite?'. So will or will not that be a problem for graft with 2.7/3.x module name case changes?

[cjerdonek]

To clarify my original comment, I got an error about ConfigParser.py/configparser.py even when that file was not part of the change.

[ezio-melotti]

http://docs.python.org/devguide/committing.html#porting-changesets-between-the-two-major-python-versions-2-x-and-3-x now mentions both "hg graft" and "hg export|import". Do you think this is enough or should we add a link to http://mercurial.selenic.com/wiki/FixingCaseCollisions too?

This could be added just after "On older version of Mercurial where hg graft is not available [or while grafting on case-insensitive filesystems] ...".

[pitrou]

To clarify my original comment, I got an error about
ConfigParser.py/configparser.py even when that file was not part of the
change.

Would you mind reporting a Mercurial bug then? (http://bz.selenic.com/)

As for mentioning it in the devguide, I don't think we want to mention every other utility's quirk.

[cjerdonek]

Why must we mention graft at all? I've never had a need for it. It seems simpler and just as effective to run hg import on the original patch.

I think it's preferable that the steps we recommend to work on all systems. Then we won't have to worry about documenting quirks, or responding to e-mails or tracker issues saying our recommended steps don't work.

[pitrou]

Why must we mention graft at all? I've never had a need for it. It
seems simpler and just as effective to run hg import on the
original patch.

hg graft actually works in some cases where hg import will fail,
because grafting uses the merge logic (so, for example, it is able to
recognize that some files were renamed between branches).

[ezio-melotti]

Also I often made changes on the patch I imported and applied on 2.7 (e.g. update Misc/NEWS). Reimporting the patch means that I would have to do it again, and both "hg import --no-c url_of_the patch" and "hg export 2.7 | hg import -" are more complicated than "hg graft 2.7".

[cjerdonek]

If you start with a patch against 3.x, which is the normal case, why go to the trouble of grafting from the patch modified for 2.7? It seems you're just creating more trouble for yourself (introducing more conflicts you have to resolve, etc) when you already have a patch that is known to apply cleanly to 3.x.

[ezio-melotti]

Because if the graft succeeds "hg graft 2.7" does everything (including porting extra modifications that I made before committing on 2.7 and the commit on 3.2), if there are conflicts I just spend a few seconds more in kdiff3 to fix them.
Reapplying the patch means that I have to do import + commit at least, and possibly reapply manually changes that I've already done on 2.7.
(I'm assuming that the patch is applied on 2.7 and grafted on 3.2, but the opposite should also be valid.)

[cjerdonek]

Reapplying the patch means that I have to do import + commit at least, and possibly reapply manually changes that I've already done on 2.7.

Since 2.7 is more different from 3.2 than is 3.4, it seems more likely that grafting from 2.7 to 3.x will result in having to undo 2.7-specific changes and/or add back 3.x-specific changes, and even more so when skipping 3.2.

But this is all secondary to my point that we shouldn't include in our basic instructions things that we know won't work for some people when there is a straightforward alternative (and one that uses no new concepts). At the very least, we should provide a working alternative alongside.

[terryjreedy]

As a member of the devguide target audience, I think for this the devguide should give alternatives with brief pluses and minuses. After importing and applying a patch to the earliest applicable 2.x or 3.x, move it to the other series with graft (new, possible better merge,possible problem with case or series specific changes); re-import (possible loss of local edits); or even export/import (keep local changes, no case problems). Expanded, the previous sentence should only be 10 or at most 15 lines. Then each person can pick the method that works best for them, which might not always be the same method for each patch. In a few years, this topic will be obsolete except for security issues.