[PATCH 2/2] Triangular workflow

[Daniel Bensoussan <danielbensoussanbohm@gmail.com>]

The documentation about triangular workflow was not clear enough.
So it couldn't be clear enough for someone else. That's why we decided to
change it. Some documentation about triangular workflow already exists.
However, it seems unfortunate that there is no documentation about it in Git.

Based-on-patch-by: Jordan DE GEA <jordan.de-gea@grenoble-inp.org>
Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: Jordan DE GEA <jordan.de-gea@grenoble-inp.org>
Signed-off-by: Matthieu Moy <matthieu.moy@univ-lyon1.fr>
Signed-off-by: Timothee Albertin <timothee.albertin@etu.univ-lyon1.fr>
Signed-off-by: Nathan Payre <nathan.payre@etu.univ-lyon1.fr>
Signed-off-by: Daniel Bensoussan <daniel.bensoussan--bohm@etu.univ-lyon1.fr>
---
 Documentation/gitworkflows.txt | 59 +++++++++++++++++++-----------------------
 1 file changed, 26 insertions(+), 33 deletions(-)

diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
index 3f1ddba82..4aea16bc0 100644
--- a/Documentation/gitworkflows.txt
+++ b/Documentation/gitworkflows.txt
@@ -490,7 +490,7 @@ GitHub or GitLab which provide a dedicated mechanism for requesting merges.
 ........................................
 ------------------               -----------------
 | UPSTREAM       |  maintainer   | PUBLISH       |
-|  git/git       |- - - - - - - -|  me/remote    |
+|                |- - - - - - - -|               |
 ------------------      <-       -----------------
               \                     /
                \                   /
@@ -515,7 +515,7 @@ new and the old code, and then send it to a maintainer to commit
 and push it.  This isn't convenient at all, neither for the
 contributor, neither for the maintainer. With the triangular
 workflow, the contributors have the write access on **PUBLISH**
-so they don't have to pass upon maintainer(s).  And only the
+so they don't need maintainer(s) approval to write code.  And only the
 maintainer(s) can push from **PUBLISH** to **UPSTREAM**.
 This is called a distributed workflow (See "DISTRIBUTED WORKFLOWS"
 above).
@@ -526,13 +526,13 @@ The goal of the triangular workflow is also that 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(s) merge it to **UPSTREAM**.  It also means
-that, in a free software, anyone can propose code without danger
+that, in free software, anyone can propose code without danger
 for the stability of the software.
 
 * Encourages clean history by using `rebase -i` and `push --force` to
 the public fork before the code is merged.
 
-This is just a side-effect of the "review before merge" mentionned
+This is just a side-effect of the "review before merge" mentioned
 above but this is still a good point.
 
 
@@ -543,18 +543,20 @@ workflow.
 Preparation as a contributor
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Cloning from **PUBLISH**, which is a fork of **UPSTREAM** or an empty
-repository.
+Cloning from **UPSTREAM**.
 
 ======================
-`git clone <PUBLISH_url>`
+`git clone <UPSTREAM_url>`
 ======================
 
-Setting the behavior of push for the triangular workflow:
+If **PUBLISH** doesn't exist, a contributor can publish his own repository.
+**PUBLISH** contains modifications before integration.
 
-===========================
-`git config push.default current`
-===========================
+============================
+`git clone <UPSTREAM_url>`
+`git remote add **PUBLISH**`
+`git push`
+============================
 
 Adding **UPSTREAM** remote:
 
@@ -576,12 +578,6 @@ Example with master as <branch>:
 * `git config branch.master.pushRemote origin`
 ===================================
 
-Staying up-to-date
-~~~~~~~~~~~~~~~~~~
-
-Retrieve updates from **UPSTREAM** with `git pull` and send them to
-**PUBLISH** with `git push`.
-
 Making your work available
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -590,20 +586,19 @@ the **UPSTREAM** thanks to the configuration you did earlier with the
 `git config remote.pushdefault origin` command.
 
 When a contributor pushes something, the `git config push.default
-current` command can be used to specifies that the name of the
+current` command can be used to specify that the name of the
 **PUBLISH** branch is the same as the name of the **LOCAL** one.
 
-.Display the push remote's name:
+.Display the name of the push remote:
 [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.
 
+=================================
+`git rev-parse --abbrev-ref @{push}`
+=================================
 
 .Display the fetch remote's name:
 [caption="Recipe: "]
@@ -630,6 +625,12 @@ takes the value of the current branch.
 `git log <branch_name>@{push}..`
 ============================
 
+Staying up-to-date
+~~~~~~~~~~~~~~~~~~
+
+Retrieve updates from **UPSTREAM** with `git pull` and send them to
+**PUBLISH** with `git push`.
+
 Alternatively
 ~~~~~~~~~~~~~
 
@@ -662,16 +663,8 @@ Adding **PUBLISH** remote:
 ===================================
 
 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'
+instead of saying its URL. In addition, `git push` without argument
+pushes to **PUBLISH**.
 
 Example with master as <branch>:
 ===================================
-- 
2.11.0