Re: [PATCH] doc: clarify triangular workflow

[Junio C Hamano <gitster@pobox.com>]

Timothee Albertin <timothee.albertin@gmail.com> writes:

> diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
> index 02569d0..21f6dc8 100644
> --- a/Documentation/gitworkflows.txt
> +++ b/Documentation/gitworkflows.txt
> @@ -407,8 +407,8 @@ follows.
>  `git pull <url> <branch>`
>  =====================================
>  
> -Occasionally, the maintainer may get merge conflicts when he tries to
> -pull changes from downstream.  In this case, he can ask downstream to
> +Occasionally, the maintainers may get merge conflicts when they try to
> +pull changes from downstream.  In this case, they can ask downstream to
>  do the merge and resolve the conflicts themselves (perhaps they will
>  know better how to resolve them).  It is one of the rare cases where
>  downstream 'should' merge from upstream.

The document starts with

    This document attempts to write down and motivate some of the
    workflow elements used for `git.git` itself.  Many ideas apply
    in general, though the full workflow is rarely required for
    smaller projects with fewer people involved.

and makes me wonder (note: I am not involved in writing any of the
existing text in this document) how much material foreign to the
actual workflow used for `git.git` should go in here.  Having
multiple maintainers at the same time is not a workflow element that
we have ever used, for example, so I am not sure about the change in
the above paragraph.

> +TRIANGULAR WORKFLOW
> +-------------------

I really hate to say this.  Before I made comment on the last round
that tried to add this section, I didn't read the original closely
enough.  

The thing is, it does already cover the triangular workflow in the
"Merge workflow" section (you may need to already know what you are
reading to realize that fact, though).  The text in the existing
"Merge workflow" section where requestor pushes to somewhere for the
maintainer to pull from may not be immediately obvious, and it may
be worthwhile to improve it, but I find it highly misleading to add
an entirely new section as if it is describing yet another separate
workflow that is different from anything that is already described
in the document.  It is not.

A replacement of the entire section (but I'd recommend keeping the
"Merge workflow" title, which contrasts well with the other "Patch
workflow" that follows), or a separate document that is referred to
with "see that other one for a lengthier description" by the
existing "Merge workflow" section, or somewhere in between, might be
a more acceptable organization, though.