Patchwork [2,of,2] commit: try to clarify when to use --new-branch

# HG changeset patch
# User timeless <timeless@mozdev.org>
# Date 1448909767 0
#      Mon Nov 30 18:56:07 2015 +0000
# Node ID c82932a5af52058a1cbce3e12cb07dccf1abc9ca
# Parent  a92289f0420c849b40f86904d935c7598a49cfa4
commit: try to clarify when to use --new-branch

On 11/30/2015 11:09 AM, timeless wrote:
> # HG changeset patch
> # User timeless <timeless@mozdev.org>
> # Date 1448909767 0
> #      Mon Nov 30 18:56:07 2015 +0000
> # Node ID c82932a5af52058a1cbce3e12cb07dccf1abc9ca
> # Parent  a92289f0420c849b40f86904d935c7598a49cfa4
> commit: try to clarify when to use --new-branch
>
> diff --git a/mercurial/commands.py b/mercurial/commands.py
> --- a/mercurial/commands.py
> +++ b/mercurial/commands.py
> @@ -1488,6 +1488,13 @@
>       head closed. When all heads of a branch are closed, the branch
>       will be considered closed and no longer listed.
>
> +    .. note::
> +
> +      If you are thinking about closing a branch, but you never shared
> +      it, you should consider making it secret (see :hg:`help phase`) or
> +      obsolete (see :hg:`help obsolete`), or stripping it
> +      (see :hg:`help strip`) instead of merely closing it.
> +

Evolution is still experimental, we cannot make reference to "obsolete" 
in the wild like that.

Improving help in that area seems a good idea. The current proposed 
paragraph seems a bit too enigmatic to me. I would insert something to 
emphasize the fact that  "If you never shared it, you would be better of 
not sharing it at all". Then pointing at option to not share it.

>> +      If you are thinking about closing a branch, but you never shared
>> +      it, you should consider making it secret (see :hg:`help phase`) or
>> +      obsolete (see :hg:`help obsolete`), or stripping it
>> +      (see :hg:`help strip`) instead of merely closing it.
>> +

Pierre-Yves David wrote:

> Evolution is still experimental, we cannot make reference to "obsolete" in
> the wild like that.

I wasn't technically referencing your obsolete ;-)

$ hg help obsolete
abort: no such help topic: obsolete
(try "hg help --keyword obsolete")
$ hg help -k obsolete
Topics:
 revsets Specifying Revision Sets

Commands:
 debugobsolete       create arbitrary obsolete marker

^ now, it's not a great idea to send someone to the dragons of debug
land, but, it would technically work :)

> Improving help in that area seems a good idea. The current proposed
> paragraph seems a bit too enigmatic to me. I would insert something to
> emphasize the fact that  "If you never shared it, you would be better of not
> sharing it at all". Then pointing at option to not share it.

I'm not really sure how to do this well. To some extent, we need a
hook for things to join in (prune, strip, histedit, ...)

Offhand, https://www.mercurial-scm.org/wiki/MutableHG is about the
only thing I can find in wiki space (I'm not a good wiki user). And I
can't find any obvious files in mercurial/help/ space for this purpose
-- Plus, I'd rather point to a web page that we could update as time
goes by.

Here's an alternative:
If you are thinking about closing a branch, but you never shared
it or at least never published it (see :hg:`help phases`), you should
consider suppressing or removing it from your repository instead of
merely closing it. See:
{url}