Changed the documentation about the triangular workflow because it was
not clear enough for a new contributor.
With a clearer and more precise documentation, any new Git contributors
will spend less time on understanding this doc and the way Git works.
Based-on-patch-by: Jordan DE GEA <jordan.de-gea@xxxxxxxxxxxxxxxx>
Signed-off-by: Michael Haggerty <mhagger@xxxxxxxxxxxx>
Signed-off-by: Matthieu Moy <matthieu.moy@xxxxxxxxxxxxx>
Signed-off-by: Daniel Bensoussan <daniel.bensoussan--bohm@xxxxxxxxxxxxxxxxx>
Signed-off-by: Nathan Payre <nathan.payre@xxxxxxxxxxxxxxxxx>
Signed-off-by: Timothee Albertin <timothee.albertin@xxxxxxxxxxxxxxxxx>
---
Documentation/gitworkflows.txt | 203 ++++++++++++++++++++++++++++++++++++++++-
1 file changed, 201 insertions(+), 2 deletions(-)
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.
@@ -464,6 +464,205 @@ in patches to figure out the merge base. See linkgit:git-am[1] for
other options.
+TRIANGULAR WORKFLOW
+-------------------
+
+Introduction
+~~~~~~~~~~~~
+
+In some projects, contributors cannot push directly to the project but
+have to suggest their commits to the maintainer (e.g. pull requests).
+For these projects, it's common to use what's called a *triangular
+workflow*:
+
+- The project maintainer publishes a repository, called **UPSTREAM** in
+this document, which is a read-only for contributors. They can clone and
+fetch from this repository.
+- Contributors publish their modifications by pushing to a repository,
+called **PUBLISH** in this document, and request a merge.
+- Opening a pull request
+- If the maintainers accept the changes, they merge them into the
+ **UPSTREAM** repository.
+
+This workflow is commonly used on different platforms like BitBucket,
+GitHub or GitLab which provide a dedicated mechanism for requesting merges.
+
+........................................
+------------------ -----------------
+| UPSTREAM | maintainer | PUBLISH |
+| |- - - - - - - -| |
+------------------ <- -----------------
+ \ /
+ \ /
+ fetch | \ / ^ push
+ v \ / |
+ \ /
+ -------------
+ | LOCAL |
+ -------------
+........................................
+
+Motivations
+~~~~~~~~~~~
+
+* Allows contributors to work with Git even if they don't have
+write access to **UPSTREAM**.
+
+With the triangular workflow, the contributors have the write
+access on **PUBLISH** and push their code there. Only the
+maintainers merge from **PUBLISH** to **UPSTREAM**.
+
+* Code review is done before integration.
+
+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 free software, anyone can
+propose code. Reviewers accept the code when everyone agrees
+with it.
+
+* 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" mentioned
+above, but this is still a good point.
+
+
+Here are the configuration variables you will need to arrange your
+workflow.
+
+Preparation as a contributor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Cloning from **UPSTREAM**.
+
+======================
+`git clone <UPSTREAM_url>`
+======================
+
+If **PUBLISH** doesn't exist, a contributor can publish his own repository.
+**PUBLISH** contains modifications before integration.
+
+============================
+* `git clone <UPSTREAM_url>`
+* `git remote add <PUBLISH>`
+* `git push`
+============================
+
+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, the `git pull` command
+(without argument) can be used to pull from **UPSTREAM**.
+
+For each branch requiring a triangular workflow, set
+`branch.<branch>.remote` and `branch.<branch>.pushRemote` to set up
+the **UPSTREAM** and **PUBLISH** repositories.
+
+Example with master as <branch>:
+===================================
+* `git config branch.master.remote upstream`
+* `git config branch.master.pushRemote origin`
+===================================
+
+Making your work available
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `git push` command sends commits to the **PUBLISH** repository and not to
+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 specify that the name of the
+**PUBLISH** branch is the same as the name of the **LOCAL** one.
+
+.Display the name of the push remote:
+[caption="Recipe: "]
+
+The shorthand `<branch>@{push}` denotes the remote-tracking branch
+where the <branch> would be pushed to. If no <branch> is specified,
+<branch> takes the value of the current branch.
+
+=================================
+`git rev-parse --abbrev-ref @{push}`
+=================================
+
+.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, <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}..`
+============================
+
+Staying up-to-date
+~~~~~~~~~~~~~~~~~~
+
+Retrieve updates from **UPSTREAM** with `git pull` and send them to
+**PUBLISH** with `git push`.
+
+Alternatively
+~~~~~~~~~~~~~
+
+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` without argument
+pushes to **PUBLISH**.
+
+Example with master as <branch>:
+===================================
+`git config branch.master.pushRemote publish`
+===================================
+
+
SEE ALSO
--------
linkgit:gittutorial[7],
--
2.7.4
