Re: [PATCH] doc: clarify triangular workflow

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 3, 2017, 06:36 UTC
Message-ID: <xmqqwp24iah2.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <1512034932-14499-1-git-send-email-timothee.albertin@etu.univ-lyon1.fr>

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

Show 15 quoted lines

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