Re: [PATCH v2] doc: add triangular workflow

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

Matthieu Moy <matthieu.moy@univ-lyon1.fr> writes:

> I don't think you should talk about "Git contributors", which can be
> read as "contributors to the git.git codebase". "Git users" would make
> more sense, or perhaps you meant "contributors to Git projects". But
> actually, I don't think this kind of documentation should focus only
> on new users. I think many reasonably advanced Git users do not know
> about remote.pushdefault for example.

Thanks for a careful review.

>> diff --git a/Documentation/Makefile b/Documentation/Makefile
>> index 2ab6556..c3e98c7 100644
>> --- a/Documentation/Makefile
>> +++ b/Documentation/Makefile
>> @@ -10,6 +10,7 @@ OBSOLETE_HTML =
>>  MAN1_TXT += $(filter-out \
>>  		$(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
>>  		$(wildcard git-*.txt))
>> +MAN1_TXT += git-triangular-workflow.txt
>
> git-*.txt is reserved for actual Git commands. Other tutorials use
> git*.txt (e.g. we have gitworkflows.txt and not git-workflows.txt).

Yeah, it probably is worth mentioning that MAN1 is for commands.
Unless we have "git triangular-workflow" subcommand, this shouldn't
be listed on MAN1_TXT list.  Perhaps in MAN7 next to tutorial and
workflow would be a better place.

>> +This workflow is commonly used on different platforms like BitBucket,
>> +GitHub or GitLab which provide a dedicated mechanism for requesting merges.
>
> As a user, I find it terribly frustrating when reading documentation
> telling me that "there's a dedicated mechanism" for something without
> telling me actually how to do it.

Also I think the description is backwards from end-user's point of
view.  It's not that it is common to use the workflow on these
hosting sites.  It's more like people use the workflow and adopt use
of these hosting sites as one building block of the workflow.

>> +In a triangular workflow the rest of the community or the company
>> +can review the code before it's in production. Everyone can read on
>> +**PUBLISH** so everyone can review code before the maintainer merge
>> +it to **UPSTREAM**.  In a free software, anyone can
>> +propose code.  Reviewers accept the code when everyone agree
>> +with it.

The above hints that the workflow covers wide range of development
circles from open source to proprietary, but the description in this
paragraph does not seem to show how the workflow achieves that goal
very well.  Not all environment allow "everyone" to read "publish"
(it is common to see siloed source repositories in commercial
settings), and not all projects require unanimous agreement for
inclusion.  Also, "anyone can propose code" may be true for any
project, not limited to "free" ones, as long as the code to base
your changes on is available, but if the project would not take
external contributions, being able to "propose" alone does not mean
that much to the proposer.

>> +If **PUBLISH** doesn't exist, a contributor can publish his own repository.
>> +**PUBLISH** contains modifications before integration.

I am not sure what this really means.  Isn't it the norm to create a
place to publish your work (and only your work) for your own use?
IOW, the above two lines solicit questions like "So... what happens
when publish does already exist??? and where does that publish
repository come from???"