* [PATCH] doc: clarify triangular workflow @ 2017-11-30 9:42 Timothee Albertin 2017-12-03 6:36 ` Junio C Hamano ` (2 more replies) 0 siblings, 3 replies; 12+ messages in thread From: Timothee Albertin @ 2017-11-30 9:42 UTC (permalink / raw) To: git Cc: Timothee Albertin, Michael Haggerty, Matthieu Moy, Daniel Bensoussan, Nathan Payre 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@grenoble-inp.org> Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Signed-off-by: Matthieu Moy <matthieu.moy@univ-lyon1.fr> Signed-off-by: Daniel Bensoussan <daniel.bensoussan--bohm@etu.univ-lyon1.fr> Signed-off-by: Nathan Payre <nathan.payre@etu.univ-lyon1.fr> Signed-off-by: Timothee Albertin <timothee.albertin@etu.univ-lyon1.fr> --- 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 ^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: [PATCH] doc: clarify triangular workflow 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-14 10:48 ` [PATCH v2] doc: add " Daniel Bensoussan [not found] ` <9a0556ac403845f39a564bbc55df5b3a@BPMBX2013-01.univ-lyon1.fr> 2 siblings, 2 replies; 12+ messages in thread From: Junio C Hamano @ 2017-12-03 6:36 UTC (permalink / raw) To: Timothee Albertin Cc: git, Timothee Albertin, Michael Haggerty, Matthieu Moy, Daniel Bensoussan, Nathan Payre Timothee Albertin <timothee.albertin@gmail.com> writes: > 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. The document starts with This document attempts to write down and motivate some of the workflow elements used for `git.git` itself. Many ideas apply in general, though the full workflow is rarely required for smaller projects with fewer people involved. and makes me wonder (note: I am not involved in writing any of the existing text in this document) how much material foreign to the actual workflow used for `git.git` should go in here. Having multiple maintainers at the same time is not a workflow element that we have ever used, for example, so I am not sure about the change in the above paragraph. > +TRIANGULAR WORKFLOW > +------------------- I really hate to say this. Before I made comment on the last round that tried to add this section, I didn't read the original closely enough. The thing is, it does already cover the triangular workflow in the "Merge workflow" section (you may need to already know what you are reading to realize that fact, though). The text in the existing "Merge workflow" section where requestor pushes to somewhere for the maintainer to pull from may not be immediately obvious, and it may be worthwhile to improve it, but I find it highly misleading to add an entirely new section as if it is describing yet another separate workflow that is different from anything that is already described in the document. It is not. A replacement of the entire section (but I'd recommend keeping the "Merge workflow" title, which contrasts well with the other "Patch workflow" that follows), or a separate document that is referred to with "see that other one for a lengthier description" by the existing "Merge workflow" section, or somewhere in between, might be a more acceptable organization, though. ^ permalink raw reply [flat|nested] 12+ messages in thread
* RE: [PATCH] doc: clarify triangular workflow 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> 1 sibling, 0 replies; 12+ messages in thread From: BENSOUSSAN--BOHM DANIEL p1507430 @ 2017-12-07 9:26 UTC (permalink / raw) To: Junio C Hamano Cc: ALBERTIN TIMOTHEE p1514771, Michael Haggerty, MOY MATTHIEU, PAYRE NATHAN p1508475, git@vger.kernel.org >The document starts with >This document attempts to write down and motivate some of the >workflow elements used for `git.git` itself. Many ideas apply >in general, though the full workflow is rarely required for >smaller projects with fewer people involved. >and makes me wonder (note: I am not involved in writing any of the >existing text in this document) how much material foreign to the >actual workflow used for `git.git` should go in here. Having >multiple maintainers at the same time is not a workflow element that >we have ever used, for example, so I am not sure about the change in >the above paragraph. We were told to change 'he' into 'they' to be neutral. However, it's true that there's one maintainer at a time so we will remove the 's' from "maintainers". >> +TRIANGULAR WORKFLOW >> +------------------- >I really hate to say this. Before I made comment on the last round >that tried to add this section, I didn't read the original closely >enough. >The thing is, it does already cover the triangular workflow in the >"Merge workflow" section (you may need to already know what you are >reading to realize that fact, though). The text in the existing >"Merge workflow" section where requestor pushes to somewhere for the >maintainer to pull from may not be immediately obvious, and it may >be worthwhile to improve it, but I find it highly misleading to add >an entirely new section as if it is describing yet another separate >workflow that is different from anything that is already described >in the document. It is not. >A replacement of the entire section (but I'd recommend keeping the >"Merge workflow" title, which contrasts well with the other "Patch >workflow" that follows), or a separate document that is referred to >with "see that other one for a lengthier description" by the >existing "Merge workflow" section, or somewhere in between, might be >a more acceptable organization, though. We'll take this into account. We will create a new file called "triangularworkflow.txt" just for the triangular workflow to be more precise because "gitworkflows.txt" is a long file. More, we first wanted to change the doc to help new contributors. If we put all the triangular workflow section in merge workflows, this won't be clear for a new contributor. Thank you for the review. Daniel BENSOUSSAN-BOHM ^ permalink raw reply [flat|nested] 12+ messages in thread
[parent not found: <24f652b96fd940ee91e2741830382a72@BPMBX2013-01.univ-lyon1.fr>]
* Re: [PATCH] doc: clarify triangular workflow [not found] ` <24f652b96fd940ee91e2741830382a72@BPMBX2013-01.univ-lyon1.fr> @ 2017-12-07 12:43 ` Matthieu Moy 2017-12-07 15:31 ` Junio C Hamano 0 siblings, 1 reply; 12+ messages in thread From: Matthieu Moy @ 2017-12-07 12:43 UTC (permalink / raw) To: BENSOUSSAN--BOHM DANIEL p1507430 Cc: Junio C Hamano, ALBERTIN TIMOTHEE p1514771, Michael Haggerty, PAYRE NATHAN p1508475, git@vger.kernel.org BENSOUSSAN--BOHM DANIEL p1507430 <daniel.bensoussan--bohm@etu.univ-lyon1.fr> writes: >>The document starts with > > >This document attempts to write down and motivate some of the > >workflow elements used for `git.git` itself. Many ideas apply > >in general, though the full workflow is rarely required for > >smaller projects with fewer people involved. > >>and makes me wonder (note: I am not involved in writing any of the >>existing text in this document) how much material foreign to the >>actual workflow used for `git.git` should go in here. Having >>multiple maintainers at the same time is not a workflow element that >>we have ever used, for example, so I am not sure about the change in >>the above paragraph. > > We were told to change 'he' into 'they' to be neutral. However, it's true > that there's one maintainer at a time so we will remove the 's' from > "maintainers". Not a native speaker, but according to wikipedia (https://en.wikipedia.org/wiki/Singular_they) it's OK to write "maintainer [singular, but already neulral] may get merge conflicts when they [sinugular they] ..." -- Matthieu Moy https://matthieu-moy.fr/ ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH] doc: clarify triangular workflow 2017-12-07 12:43 ` Matthieu Moy @ 2017-12-07 15:31 ` Junio C Hamano 0 siblings, 0 replies; 12+ messages in thread From: Junio C Hamano @ 2017-12-07 15:31 UTC (permalink / raw) To: Matthieu Moy Cc: BENSOUSSAN--BOHM DANIEL p1507430, ALBERTIN TIMOTHEE p1514771, Michael Haggerty, PAYRE NATHAN p1508475, git@vger.kernel.org Matthieu Moy <Matthieu.Moy@univ-lyon1.fr> writes: > Not a native speaker, but according to wikipedia > (https://en.wikipedia.org/wiki/Singular_they) it's OK to write > "maintainer [singular, but already neulral] may get merge conflicts when > they [sinugular they] ..." Yes. ^ permalink raw reply [flat|nested] 12+ messages in thread
* [PATCH v2] doc: add triangular workflow 2017-11-30 9:42 [PATCH] doc: clarify triangular workflow Timothee Albertin 2017-12-03 6:36 ` Junio C Hamano @ 2017-12-14 10:48 ` Daniel Bensoussan [not found] ` <9a0556ac403845f39a564bbc55df5b3a@BPMBX2013-01.univ-lyon1.fr> 2 siblings, 0 replies; 12+ messages in thread From: Daniel Bensoussan @ 2017-12-14 10:48 UTC (permalink / raw) To: git Cc: Daniel Bensoussan, Michael Haggerty, Jordan DE GEA, Matthieu Moy, Timothee Albertin, Nathan Payre 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 ^ permalink raw reply related [flat|nested] 12+ messages in thread
[parent not found: <9a0556ac403845f39a564bbc55df5b3a@BPMBX2013-01.univ-lyon1.fr>]
* Re: [PATCH v2] doc: add triangular workflow [not found] ` <9a0556ac403845f39a564bbc55df5b3a@BPMBX2013-01.univ-lyon1.fr> @ 2017-12-14 15:04 ` Matthieu Moy 2017-12-14 20:47 ` Junio C Hamano ` (2 more replies) 0 siblings, 3 replies; 12+ messages in thread From: Matthieu Moy @ 2017-12-14 15:04 UTC (permalink / raw) To: BENSOUSSAN--BOHM DANIEL p1507430 Cc: git, Michael Haggerty, Jordan DE GEA, ALBERTIN TIMOTHEE p1514771, PAYRE NATHAN p1508475 "BENSOUSSAN--BOHM DANIEL p1507430" <daniel.bensoussan--bohm@etu.univ-lyon1.fr> wrote: > Added a new file about triangular workflow for a clearer organization. "for a clearer organization" is an explanation of why you are doing things this way compared to your previous email. But this is the commit message, and its wording shoud make sense in this context, i.e. regardless of previous emails you sent which won't appear it the Git history. Now, read again this sentence: adding a file about triangular workflow does not make any "organization" "clearer". > With a more precise documentation, any new Git contributors > will spend less time on understanding this doc and the way Git works. I understand what you mean, but adding a new piece of documentation cannot make people spend less time on this particular documentation. Also "any new Git contributors will spend less time" sounds like marketing speach, not technical. Your goal is to make it easier for new users, but claiming that everybody is going to gain time by reading your documentation is a bit overselling your text. 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. > 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). > +- The project maintainer publishes a repository, called **UPSTREAM** in > +this document, which is a read-only for contributors. They can clone and s/a read-only/read-only/ Perhaps s/can/& only/ too. > +- Contributors publish their modifications by pushing to a repository, > +called **PUBLISH** in this document, and request a merge. > +- Opening a pull request Other items use full sentences, this one seems half-written. Actually, I think this item is included in the "request a merge" part of the previous one. > +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. > + > +........................................ > +------------------ ----------------- > +| UPSTREAM | maintainer | PUBLISH | > +| |- - - - - - - -| | > +------------------ <- ----------------- > + \ / > + \ / > + fetch | \ / ^ push > + v \ / | > + \ / > + ------------- > + | LOCAL | > + ------------- This kind of diagram deserves a bit of text to explain the situation. For example, LOCAL is local only for the contributor (the maintainer doesn't need to know about it for example). I'd add a sentence to explain that this gives the overall view on the flow, from the point of view of a contributor. > +With the triangular workflow, the contributors have the write > +access on **PUBLISH** and push their code there. Only the "have write access", no need for "the". > +* 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. "Encourages" has no subject. It could be OK, but for consistency with other items I'd add one ("Triangular workflow encourages ..."?). > +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 remote add needs two arguments, you're giving only one. > +* `git push` This will push to UPSTREAM, right? > +Adding **UPSTREAM** remote: > + > +=================================== > +`git remote add upstream <UPSTREAM_url>` > +=================================== In which circumstance shall one write this? If you don't say it, the reader will probably assume that this is to be done after the commands you specified right above. But then: it doesn't make sense. You've just cloned from UPSTREAM, you already have the UPSTREAM remote. > +For each branch requiring a triangular workflow, set > +`branch.<branch>.remote` and `branch.<branch>.pushRemote` to set up > +the **UPSTREAM** and **PUBLISH** repositories. This neither tells me how to set the variables, nor what the effect will be ("set up"?). > +Example with master as <branch>: > +=================================== > +* `git config branch.master.remote upstream` > +* `git config branch.master.pushRemote origin` > +=================================== origin is the remote you've cloned from. From the text above, I guess you meant it to point to PUBLISH. But all the examples "git clone" you gave are from UPSTREAM. You're mixing the case where one "git clone"s from UPSTREAM and "git remode add"s PUBLISH, and the converse. Both are possible, but the "origin" remote will be different depending on which one you chose. > +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. This explanation should be next to the place where you recommend setting remote.pushdefault. > +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. I already said it multiple times, but I don't think it's a good idea to recommend changing push.default. The default, "simple", was specifically designed to be appropriate for triangular workflow: http://git.661346.n2.nabble.com/PATCH-0-6-push-default-in-the-triangular-world-td7589907.html (PATCH 3/6 in particular) You may disagree with me, but then please explain your motivation (by replying to my messages and/or by explaining the rationale in the commit message). > +================================= > +`git rev-parse --abbrev-ref @{push}` > +================================= > + > +.Display the fetch remote's name: > +[caption="Recipe: "] > + > +=================================== > +`git rev-parse --abbrev-ref @{upstream}` > +=================================== I don't think "rev-parse" is the best example to give. I use @{upstream} all the time to see what commits I have which aren't in upstream yet: git log @{upstream}.. [ part of text not re-read by lack of time ] > --- 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], I think this deserves more than just a "SEE ALSO" link. The "merge workflow" part is essentially another name for triangular workflow. There should be a proper citation of this new triangular workflow doc, i.e. a link with an explanatory sentence somewhere in the "merge workflow" part IMHO. -- Matthieu Moy https://matthieu-moy.fr/ ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH v2] doc: add triangular workflow 2017-12-14 15:04 ` 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 15:18 ` ALBERTIN TIMOTHEE p1514771 [not found] ` <130319f3e40c4bfb81d2fc37bb4a4f9f@BPMBX2013-01.univ-lyon1.fr> 2 siblings, 2 replies; 12+ messages in thread From: Junio C Hamano @ 2017-12-14 20:47 UTC (permalink / raw) To: Matthieu Moy Cc: BENSOUSSAN--BOHM DANIEL p1507430, git, Michael Haggerty, Jordan DE GEA, ALBERTIN TIMOTHEE p1514771, PAYRE NATHAN p1508475 Matthieu Moy <matthieu.moy@univ-lyon1.fr> 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???" ^ permalink raw reply [flat|nested] 12+ messages in thread
* RE: [PATCH v2] doc: add triangular workflow 2017-12-14 20:47 ` Junio C Hamano @ 2017-12-15 15:46 ` ALBERTIN TIMOTHEE p1514771 [not found] ` <eca47dd3598045a1a3fac94f9df8e972@BPMBX2013-01.univ-lyon1.fr> 1 sibling, 0 replies; 12+ messages in thread From: ALBERTIN TIMOTHEE p1514771 @ 2017-12-15 15:46 UTC (permalink / raw) To: Junio C Hamano, MOY MATTHIEU Cc: BENSOUSSAN--BOHM DANIEL p1507430, git@vger.kernel.org, Michael Haggerty, Jordan DE GEA, PAYRE NATHAN p1508475 >>> +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. I'm wondering if this sentence is really useful. It's not essential and it will take lot of time and space to talk about it properly. So, if you agree, we'll erase it. >>> +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???" In the case of a triangular workflow, if the project already exists, PUBLISH will already exist too. However, if the project doesn't exist it is at the creator charge to create it. In fact, we just explain how doing it if the project already exist. We'll add it for the second case. BTW, the line : * `git push` is useless. Thank you for the review Timothée Albertin ^ permalink raw reply [flat|nested] 12+ messages in thread
[parent not found: <eca47dd3598045a1a3fac94f9df8e972@BPMBX2013-01.univ-lyon1.fr>]
* Re: [PATCH v2] doc: add triangular workflow [not found] ` <eca47dd3598045a1a3fac94f9df8e972@BPMBX2013-01.univ-lyon1.fr> @ 2017-12-15 16:04 ` Matthieu Moy 0 siblings, 0 replies; 12+ messages in thread From: Matthieu Moy @ 2017-12-15 16:04 UTC (permalink / raw) To: ALBERTIN TIMOTHEE p1514771 Cc: Junio C Hamano, BENSOUSSAN--BOHM DANIEL p1507430, git@vger.kernel.org, Michael Haggerty, Jordan DE GEA, PAYRE NATHAN p1508475 ALBERTIN TIMOTHEE p1514771 <timothee.albertin@etu.univ-lyon1.fr> writes: >>>> +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. > > I'm wondering if this sentence is really useful. It's not essential > and it will take lot of time and space to talk about it properly. > So, if you agree, we'll erase it. I think it is useful. My guess is that most people don't know the wording "triangular workflow", but most people know about GitHub for example. See e.g. https://trends.google.com/trends/explore?q=%22triangular%20workflow%22,github,gitlab,bitbucket So the hope here is that the reader reading this feels "Ah, OK, this is about how to do pull-requests on GitHub". OTOH, I wouldn't like a Git official documentation to be biaised towards a single hosting site. > In the case of a triangular workflow, if the project already exists, > PUBLISH will already exist too. No. If the project already exists, then UPSTREAM exists, and the contributor will create his or her own PUBLISH. There's generally two ways to do it: * On platforms supporting this, use the platform's mechanism to create a fork (e.g. fork button on GitHub/GitLab's web UI). * One can create an empty PUBLISH, clone UPSTREAM, and push to PUBLISH. -- Matthieu Moy https://matthieu-moy.fr/ ^ permalink raw reply [flat|nested] 12+ messages in thread
* RE: [PATCH v2] doc: add triangular workflow 2017-12-14 15:04 ` Matthieu Moy 2017-12-14 20:47 ` Junio C Hamano @ 2017-12-15 15:18 ` ALBERTIN TIMOTHEE p1514771 [not found] ` <130319f3e40c4bfb81d2fc37bb4a4f9f@BPMBX2013-01.univ-lyon1.fr> 2 siblings, 0 replies; 12+ messages in thread From: ALBERTIN TIMOTHEE p1514771 @ 2017-12-15 15:18 UTC (permalink / raw) To: MOY MATTHIEU Cc: git@vger.kernel.org, Michael Haggerty, Jordan DE GEA, PAYRE NATHAN p1508475, BENSOUSSAN--BOHM DANIEL p1507430 >> + >> +........................................ >> +------------------ ----------------- >> +| UPSTREAM | maintainer | PUBLISH | >> +| |- - - - - - - -| | >> +------------------ <- ----------------- >> + \ / >> + \ / >> + fetch | \ / ^ push >> + v \ / | >> + \ / >> + ------------- >> + | LOCAL | >> + ------------- >This kind of diagram deserves a bit of text to explain the situation. >For example, LOCAL is local only for the contributor (the maintainer >doesn't need to know about it for example). I'd add a sentence to >explain that this gives the overall view on the flow, from the point >of view of a contributor. Ok, we'll do that >> +* `git push` >This will push to UPSTREAM, right? Yes, we will specify it. >> +Adding **UPSTREAM** remote: >> + >> +=================================== >> +`git remote add upstream <UPSTREAM_url>` >> +=================================== >In which circumstance shall one write this? If you don't say it, the >reader will probably assume that this is to be done after the commands >you specified right above. But then: it doesn't make sense. You've >just cloned from UPSTREAM, you already have the UPSTREAM remote. Indeed, we just remove it. >> +For each branch requiring a triangular workflow, set >> +`branch.<branch>.remote` and `branch.<branch>.pushRemote` to set up >> +the **UPSTREAM** and **PUBLISH** repositories. >This neither tells me how to set the variables, nor what the effect >will be ("set up"?). We'll fix that in the next patch. >> +Example with master as <branch>: >> +=================================== >> +* `git config branch.master.remote upstream` >> +* `git config branch.master.pushRemote origin` >> +=================================== >origin is the remote you've cloned from. From the text above, I guess >you meant it to point to PUBLISH. But all the examples "git clone" you >gave are from UPSTREAM. >You're mixing the case where one "git clone"s from UPSTREAM and "git >remode add"s PUBLISH, and the converse. Both are possible, but the >"origin" remote will be different depending on which one you chose. I think I don't really get it. IMHO UPSTREAM is name from the repository you pull from and PUBLISH from the repositiry you push to. >> +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. >This explanation should be next to the place where you recommend >setting remote.pushdefault. Done. >> +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. >I already said it multiple times, but I don't think it's a good idea >to recommend changing push.default. The default, "simple", was >specifically designed to be appropriate for triangular workflow: >http://git.661346.n2.nabble.com/PATCH-0-6-push-default-in-the-triangular-world-td7589907.html >(PATCH 3/6 in particular) >You may disagree with me, but then please explain your motivation (by >replying to my messages and/or by explaining the rationale in the >commit message). I read this discussion and so I understand the point here. I agree we shouldn't recommend this. >> +================================= >> +`git rev-parse --abbrev-ref @{push}` >> +================================= >> + >> +.Display the fetch remote's name: >> +[caption="Recipe: "] >> + >> +=================================== >> +`git rev-parse --abbrev-ref @{upstream}` >> +=================================== >I don't think "rev-parse" is the best example to give. >I use @{upstream} all the time to see what commits I have which aren't >in upstream yet: >git log @{upstream}.. git log seems a better exemple. We are ok we the rest of the review Thank you for your time Timothée Albertin ^ permalink raw reply [flat|nested] 12+ messages in thread
[parent not found: <130319f3e40c4bfb81d2fc37bb4a4f9f@BPMBX2013-01.univ-lyon1.fr>]
* Re: [PATCH v2] doc: add triangular workflow [not found] ` <130319f3e40c4bfb81d2fc37bb4a4f9f@BPMBX2013-01.univ-lyon1.fr> @ 2017-12-15 15:54 ` Matthieu Moy 0 siblings, 0 replies; 12+ messages in thread From: Matthieu Moy @ 2017-12-15 15:54 UTC (permalink / raw) To: ALBERTIN TIMOTHEE p1514771 Cc: git@vger.kernel.org, Michael Haggerty, Jordan DE GEA, PAYRE NATHAN p1508475, BENSOUSSAN--BOHM DANIEL p1507430 ALBERTIN TIMOTHEE p1514771 <timothee.albertin@etu.univ-lyon1.fr> writes: >>> +Example with master as <branch>: >>> +=================================== >>> +* `git config branch.master.remote upstream` >>> +* `git config branch.master.pushRemote origin` >>> +=================================== > >>origin is the remote you've cloned from. From the text above, I guess >>you meant it to point to PUBLISH. But all the examples "git clone" you >>gave are from UPSTREAM. > >>You're mixing the case where one "git clone"s from UPSTREAM and "git >>remode add"s PUBLISH, and the converse. Both are possible, but the >>"origin" remote will be different depending on which one you chose. > > I think I don't really get it. IMHO UPSTREAM is name from the repository > you pull from and PUBLISH from the repositiry you push to. In your document, you're suggesting to clone from ORIGIN, and then to set pushRemote to origin. This means "git push" will push to ORIGIN, which doesn't work. Actually, if one follows your instructions, upstream and origin will point to the same remote. Did you test your own document on a real-life example? If not, you should do so before anything else. You should notice this kind of issues before asking for external review. -- Matthieu Moy https://matthieu-moy.fr/ ^ permalink raw reply [flat|nested] 12+ messages in thread
end of thread, other threads:[~2017-12-15 16:05 UTC | newest] Thread overview: 12+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 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 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
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).