Re: [PATCHv4] Documentation: triangular workflow

["Philip Oakley" <philipoakley@iee.org>]

From: "Jordan DE GEA" <jordan.de-gea@grenoble-inp.org>
> Currently, triangular workflow can be configured, but there is no
> documentation about it. A documentation is useful to keep
> configuration possibilities up-to-date.
>
> A new subsection is created in gitworkflow.
>
> Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
> Signed-off-by: Matthieu Moy <Matthieu.Moy@grenoble-inp.fr>
> Signed-off-by: Jordan DE GEA <jordan.de-gea@grenoble-inp.org>
> ---
> Changes since v3:
> * Text reorganized to follow:
>   - Introduction
>   - Preparation
>   - Staying up-to-date
>   - Alternatively
> * Texts added to explain why we use commands in:
>   - Preparation
>   - Alternatively
>
> Documentation/gitworkflows.txt | 177 
> ++++++++++++++++++++++++++++++++++++++++-
> 1 file changed, 176 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/gitworkflows.txt 
> b/Documentation/gitworkflows.txt
> index f16c414..1ec1f63 100644
> --- a/Documentation/gitworkflows.txt
> +++ b/Documentation/gitworkflows.txt
> @@ -463,6 +463,178 @@ if you get conflicts: `git am -3` will use index 
> information contained
> in patches to figure out the merge base.  See linkgit:git-am[1] for
> other options.
>
> +TRIANGULAR WORKFLOW
> +-------------------
> +
> +In some projects, you cannot push directly to the project but have to
> +suggest your commits to the maintainer (e.g. pull requests).
> +For these projects, it's common to use what's called a *triangular
> +workflow*:
> +
> +- Taking the last version of the project by fetching from **UPSTREAM**
> +- Writing modifications and push them to a fork (e.g. **PUBLISH**)

s/a fork/an accessible fork/
Isn't one of the key points of the triangle that the user can't push to the 
upstream? (and the maintainer can't see the users local repo)

> +- Opening a pull request
s/request/request (formally or informally)/

> +- If the maintainer accepts the changes, he merges them into the
a Catch 22 here. The maintainer needs first to fetch, or othewise read, the 
mods before she could accept the changes. Perhaps

- The maintainer fetches, and reviews, the proposed changes; And if 
acceptable, merges them into the upstream.

the exact timing of the fetch will depend on the review system (see below).

> +  **UPSTREAM** repository.
> +
> +
> +........................................
> +------------------               -----------------
> +| UPSTREAM       |  maintainer   | PUBLISH       |
> +|  git/git       |- - - - - - - -|  me/remote    |
> +------------------       ←       -----------------
> +              \                     /
> +               \                   /
> +          fetch↓\                 /↑push
> +                 \               /
> +                  \             /
> +                   -------------
> +                   |   LOCAL   |
> +                   -------------
> +........................................
> +
> +Motivations
> +~~~~~~~~~~~
> +
> +* Allows contributors to work with Git even though they do not have
> +write access to **UPSTREAM**.
> +
> +* Allows maintainers to receive code from contributors they may not
> +trust.
s/trust/trust with psuh access/
It is the push/pull access issues that create the triangular workflow!

> +
> +* Code review is more efficient

more efficient than ??? in environment ??? (e.g. a review process of web 
viewing/commenting on GitHub, driven by a limited patch/mail server 
capability)


> +
> +* Encourages clean history by using `rebase -i` and `push --force` to
> +your public fork before the code is merged
> +
> +Preparation
> +~~~~~~~~~~~
> +
> +Cloning from **PUBLISH**, which is a fork of **UPSTREAM** or an empty
> +repository.

I agree here. To clone the upstream, to which you have no push access (by 
definition), would leave the config badly mis-set for the basic user. It's 
better for the user to clone their publish fork (to which they have both 
read and write access).

One issue may be the different expectations of how the fork is created (it's 
only one click on the GitHub..)

It may be worth covering the remote rename option to set that origin to the 
short and sweet 'me', or 'my', as per the ascii diagram.

> +
> +======================
> +`git clone <PUBLISH_url>`
> +======================
> +
> +Setting the behavior of push for the triangular workflow:
> +
> +===========================
> +`git config push.default current`
> +===========================
> +
> +Adding **UPSTREAM** remote:
> +
> +===================================
> +`git remote add upstream <UPSTREAM_url>`
> +===================================
> +
> +With the `remote add` above, using `git pull upstream` pulls there,
> +instead of saying its URL. In addition, `git pull` can pull from
> +**UPSTREAM** without argument.
> +
> +For each branch requiring a triangular workflow, set
> +`branch.<branch>.remote` and `branch.<branch>.pushRemote`.
> +
> +Example with master as <branch>:
> +===================================
> +* `git config branch.master.remote upstream`
> +* `git config branch.master.pushRemote origin`
> +===================================
> +
> +Stay up-to-date
> +~~~~~~~~~~~~~~~
> +
> +Retrieve updates from **UPSTREAM** with `git pull` and send them to
> +**PUBLISH** with `git push`.
> +
> +Checks
> +~~~~~~
> +
> +.Display the push remote's name:
> +[caption="Recipe: "]
> +
> +=================================
> +`git rev-parse --abbrev-ref @{push}`
> +=================================
> +
> +The shorthand `<branch>@{push}` denotes the remote-tracking branch
> +where the <branch> would be pushed to. If no <branch> is specified
> +(`@{push}`), <branch> takes the value of the current branch.
> +
> +
> +.Display the fetch remote's name:
> +[caption="Recipe: "]
> +
> +===================================
> +`git rev-parse --abbrev-ref @{upstream}`
> +===================================
> +
> +The shorthand `<branch>@{upstream}` substitutes the upstream name of
> +the branch. If no <branch> is specified (`@{upstream}`), <branch>
> +takes the value of the current branch.
> +
> +.Display commits added to the current branch since last push:
> +[caption="Recipe: "]
> +
> +===============
> +`git log @{push}..`
> +===============
> +
> +.Display commits added to a specific branch since last push:
> +[caption="Recipe: "]
> +
> +============================
> +`git log <branch_name>@{push}..`
> +============================
> +
> +Alternative configuration
> +~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +.Cloning from **UPSTREAM**
> +[caption="Recipe: "]
> +
> +In the preparation above, a clone from **PUBLISH** was used. Starting
> +with a clone of **UPSTREAM** is possible too.
> +
> +Cloning from **UPSTREAM**
> +
> +======================
> +`git clone <UPSTREAM_url>`
> +======================
> +
> +Setting the behavior of push for the triangular workflow:
> +
> +===========================
> +`git config push.default current`
> +===========================
> +
> +Because modifications will be often pushed into the **PUBLISH** 
> repository,
> +instead of having to type its URL every time, a short name can be used
> +to call it.
> +
> +Adding **PUBLISH** remote:
> +
> +===================================
> +`git remote add publish <PUBLISH_url>`
> +===================================
> +
> +With the `remote add` above, using `git push publish` pushes there,
> +instead of saying its URL. In addition, `git push` can push to
> +**PUBLISH** without argument.
> +
> +'Method 1: One option for all branches'
> +
> +===================================
> +`git config remote.pushDefault publish`
> +===================================
> +
> +'Method 2: Each branch its option'
> +
> +Example with master as <branch>:
> +===================================
> +`git config branch.master.pushRemote publish`
> +===================================
>
> SEE ALSO
> --------
> @@ -473,7 +645,10 @@ linkgit:git-merge[1],
> linkgit:git-rebase[1],
> linkgit:git-format-patch[1],
> linkgit:git-send-email[1],
> -linkgit:git-am[1]
> +linkgit:git-am[1],
> +linkgit:git-config[1],
> +linkgit:git-log[1],
> +linkgit:git-rev-parse[1]
>
> GIT
> ---