{"thread":{"id":"47230","subject":"[PATCH 1/2] Documentation about triangular workflow","startedAt":"2017-11-17T16:09:17Z","lastAt":"2017-11-22T15:55:57Z","messageCount":8,"participants":["Daniel Bensoussan","Stefan Beller","Martin Ågren","Junio C Hamano","ALBERTIN TIMOTHEE p1514771"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"332760","messageId":"20171117160759.6397-1-daniel.bensoussan--bohm@etu.univ-lyon1.fr","threadId":"47230","inReplyTo":null,"subject":"[PATCH 1/2] Documentation about triangular workflow","fromName":"Daniel Bensoussan","fromEmail":"danielbensoussanbohm@gmail.com","sentAt":"2017-11-17T16:07:58Z","receivedAt":"2017-11-17T16:09:17Z","isPatch":true,"sender":{"key":"danielbensoussanbohm@gmail.com","avatar":null},"body":"From: ALBERTIN TIMOTHEE 11514771 \n\n---\n Documentation/gitworkflows.txt | 215 +++++++++++++++++++++++++++++++++++++++++\n 1 file changed, 215 insertions(+)\n\ndiff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\nindex 02569d061..3f1ddba82 100644\n--- a/Documentation/gitworkflows.txt\n+++ b/Documentation/gitworkflows.txt\n@@ -464,6 +464,221 @@ in patches to figure out the merge base. See linkgit:git-am[1] for\n other options.\n \n \n+TRIANGULAR WORKFLOW\n+-------------------\n+\n+Introduction\n+~~~~~~~~~~~~\n+\n+In some projects, contributors cannot push directly to the project but\n+have to suggest their commits to the maintainer (e.g. pull requests).\n+For these projects, it's common to use what's called a *triangular\n+workflow*:\n+\n+- The project maintainer publishes a repository, called **UPSTREAM** in\n+this document, which is a read-only for contributors. They can clone and\n+fetch from this repository.\n+- Contributors publish their modifications by pushing to a repository,\n+called **PUBLISH** in this document, and request a merge.\n+- Opening a pull request\n+- If the maintainer accepts the changes, he merges them into the\n+ **UPSTREAM** repository.\n+\n+This workflow is commonly used on different platforms like BitBucket,\n+GitHub or GitLab which provide a dedicated mechanism for requesting merges.\n+\n+........................................\n+------------------ -----------------\n+| UPSTREAM | maintainer | PUBLISH |\n+| git/git |- - - - - - - -| me/remote |\n+------------------ <- -----------------\n+ \\ /\n+ \\ /\n+ fetch | \\ / ^ push\n+ v \\ / |\n+ \\ /\n+ -------------\n+ | LOCAL |\n+ -------------\n+........................................\n+\n+Motivations\n+~~~~~~~~~~~\n+\n+* Allows contributors to work with Git even if they don't have\n+write access to **UPSTREAM**.\n+\n+Indeed, in a centralized workflow, a contributor without write access\n+could write some code but could not send it by itself. The contributor\n+was forced to create a mail which shows the difference between the\n+new and the old code, and then send it to a maintainer to commit\n+and push it. This isn't convenient at all, neither for the\n+contributor, neither for the maintainer. With the triangular\n+workflow, the contributors have the write access on **PUBLISH**\n+so they don't have to pass upon maintainer(s). And only the\n+maintainer(s) can push from **PUBLISH** to **UPSTREAM**.\n+This is called a distributed workflow (See \"DISTRIBUTED WORKFLOWS\"\n+above).\n+\n+* Code review is made before integration.\n+\n+The goal of the triangular workflow is also that the rest of the\n+community or the company can review the code before it's in production.\n+Everyone can read on **PUBLISH** so everyone can review code\n+before the maintainer(s) merge it to **UPSTREAM**. It also means\n+that, in a free software, anyone can propose code without danger\n+for the stability of the software.\n+\n+* Encourages clean history by using `rebase -i` and `push --force` to\n+the public fork before the code is merged.\n+\n+This is just a side-effect of the \"review before merge\" mentionned\n+above but this is still a good point.\n+\n+\n+\n+Here are the configuration variables you will need to arrange your\n+workflow.\n+\n+Preparation as a contributor\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+Cloning from **PUBLISH**, which is a fork of **UPSTREAM** or an empty\n+repository.\n+\n+======================\n+`git clone `\n+======================\n+\n+Setting the behavior of push for the triangular workflow:\n+\n+===========================\n+`git config push.default current`\n+===========================\n+\n+Adding **UPSTREAM** remote:\n+\n+===================================\n+`git remote add upstream `\n+===================================\n+\n+With the `remote add` above, using `git pull upstream` pulls there,\n+instead of saying its URL. In addition, the `git pull` command\n+(without argument) can be used to pull from **UPSTREAM**.\n+\n+For each branch requiring a triangular workflow, set\n+`branch..remote` and `branch..pushRemote` to set up\n+the **UPSTREAM** and **PUBLISH** repositories.\n+\n+Example with master as :\n+===================================\n+* `git config branch.master.remote upstream`\n+* `git config branch.master.pushRemote origin`\n+===================================\n+\n+Staying up-to-date\n+~~~~~~~~~~~~~~~~~~\n+\n+Retrieve updates from **UPSTREAM** with `git pull` and send them to\n+**PUBLISH** with `git push`.\n+\n+Making your work available\n+~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+The `git push` command sends commits to the **PUBLISH** repository and not to\n+the **UPSTREAM** thanks to the configuration you did earlier with the\n+`git config remote.pushdefault origin` command.\n+\n+When a contributor pushes something, the `git config push.default\n+current` command can be used to specifies that the name of the\n+**PUBLISH** branch is the same as the name of the **LOCAL** one.\n+\n+.Display the push remote's name:\n+[caption=\"Recipe: \"]\n+\n+=================================\n+`git rev-parse --abbrev-ref @{push}`\n+=================================\n+\n+The shorthand `@{push}` denotes the remote-tracking branch\n+where the would be pushed to. If no is specified\n+(`@{push}`), takes the value of the current branch.\n+\n+\n+.Display the fetch remote's name:\n+[caption=\"Recipe: \"]\n+\n+===================================\n+`git rev-parse --abbrev-ref @{upstream}`\n+===================================\n+\n+The shorthand `@{upstream}` substitutes the upstream name of\n+the branch. If no is specified (`@{upstream}`), \n+takes the value of the current branch.\n+\n+.Display commits added to the current branch since last push:\n+[caption=\"Recipe: \"]\n+\n+===============\n+`git log @{push}..`\n+===============\n+\n+.Display commits added to a specific branch since last push:\n+[caption=\"Recipe: \"]\n+\n+============================\n+`git log @{push}..`\n+============================\n+\n+Alternatively\n+~~~~~~~~~~~~~\n+\n+Cloning from **UPSTREAM**\n+[caption=\"Recipe: \"]\n+\n+In the preparation above, a clone from **PUBLISH** was used. Starting\n+with a clone of **UPSTREAM** is possible too.\n+\n+Cloning from **UPSTREAM**\n+\n+======================\n+`git clone `\n+======================\n+\n+Setting the behavior of push for the triangular workflow:\n+\n+===========================\n+`git config push.default current`\n+===========================\n+\n+Because modifications will be often pushed into the **PUBLISH** repository,\n+instead of having to type its URL every time, a short name can be used\n+to call it.\n+\n+Adding **PUBLISH** remote:\n+\n+===================================\n+`git remote add publish `\n+===================================\n+\n+With the `remote add` above, using `git push publish` pushes there,\n+instead of saying its URL. In addition, `git push` can push to\n+**PUBLISH** without argument.\n+\n+'Method 1: One option for all branches'\n+\n+===================================\n+`git config remote.pushDefault publish`\n+===================================\n+\n+'Method 2: Each branch its option'\n+\n+Example with master as :\n+===================================\n+`git config branch.master.pushRemote publish`\n+===================================\n+\n+\n SEE ALSO\n --------\n linkgit:gittutorial[7],\n-- \n2.11.0\n\n"},{"id":"332761","messageId":"20171117160759.6397-2-daniel.bensoussan--bohm@etu.univ-lyon1.fr","threadId":"47230","inReplyTo":"20171117160759.6397-1-daniel.bensoussan--bohm@etu.univ-lyon1.fr","subject":"[PATCH 2/2] Triangular workflow","fromName":"Daniel Bensoussan","fromEmail":"danielbensoussanbohm@gmail.com","sentAt":"2017-11-17T16:07:59Z","receivedAt":"2017-11-17T16:10:29Z","isPatch":true,"sender":{"key":"danielbensoussanbohm@gmail.com","avatar":null},"body":"The documentation about triangular workflow was not clear enough.\nSo it couldn't be clear enough for someone else. That's why we decided to\nchange it. Some documentation about triangular workflow already exists.\nHowever, it seems unfortunate that there is no documentation about it in Git.\n\nBased-on-patch-by: Jordan DE GEA \nSigned-off-by: Michael Haggerty \nSigned-off-by: Jordan DE GEA \nSigned-off-by: Matthieu Moy \nSigned-off-by: Timothee Albertin \nSigned-off-by: Nathan Payre \nSigned-off-by: Daniel Bensoussan \n---\n Documentation/gitworkflows.txt | 59 +++++++++++++++++++-----------------------\n 1 file changed, 26 insertions(+), 33 deletions(-)\n\ndiff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\nindex 3f1ddba82..4aea16bc0 100644\n--- a/Documentation/gitworkflows.txt\n+++ b/Documentation/gitworkflows.txt\n@@ -490,7 +490,7 @@ GitHub or GitLab which provide a dedicated mechanism for requesting merges.\n ........................................\n ------------------ -----------------\n | UPSTREAM | maintainer | PUBLISH |\n-| git/git |- - - - - - - -| me/remote |\n+| |- - - - - - - -| |\n ------------------ <- -----------------\n \\ /\n \\ /\n@@ -515,7 +515,7 @@ new and the old code, and then send it to a maintainer to commit\n and push it. This isn't convenient at all, neither for the\n contributor, neither for the maintainer. With the triangular\n workflow, the contributors have the write access on **PUBLISH**\n-so they don't have to pass upon maintainer(s). And only the\n+so they don't need maintainer(s) approval to write code. And only the\n maintainer(s) can push from **PUBLISH** to **UPSTREAM**.\n This is called a distributed workflow (See \"DISTRIBUTED WORKFLOWS\"\n above).\n@@ -526,13 +526,13 @@ The goal of the triangular workflow is also that the rest of the\n community or the company can review the code before it's in production.\n Everyone can read on **PUBLISH** so everyone can review code\n before the maintainer(s) merge it to **UPSTREAM**. It also means\n-that, in a free software, anyone can propose code without danger\n+that, in free software, anyone can propose code without danger\n for the stability of the software.\n \n * Encourages clean history by using `rebase -i` and `push --force` to\n the public fork before the code is merged.\n \n-This is just a side-effect of the \"review before merge\" mentionned\n+This is just a side-effect of the \"review before merge\" mentioned\n above but this is still a good point.\n \n \n@@ -543,18 +543,20 @@ workflow.\n Preparation as a contributor\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n-Cloning from **PUBLISH**, which is a fork of **UPSTREAM** or an empty\n-repository.\n+Cloning from **UPSTREAM**.\n \n ======================\n-`git clone `\n+`git clone `\n ======================\n \n-Setting the behavior of push for the triangular workflow:\n+If **PUBLISH** doesn't exist, a contributor can publish his own repository.\n+**PUBLISH** contains modifications before integration.\n \n-===========================\n-`git config push.default current`\n-===========================\n+============================\n+`git clone `\n+`git remote add **PUBLISH**`\n+`git push`\n+============================\n \n Adding **UPSTREAM** remote:\n \n@@ -576,12 +578,6 @@ Example with master as :\n * `git config branch.master.pushRemote origin`\n ===================================\n \n-Staying up-to-date\n-~~~~~~~~~~~~~~~~~~\n-\n-Retrieve updates from **UPSTREAM** with `git pull` and send them to\n-**PUBLISH** with `git push`.\n-\n Making your work available\n ~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n@@ -590,20 +586,19 @@ the **UPSTREAM** thanks to the configuration you did earlier with the\n `git config remote.pushdefault origin` command.\n \n When a contributor pushes something, the `git config push.default\n-current` command can be used to specifies that the name of the\n+current` command can be used to specify that the name of the\n **PUBLISH** branch is the same as the name of the **LOCAL** one.\n \n-.Display the push remote's name:\n+.Display the name of the push remote:\n [caption=\"Recipe: \"]\n \n-=================================\n-`git rev-parse --abbrev-ref @{push}`\n-=================================\n-\n The shorthand `@{push}` denotes the remote-tracking branch\n where the would be pushed to. If no is specified\n (`@{push}`), takes the value of the current branch.\n \n+=================================\n+`git rev-parse --abbrev-ref @{push}`\n+=================================\n \n .Display the fetch remote's name:\n [caption=\"Recipe: \"]\n@@ -630,6 +625,12 @@ takes the value of the current branch.\n `git log @{push}..`\n ============================\n \n+Staying up-to-date\n+~~~~~~~~~~~~~~~~~~\n+\n+Retrieve updates from **UPSTREAM** with `git pull` and send them to\n+**PUBLISH** with `git push`.\n+\n Alternatively\n ~~~~~~~~~~~~~\n \n@@ -662,16 +663,8 @@ Adding **PUBLISH** remote:\n ===================================\n \n With the `remote add` above, using `git push publish` pushes there,\n-instead of saying its URL. In addition, `git push` can push to\n-**PUBLISH** without argument.\n-\n-'Method 1: One option for all branches'\n-\n-===================================\n-`git config remote.pushDefault publish`\n-===================================\n-\n-'Method 2: Each branch its option'\n+instead of saying its URL. In addition, `git push` without argument\n+pushes to **PUBLISH**.\n \n Example with master as :\n ===================================\n-- \n2.11.0\n\n"},{"id":"332769","messageId":"CAGZ79ka5yEv0n+kZLk6p9j3HX1aR9MNs+uH7N7o7UvGx+akxxg@mail.gmail.com","threadId":"47230","inReplyTo":"20171117160759.6397-1-daniel.bensoussan--bohm@etu.univ-lyon1.fr","subject":"Re: [PATCH 1/2] Documentation about triangular workflow","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-11-17T20:01:00Z","receivedAt":"2017-11-17T20:01:07Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"Thanks for contributing to Git and making the documentation better!\n\nOn Fri, Nov 17, 2017 at 8:07 AM, Daniel Bensoussan\n wrote:\n> From: ALBERTIN TIMOTHEE 11514771 \n\nThis is a place where you can describe why this change is awesome (and\nhence the project is interested in including it.)\n\nThe Git projects requires your Sign-off (and by the differing author\nand you as a sender, both of you)\nSee Documentation/SubmittingPatches or\nhttps://developercertificate.org/ and if you can agree\nto that add a line \"Signed-off-by: name \" to the commit message\nof the text.\n\n>\n> diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\n> index 02569d061..3f1ddba82 100644\n> --- a/Documentation/gitworkflows.txt\n> +++ b/Documentation/gitworkflows.txt\n> @@ -464,6 +464,221 @@ in patches to figure out the merge base. See linkgit:git-am[1] for\n> other options.\n>\n>\n> +TRIANGULAR WORKFLOW\n> +-------------------\n> +\n> +Introduction\n> +~~~~~~~~~~~~\n> +\n> +In some projects, contributors cannot push directly to the project but\n> +have to suggest their commits to the maintainer (e.g. pull requests).\n> +For these projects, it's common to use what's called a *triangular\n> +workflow*:\n> +\n> +- The project maintainer publishes a repository, called **UPSTREAM** in\n> +this document, which is a read-only for contributors. They can clone and\n> +fetch from this repository.\n> +- Contributors publish their modifications by pushing to a repository,\n> +called **PUBLISH** in this document, and request a merge.\n> +- Opening a pull request\n> +- If the maintainer accepts the changes, he merges them into the\n> + **UPSTREAM** repository.\n> +\n> +This workflow is commonly used on different platforms like BitBucket,\n> +GitHub or GitLab which provide a dedicated mechanism for requesting merges.\n> +\n> +........................................\n> +------------------ -----------------\n> +| UPSTREAM | maintainer | PUBLISH |\n> +| git/git |- - - - - - - -| me/remote |\n> +------------------ <- -----------------\n> + \\ /\n> + \\ /\n> + fetch | \\ / ^ push\n> + v \\ / |\n> + \\ /\n> + -------------\n> + | LOCAL |\n> + -------------\n> +........................................\n\ngit/git as the upstream is a notable example which doesn't\nuse this triangular workflow, as most patches are accepted\nvia email, such that the PUBLISH remote may not exist when\ncontributing to git/git. (Though https://submitgit.herokuapp.com/\ntries to emulate the triangular workflow for contributors)\n\n\n> +This is just a side-effect of the \"review before merge\" mentionned\n> +above but this is still a good point.\n\nmentioned (typo)\n"},{"id":"332773","messageId":"CAN0heSoLbnkfJLqStvR2nfy4LAAc3KEkRH-_kE-QAQoM-4iqGA@mail.gmail.com","threadId":"47230","inReplyTo":"20171117160759.6397-1-daniel.bensoussan--bohm@etu.univ-lyon1.fr","subject":"Re: [PATCH 1/2] Documentation about triangular workflow","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2017-11-17T21:11:43Z","receivedAt":"2017-11-17T21:11:51Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On 17 November 2017 at 17:07, Daniel Bensoussan\n wrote:\n> +- If the maintainer accepts the changes, he merges them into the\n> + **UPSTREAM** repository.\n\nPersonally, I would prefer \"they\" and \"their\" over \"he\" and \"his\". I'm\nnot sure how universal this preference is, but see also 715a51bcaf (am:\ncounteract gender bias, 2016-07-08). I realize that \"he\" is already used\nin this document...\n\n> + ... The contributor\n> +was forced to create a mail which shows the difference between the\n> +new and the old code, and then send it to a maintainer to commit\n> +and push it. This isn't convenient at all, neither for the\n> +contributor, neither for the maintainer.\n\n\"neither ... nor\". That said, I find the tone of this paragraph a bit\nvalue-loaded (\"forced ... isn't convenient at all\"). It does sort of\ncontradict or at least compare interestingly with how git.git itself is\nmaintained. ;-) Maybe this could be framed in a more neutral way?\n\n> +The goal of the triangular workflow is also that the rest of the\n> +community or the company can review the code before it's in production.\n> +Everyone can read on **PUBLISH** so everyone can review code\n> +before the maintainer(s) merge it to **UPSTREAM**. It also means\n\nI think you can drop the \"(s)\". Your example workflow could have a\nsingle maintainer. In a multi-maintainer workflow, the workflow would\nstill be the same. So no need to cover all bases by sprinkling \"(s)\" on\nthe text. (IMHO.)\n\nI'll follow up with some comments on patch 2/2...\n\nMartin\n"},{"id":"332774","messageId":"CAN0heSoJissfQqO9sDi1sHut7a-tfFcQgkcUD=QLa+5F0F9PbA@mail.gmail.com","threadId":"47230","inReplyTo":"20171117160759.6397-2-daniel.bensoussan--bohm@etu.univ-lyon1.fr","subject":"Re: [PATCH 2/2] Triangular workflow","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2017-11-17T21:15:36Z","receivedAt":"2017-11-17T21:15:42Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On 17 November 2017 at 17:07, Daniel Bensoussan\n wrote:\n> The documentation about triangular workflow was not clear enough.\n\nI think you would be able to `git rebase -i` these two patches into a\nsingle, perfect patch. ;-) Maybe in collaboration with Albertin?\n\n> -===========================\n> -`git config push.default current`\n> -===========================\n> +============================\n> +`git clone `\n> +`git remote add **PUBLISH**`\n> +`git push`\n> +============================\n\nThis renders as a single line for me, including \"**PUBLISH**\". (I use\nAsciiDoctor, does this look good with AsciiDoc, I wonder?)\n\nI've never worked with triangular workflows. That means I can't judge\nthe correctness of this, but what I've read seems reasonable and\nhelpful. I dropped some comments along the way, I hope you'll find them\nconstructive.\n\nMartin\n"},{"id":"332783","messageId":"xmqqlgj4qskj.fsf@gitster.mtv.corp.google.com","threadId":"47230","inReplyTo":"20171117160759.6397-1-daniel.bensoussan--bohm@etu.univ-lyon1.fr","subject":"Re: [PATCH 1/2] Documentation about triangular workflow","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-11-18T01:33:16Z","receivedAt":"2017-11-18T01:33:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Daniel Bensoussan writes:\n\n> +TRIANGULAR WORKFLOW\n> +-------------------\n> +\n> +Introduction\n> +~~~~~~~~~~~~\n> +\n> +In some projects, contributors cannot push directly to the project but\n> +have to suggest their commits to the maintainer (e.g. pull requests).\n> +For these projects, it's common to use what's called a *triangular\n> +workflow*:\n> + ...\n> +Motivations\n> +~~~~~~~~~~~\n> +\n> +* Allows contributors to work with Git even if they don't have\n> +write access to **UPSTREAM**.\n> +\n> +Indeed, in a centralized workflow, a contributor without write access\n> +could write some code but could not send it by itself. The contributor\n> +was forced to create a mail which shows the difference between the\n> +new and the old code, and then send it to a maintainer to commit\n> +and push it. This isn't convenient at all, neither for the\n> +contributor, neither for the maintainer. With the triangular\n> +workflow, the contributors have the write access on **PUBLISH**\n> +so they don't have to pass upon maintainer(s). And only the\n> +maintainer(s) can push from **PUBLISH** to **UPSTREAM**.\n> +This is called a distributed workflow (See \"DISTRIBUTED WORKFLOWS\"\n> +above).\n\nI probably should not be judging if these additions to\ngitworkflows.txt is a good idea in the first place without seeing\nany explanation as to why this patch is here, but I think it misses\nthe place where \"triangular\" sits in a larger picture.\n\nThe workflow to contrast against to illustrate the motivation is a\ncentralized workflow, where everybody pushes their updates to a\nsingle place. It does have problems inherent to its structure\n(e.g. \"review before integration\" is much harder, if possible), and\nalso has its merits (e.g. it is simpler to explain and reason\nabout).\n\nIf you want to wean a project off of the centralized model, you'd\nneed to use the \"distributed workflow\". The workflow to review and\napply mailed patches in public, and the workflow to have the project\npull from many publish repositories individual contributor has, are\ntwo that allows the project to go distributed. These two are\ncomplementary choices with pros and cons, and it is not like one is\nan improvement of the other. Projects like the kernel even uses\nhybrid of the two---the patches are reviewed in public at central\nplaces (i.e. subsystem mailing lists) in an e-mail form and go\nthrough iterations getting polished, and the polished results are\ncollected by (sub)maintainers and sent upwards, either as a request\nto pull from publish repositories maintained by (sub)maintainers, or\nrelayed again in e-mail form (the last mile being e-mail primarily\nserves as a transport vehicle for changes proven to be good, not as\nmaterial to be further reviewed).\n\nThe reason why projects make these choices is because there are pros\nand cons. A large collection of changes is far easier to integrate\nwith one command (i.e. \"git pull\") and with a need to resolve merge\nconflicts just once, than applying many small changes as e-mailed\npatches, having to resolve many conflicts along the way. In order\nto ensure quality of the individual changes, however, the changes\nneed to be reviewed and polished, and the reality of the life is\nthat there are far fewer people who are qualified to adequately\nreview and help polishing the changes than those who make changes.\nAsking reviewers to go to different repositories (whose number\nscales with the number of contributors) and leave comments in the\nwebforms is much less efficient and more costly for the project\noverall, than asking them to subscribe to relevant mailing lists\n(whose number scales only with the number of areas of interest) and\nconduct reviews there. Other factors like \"offline access\" also\ncount when considering the two models as \"choices\".\n\nAs long as the document uses phrases like \"forced to\", \"isn't\nconvenient at all\", etc., it is clear that it starts from a wrong\npremise, \"one is an improvement over the other\".\n\n\n"},{"id":"333279","messageId":"1511367199220.88867@etu.univ-lyon1.fr","threadId":"47230","inReplyTo":"CAN0heSoLbnkfJLqStvR2nfy4LAAc3KEkRH-_kE-QAQoM-4iqGA@mail.gmail.com","subject":"RE: [PATCH 1/2] Documentation about triangular workflow","fromName":"ALBERTIN TIMOTHEE p1514771","fromEmail":"timothee.albertin@etu.univ-lyon1.fr","sentAt":"2017-11-22T15:13:17Z","receivedAt":"2017-11-22T15:13:24Z","isPatch":true,"sender":{"key":"timothee.albertin@etu.univ-lyon1.fr","avatar":null},"body":"\n>On 17 November 2017 at 17:07, Daniel Bensoussan\n> wrote:\n>> +- If the maintainer accepts the changes, he merges them into the\n>> + **UPSTREAM** repository.\n\n>Personally, I would prefer \"they\" and \"their\" over \"he\" and \"his\". I'm\n>not sure how universal this preference is, but see also 715a51bcaf (am:\n>counteract gender bias, 2016-07-08). I realize that \"he\" is already used\n>in this document...\n\nThis could be a good thing in order to be neutral. We can change this in\nthe whole file.\n\n>> + ... The contributor\n>> +was forced to create a mail which shows the difference between the\n>> +new and the old code, and then send it to a maintainer to commit\n>> +and push it. This isn't convenient at all, neither for the\n>> +contributor, neither for the maintainer.\n\n>\"neither ... nor\". That said, I find the tone of this paragraph a bit\n>value-loaded (\"forced ... isn't convenient at all\"). It does sort of\n>contradict or at least compare interestingly with how git.git itself is\n>maintained. ;-) Maybe this could be framed in a more neutral way?\n\nJunio C Hamano told us the same thing about the motivation\nsection, we'll change it the next patch.\n\n>> +The goal of the triangular workflow is also that the rest of the\n>> +community or the company can review the code before it's in production.\n>> +Everyone can read on **PUBLISH** so everyone can review code\n>> +before the maintainer(s) merge it to **UPSTREAM**. It also means\n\n>I think you can drop the \"(s)\". Your example workflow could have a\n>single maintainer. In a multi-maintainer workflow, the workflow would\n>still be the same. So no need to cover all bases by sprinkling \"(s)\" on\n>the text. (IMHO.)\n\nWe'll fix that.\n\n\nThank you for your review.\n\nTimothée Albertin\n"},{"id":"333284","messageId":"1511369748441.43953@etu.univ-lyon1.fr","threadId":"47230","inReplyTo":"xmqqlgj4qskj.fsf@gitster.mtv.corp.google.com","subject":"RE: [PATCH 1/2] Documentation about triangular workflow","fromName":"ALBERTIN TIMOTHEE p1514771","fromEmail":"timothee.albertin@etu.univ-lyon1.fr","sentAt":"2017-11-22T15:55:46Z","receivedAt":"2017-11-22T15:55:57Z","isPatch":true,"sender":{"key":"timothee.albertin@etu.univ-lyon1.fr","avatar":null},"body":"\n\nDaniel Bensoussan writes:\n\n>> +TRIANGULAR WORKFLOW\n>> +-------------------\n>> +\n>> +Introduction\n>> +~~~~~~~~~~~~\n>> +\n>> +In some projects, contributors cannot push directly to the project but\n>> +have to suggest their commits to the maintainer (e.g. pull requests).\n>> +For these projects, it's common to use what's called a *triangular\n>> +workflow*:\n>> + ...\n>> +Motivations\n>> +~~~~~~~~~~~\n>> +\n>> +* Allows contributors to work with Git even if they don't have\n>> +write access to **UPSTREAM**.\n>> +\n>> +Indeed, in a centralized workflow, a contributor without write access\n>> +could write some code but could not send it by itself. The contributor\n>> +was forced to create a mail which shows the difference between the\n>> +new and the old code, and then send it to a maintainer to commit\n>> +and push it. This isn't convenient at all, neither for the\n>> +contributor, neither for the maintainer. With the triangular\n>> +workflow, the contributors have the write access on **PUBLISH**\n>> +so they don't have to pass upon maintainer(s). And only the\n>> +maintainer(s) can push from **PUBLISH** to **UPSTREAM**.\n>> +This is called a distributed workflow (See \"DISTRIBUTED WORKFLOWS\"\n>> +above).\n\n>I probably should not be judging if these additions to\n>gitworkflows.txt is a good idea in the first place without seeing\n>any explanation as to why this patch is here, but I think it misses\n>the place where \"triangular\" sits in a larger picture.\n\nThere already have been a discussion about this documentation:\nhttps://public-inbox.org/git/E83A9439-54C8-4925-8EE3-6AEEDD9416F3@grenoble-inp.org/\nWe forgot to add it to the commit message, it will be in the next\ncommit message.\n\n>The workflow to contrast against to illustrate the motivation is a\n>centralized workflow, where everybody pushes their updates to a\n>single place. It does have problems inherent to its structure\n>(e.g. \"review before integration\" is much harder, if possible), and\n>also has its merits (e.g. it is simpler to explain and reason\n>about).\n\n>If you want to wean a project off of the centralized model, you'd\n>need to use the \"distributed workflow\". The workflow to review and\n>apply mailed patches in public, and the workflow to have the project\n>pull from many publish repositories individual contributor has, are\n>two that allows the project to go distributed. These two are\n>complementary choices with pros and cons, and it is not like one is\n>an improvement of the other. Projects like the kernel even uses\n>hybrid of the two---the patches are reviewed in public at central\n>places (i.e. subsystem mailing lists) in an e-mail form and go\n>through iterations getting polished, and the polished results are\n>collected by (sub)maintainers and sent upwards, either as a request\n>to pull from publish repositories maintained by (sub)maintainers, or\n>relayed again in e-mail form (the last mile being e-mail primarily\n>serves as a transport vehicle for changes proven to be good, not as\n>material to be further reviewed).\n\n>The reason why projects make these choices is because there are pros\n>and cons. A large collection of changes is far easier to integrate\n>with one command (i.e. \"git pull\") and with a need to resolve merge\n>conflicts just once, than applying many small changes as e-mailed\n>patches, having to resolve many conflicts along the way. In order\n>to ensure quality of the individual changes, however, the changes\n>need to be reviewed and polished, and the reality of the life is\n>that there are far fewer people who are qualified to adequately\n>review and help polishing the changes than those who make changes.\n>Asking reviewers to go to different repositories (whose number\n>scales with the number of contributors) and leave comments in the\n>webforms is much less efficient and more costly for the project\n>overall, than asking them to subscribe to relevant mailing lists\n>(whose number scales only with the number of areas of interest) and\n>conduct reviews there. Other factors like \"offline access\" also\n>count when considering the two models as \"choices\".\n\n>As long as the document uses phrases like \"forced to\", \"isn't\n>convenient at all\", etc., it is clear that it starts from a wrong\n>premise, \"one is an improvement over the other\".\n\nWe will take this into account.\nWe didn't know there were hybrid workflows.\n\nThank you for your time\n\nTimothée Albertin\n"}]}