The devguide describes a mq-based approach (*) for generating patches, but it seems nobody (almost) uses it. We should therefore replace that description with a more traditional one ("hg diff").

(*) http://docs.python.org/devguide/patch.html#tool-usage

Yes please.  We already have text if we look at the history before 73e11f64a704; we only need to agree on recommending “uncommitted changes in a clone” (which is okay to share patches but not for not ideal for more than one person working on something), named branches (what was in the previous text, because it makes it easy to run hg diff -r default and such commands) or bookmarks (lightweight named branches that some people recommend; I’m not sure how they’re better, given that in the end we generate a patch and make a new commit).

I, for one, use both uncommitted-changes and named branches; the former is easiest, but the latter safer: if I screw up a merge in a clone where I use a named branch, I can revert and retry the merge, but if I screw up merging pulled changes with my uncommitted edits, I risk losing them.

> I, for one, use both uncommitted-changes and named branches; the
> former is easiest, but the latter safer: if I screw up a merge in a
> clone where I use a named branch, I can revert and retry the merge,
> but if I screw up merging pulled changes with my uncommitted edits, I
> risk losing them.

I think uncommitted changes is fine for a simple introduction.
hg experts can use whatever they want without needing our help.

No one uses it?  I'm surprised.  I do and it seems to me by far the easiest and safest way to maintain patches in progress when there is constant churn.

+1
Most of the time "hg diff > issue12345.diff" is all that it's needed to produce a patch, and whenever I point someone to the devguide they usually get confused because they think they have to use mq.

FWIW I mostly use uncommitted changes, possibly on more clones, and since I usually upload the patch to the tracker I don't risk losing it in case I do something wrong.

> No one uses it?  I'm surprised.  I do and it seems to me by far the
> easiest and safest way to maintain patches in progress when there is
> constant churn.

Ah, good to know :) My wording was a bit too strong then.
However, I rarely see mq-produced patches when processing patches from contributors.

One person that I helped at the PyCon sprints was using it, because the devguide said to.  But I think she was more confused by it than she would have been by 'hg diff', at least to start out.  Or maybe not...but I wasn't able to help her with the mq commands, because I don't use mq myself.

I should try it sometime, I suppose.

> One person that I helped at the PyCon sprints was using it, because
> the devguide said to.  But I think she was more confused by it than
> she would have been by 'hg diff', at least to start out.  Or maybe
> not...but I wasn't able to help her with the mq commands, because I
> don't use mq myself.

mq is "advanced" compared to other workflows. It's a rather powerful and
sophisticated tool. I think people familiar with hg will have no problem
using mq even if we don't mention it. hg beginners, on the other hand,
will be more comfortable with something simpler.

Here is a patch.

LGTM.

+   hg import --no-commit < mywork.patch

Is the '<' correct here?

I would also mention hg diff right away, and explain about adding/removing files after that.
The rest looks good.

On Tue, Apr 03, 2012 at 08:37:35AM +0000, Ezio Melotti wrote:
> 
> Ezio Melotti <ezio.melotti@gmail.com> added the comment:
> 
> +   hg import --no-commit < mywork.patch
> 
> Is the '<' correct here?

No!. It should just be hg import --no-commit mywork.patch.

I asked around at PyCon to see if there were people using 'mq' just to
know about their workflow and it's advantages. I think only Ned
mentioned that he was using it, but everyone "theoretically" agreed
that it could be useful extension while working on a patch. When it is
not being used by many, I think it is just adding to the confusion by
it's mention in the devguide. +1 to remove it.

New changeset e1d4b6dc9702 by Antoine Pitrou in branch 'default':
Issue #14466: remove mq-based workflow
http://hg.python.org/devguide/rev/e1d4b6dc9702

Done, thank you.

Just for the record:

Thanks to the old mq workflow in the devguide I've learned about them and I'm now using it all the time to send and manage the patches.

The only thing is that one should first use the “qqueue” functionality (see “hg help qqueue”) and then in a "qqueue" all the old devguide stuff (hg qdiff, hg qpush, hg qpop, and so on...).

I agree that for a beginner the actual workflow maybe easier.