From: Junio C Hamano <email@example.com>
To: Matthieu Moy <firstname.lastname@example.org>
Cc: BENSOUSSAN--BOHM DANIEL p1507430
email@example.com, Michael Haggerty <firstname.lastname@example.org>,
Jordan DE GEA <email@example.com>,
ALBERTIN TIMOTHEE p1514771 <firstname.lastname@example.org>,
PAYRE NATHAN p1508475 <email@example.com>
Subject: Re: [PATCH v2] doc: add triangular workflow
Date: Thu, 14 Dec 2017 12:47:14 -0800 [thread overview]
Message-ID: <firstname.lastname@example.org> (raw)
In-Reply-To: <1547311095.1194033.1513263844281.JavaMail.email@example.com> (Matthieu Moy's message of "Thu, 14 Dec 2017 16:04:04 +0100 (CET)")
Matthieu Moy <firstname.lastname@example.org> 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???"
next prev parent reply other threads:[~2017-12-14 20:47 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-11-30 9:42 [PATCH] doc: clarify triangular workflow Timothee Albertin
2017-12-03 6:36 ` Junio C Hamano
2017-12-07 9:26 ` BENSOUSSAN--BOHM DANIEL p1507430
[not found] ` <24f652b96fd940ee91e2741830382a72@BPMBX2013-01.univ-lyon1.fr>
2017-12-07 12:43 ` Matthieu Moy
2017-12-07 15:31 ` Junio C Hamano
2017-12-14 10:48 ` [PATCH v2] doc: add " Daniel Bensoussan
[not found] ` <9a0556ac403845f39a564bbc55df5b3a@BPMBX2013-01.univ-lyon1.fr>
2017-12-14 15:04 ` Matthieu Moy
2017-12-14 20:47 ` Junio C Hamano [this message]
2017-12-15 15:46 ` ALBERTIN TIMOTHEE p1514771
[not found] ` <eca47dd3598045a1a3fac94f9df8e972@BPMBX2013-01.univ-lyon1.fr>
2017-12-15 16:04 ` Matthieu Moy
2017-12-15 15:18 ` ALBERTIN TIMOTHEE p1514771
[not found] ` <130319f3e40c4bfb81d2fc37bb4a4f9f@BPMBX2013-01.univ-lyon1.fr>
2017-12-15 15:54 ` Matthieu Moy
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).