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).

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.

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?

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

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] ...".

> 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.

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.

> 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).

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".

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.

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.)

> 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.

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.

> I think for this the devguide should give alternatives with brief 
> pluses and minuses.

Something like http://docs.python.org/devguide/committing.html#porting-changesets-between-the-two-major-python-versions-2-x-and-3-x ? :)

16.6 is just what I was suggesting. I had not read that far in the revised version. But I am glad I did to find out about auto-commit. There have been issues where I would not want that. (I will check to see if commit is really 'alwats' or if there is an option to not commit, as with import and merge.)

I think that the worry about people not having graft available is misplaced. New people should be downloading the latest version of hg. Experienced users will know about the alternatives before they read 'hg graft'. Also, it seems easy enough to update hg (I plan to do so again soon), I think the main dev doc should assume that people have a recent enough version and describe what is most favored by experienced devs. (On quasi-religious issues like editors and dev methods, consensus is unreachable.)

As for case conflicts, how about adding a phrase to produce
"On older versions of Mercurial where hg graft is not available, or when graft has problems with case conflicts, you can use:"
(note /version/versions/, so a patch is needed anyway ;-).

Other than that, I think this issue should be closed unless and until there is a actual problem encountered, say by someone like me or with even less experience. Let's move on to another dev guide issue.

> (I will check to see if commit is really 'alwats' or if there is an 
> option to not commit, as with import and merge.)

There isn't AFAIK, but two "tricks" I use are:
 1) "hg diff -c tip" to check the diff of what I just grafted;
 2) "hg rollback" to rollback the commit in case something is wrong;

I'll see if/where they should be added.

> New people should be downloading the latest version of hg.

That works on Windows, but on Unix most people just use the version shipped with their distribution.  "hg graft" is not so bleeding-edge anymore though -- I had it for a while using the default "hg".

> As for case conflicts, how about adding a phrase to produce
> "On older versions of Mercurial where hg graft is not available, or 
> when graft has problems with case conflicts, you can use:"

This (or the wording I suggested in msg183024 if it's accurate) would be ok with me.  Terry, have you tried using "hg graft" yet?  Are there conflicts on Windows?  I'm not sure how common these conflicts are -- I've never seen them myself.

> (note /version/versions/, so a patch is needed anyway ;-).

Yep, I spotted that but was waiting for this issue :)

The first and/or main place that recommends "hg graft" should link to the section with more detail for cases where users experience problems with graft.  I also agree that the section should mention the case-folding error.  I'm using a pretty new version of hg (version 2.2.1+20120504) and get the error.  (Mercurial's web site is down right now so I can't tell if it's the newest released version still.)

With the migration to git pending, this won't be worth the effort.