From: Daniel Bensoussan <daniel.bensoussan--bohm@etu.univ-lyon1.fr>
To: <git@vger.kernel.org>
Cc: Daniel Bensoussan <daniel.bensoussan--bohm@etu.univ-lyon1.fr>,
Michael Haggerty <mhagger@alum.mit.edu>,
Jordan DE GEA <jordan.de-gea@grenoble-inp.org>,
Matthieu Moy <matthieu.moy@univ-lyon1.fr>,
Timothee Albertin <timothee.albertin@etu.univ-lyon1.fr>,
Nathan Payre <nathan.payre@etu.univ-lyon1.fr>
Subject: [PATCH v2] doc: add triangular workflow
Date: Thu, 14 Dec 2017 11:48:00 +0100 [thread overview]
Message-ID: <20171214104800.4998-1-daniel.bensoussan--bohm@etu.univ-lyon1.fr> (raw)
In-Reply-To: <1512034932-14499-1-git-send-email-timothee.albertin@etu.univ-lyon1.fr>
Added a new file about triangular workflow for a clearer organization.
With a 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@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/Makefile | 1 +
Documentation/git-triangular-workflow.txt | 221 ++++++++++++++++++++++++++++++
Documentation/git.txt | 2 +-
Documentation/gittutorial.txt | 1 +
Documentation/gitworkflows.txt | 1 +
5 files changed, 225 insertions(+), 1 deletion(-)
create mode 100644 Documentation/git-triangular-workflow.txt
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
MAN1_TXT += git.txt
MAN1_TXT += gitk.txt
MAN1_TXT += gitremote-helpers.txt
diff --git a/Documentation/git-triangular-workflow.txt b/Documentation/git-triangular-workflow.txt
new file mode 100644
index 0000000..ee599b7
--- /dev/null
+++ b/Documentation/git-triangular-workflow.txt
@@ -0,0 +1,221 @@
+git-triangular-workflow(1)
+==========================
+
+NAME
+----
+git-triangular-workflow - An overview of the triangular workflow with Git
+
+
+SYNOPSIS
+--------
+[verse]
+git *
+
+
+DESCRIPTION
+-----------
+
+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 accepts 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 made 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 a free software, anyone can
+propose code. Reviewers accept the code when everyone agree
+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
+(`@{push}`), <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 (`@{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}..`
+============================
+
+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:gitworkflows[7],
+linkgit:git-push[1],
+linkgit:git-pull[1],
+linkgit:git-merge[1],
+linkgit:git-rebase[1]
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 483a1f3..3641824 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -831,7 +831,7 @@ linkgit:gittutorial[7], linkgit:gittutorial-2[7],
linkgit:giteveryday[7], linkgit:gitcvs-migration[7],
linkgit:gitglossary[7], linkgit:gitcore-tutorial[7],
linkgit:gitcli[7], link:user-manual.html[The Git User's Manual],
-linkgit:gitworkflows[7]
+linkgit:gitworkflows[7], linkgit:git-triangular-workflow.txt[1]
GIT
---
diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt
index 242de31..cc08b21 100644
--- a/Documentation/gittutorial.txt
+++ b/Documentation/gittutorial.txt
@@ -669,6 +669,7 @@ linkgit:gitcore-tutorial[7],
linkgit:gitglossary[7],
linkgit:git-help[1],
linkgit:gitworkflows[7],
+linkgit:git-triangular-workflow.txt[1],
linkgit:giteveryday[7],
link:user-manual.html[The Git User's Manual]
diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
index 02569d0..c52ee4a 100644
--- a/Documentation/gitworkflows.txt
+++ b/Documentation/gitworkflows.txt
@@ -467,6 +467,7 @@ other options.
SEE ALSO
--------
linkgit:gittutorial[7],
+linkgit:git-triangular-workflow.txt[1],
linkgit:git-push[1],
linkgit:git-pull[1],
linkgit:git-merge[1],
--
2.11.0
next prev parent reply other threads:[~2017-12-14 10:48 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 ` Daniel Bensoussan [this message]
[not found] ` <9a0556ac403845f39a564bbc55df5b3a@BPMBX2013-01.univ-lyon1.fr>
2017-12-14 15:04 ` [PATCH v2] doc: add " Matthieu Moy
2017-12-14 20:47 ` Junio C Hamano
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
Reply instructions:
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:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
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 \
--in-reply-to=20171214104800.4998-1-daniel.bensoussan--bohm@etu.univ-lyon1.fr \
--to=daniel.bensoussan--bohm@etu.univ-lyon1.fr \
--cc=git@vger.kernel.org \
--cc=jordan.de-gea@grenoble-inp.org \
--cc=matthieu.moy@univ-lyon1.fr \
--cc=mhagger@alum.mit.edu \
--cc=nathan.payre@etu.univ-lyon1.fr \
--cc=timothee.albertin@etu.univ-lyon1.fr \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* 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
https://80x24.org/mirrors/git.git
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).