{"thread":{"id":"42454","subject":"[RFC] Triangular Workflow: user friendly full implementation","startedAt":"2016-05-26T10:06:33Z","lastAt":"2016-06-16T06:55:51Z","messageCount":41,"participants":["Jordan DE GEA","Matthieu Moy","Junio C Hamano","Philip Oakley","Michael Haggerty","Ramkumar Ramachandra"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"287563","messageId":"E83A9439-54C8-4925-8EE3-6AEEDD9416F3@grenoble-inp.org","threadId":"42454","inReplyTo":null,"subject":"[RFC] Triangular Workflow: user friendly full implementation","fromName":"Jordan DE GEA","fromEmail":"jordan.de-gea@grenoble-inp.org","sentAt":"2016-05-26T10:06:33Z","receivedAt":"2016-05-26T10:06:33Z","isPatch":false,"sender":{"key":"jordan.de-gea@grenoble-inp.org","avatar":null},"body":"We are working on full implementation of triangular workflow feature.\nFor now, the main options available are: \n\t - branch..pushRemote\n\t - remote.pushDefault\nAnd only setable by hands. \n\nAs it can be difficult to understand, here is what we want to do. \n\n\nContext:\n\t- One main remote repository, e.g. git/git.\n\t- A remote fork (e.g. a GitHub fork) of git/git, e.g. me/git.\n\t- A local clone of me/git on the machine\n\nPurposes:\n\t- the local branch master has to fetch to git/git by default\n\t- the local branch master has to push to me/git by default\n\nConfiguration wanted:\n\t- Add a remote to git/git e.g. `git remote add ...`\n\t- Set the fetch remote for branch as default. \n\nFor now, we can do that by setting: \n\t- branch..remote to git/git\n\t- branch..pushRemote to me/git\nBut many options set `branch..remote`, a suitable solution is to\nimplement an option for the fetch for example. \n\n\nHere is what we want to implement: \n\n1. \n\ta. add the config var: remote.fetchDefault\n\tb. add the config var: branch..fetchRemote\n\tc. add `git fetch --set-default` in order to set remote.fetchDefault\n\td. add `git fetch --set-remote` in order to set branch..fetchRemote\n\te. add `git pull --set-default` in order to set remote.fetchDefault\n\tf. add `git pull --set-remote` in order to set branch..fetchRemote\n\n2. \n\ta. add `git push --set-default` in order to set remote.pushDefault\n\tb. add `git push --set-remote` in order to set branch..pushRemote\n\n\nWhat's your opinion about this feature ?\n"},{"id":"287564","messageId":"vpqeg8pgjx1.fsf@anie.imag.fr","threadId":"42454","inReplyTo":"E83A9439-54C8-4925-8EE3-6AEEDD9416F3@grenoble-inp.org","subject":"Re: [RFC] Triangular Workflow: user friendly full implementation","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2016-05-26T11:04:10Z","receivedAt":"2016-05-26T11:04:10Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Jordan DE GEA writes:\n\n> Here is what we want to implement: \n\nYour message contains the word \"implement\" too many times. Before\nthinking about implementation, think, and discuss, about the design.\n\nIf your message is intended to be a discussion on the design, then avoid\nusing \"implementation\" in the subject.\n\n> 1. \n> \ta. add the config var: remote.fetchDefault\n> \tb. add the config var: branch..fetchRemote\n> \tc. add `git fetch --set-default` in order to set remote.fetchDefault\n> \td. add `git fetch --set-remote` in order to set branch..fetchRemote\n> \te. add `git pull --set-default` in order to set remote.fetchDefault\n> \tf. add `git pull --set-remote` in order to set branch..fetchRemote\n>\n> 2. \n> \ta. add `git push --set-default` in order to set remote.pushDefault\n> \tb. add `git push --set-remote` in order to set branch..pushRemote\n\nThis tells a lot about the \"what?\", but lacks the most important \"why?\"\n(or \"what for?\") question.\n\nThe user doesn't want to \"set configuration variables\". He wants to work\nwith git, have commands do the right thing, avoid typing useless\nkeystrokes and avoid surprising behavior. Please explain how your\nproposal would improve the situation. For example, show a typical\nuse-case with commands to type before and after your proposal is\nimplemented.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"287604","messageId":"xmqqwpmgvfif.fsf@gitster.mtv.corp.google.com","threadId":"42454","inReplyTo":"E83A9439-54C8-4925-8EE3-6AEEDD9416F3@grenoble-inp.org","subject":"Re: [RFC] Triangular Workflow: user friendly full implementation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-05-26T18:30:16Z","receivedAt":"2016-05-26T18:30:16Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jordan DE GEA writes:\n\n> We are working on full implementation of triangular workflow feature.\n> For now, the main options available are: \n> \t - branch..pushRemote\n> \t - remote.pushDefault\n> And only setable by hands. \n\nAnd once it is set, you do not have to worry about it. I am not\nsure per-branch thing is all that useful, unless you are always\nworking on a single branch like 'master', but the latter would be\njust set once and forget about it.\n\n> Context:\n> \t- One main remote repository, e.g. git/git.\n> \t- A remote fork (e.g. a GitHub fork) of git/git, e.g. me/git.\n> \t- A local clone of me/git on the machine\n> Purposes:\n> \t- the local branch master has to fetch to git/git by default\n> \t- the local branch master has to push to me/git by default\n\nWouldn't remote.pushDefault be the single thing you need to set just\nonce and forget about it? Why would your users even want to do\nthese things ...\n\n> \tc. add `git fetch --set-default` in order to set remote.fetchDefault\n> \td. add `git fetch --set-remote` in order to set branch..fetchRemote\n> \te. add `git pull --set-default` in order to set remote.fetchDefault\n> \tf. add `git pull --set-remote` in order to set branch..fetchRemote\n> \ta. add `git push --set-default` in order to set remote.pushDefault\n> \tb. add `git push --set-remote` in order to set branch..pushRemote\n\n... just to configure many variables every time they work on a new\nbranch?\n"},{"id":"287661","messageId":"D501BE7EF38A4CDF9ADB786B53CCFE0C@PhilipOakley","threadId":"42454","inReplyTo":"E83A9439-54C8-4925-8EE3-6AEEDD9416F3@grenoble-inp.org","subject":"Re: [RFC] Triangular Workflow: user friendly full implementation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-05-27T07:32:11Z","receivedAt":"2016-05-27T07:32:11Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Jordan DE GEA\" \n> We are working on full implementation of triangular workflow feature.\n> For now, the main options available are:\n> - branch..pushRemote\n> - remote.pushDefault\n> And only setable by hands.\n>\n> As it can be difficult to understand, here is what we want to do.\n>\n>\n> Context:\n> - One main remote repository, e.g. git/git.\n> - A remote fork (e.g. a GitHub fork) of git/git, e.g. me/git.\n> - A local clone of me/git on the machine\n>\n> Purposes:\n> - the local branch master has to fetch to git/git by default\n> - the local branch master has to push to me/git by default\n>\n> Configuration wanted:\n> - Add a remote to git/git e.g. `git remote add ...`\n> - Set the fetch remote for branch as default.\n>\n> For now, we can do that by setting:\n> - branch..remote to git/git\n> - branch..pushRemote to me/git\n> But many options set `branch..remote`, a suitable solution is to\n> implement an option for the fetch for example.\n>\n>\n> Here is what we want to implement:\n>\n> 1.\n> a. add the config var: remote.fetchDefault\n> b. add the config var: branch..fetchRemote\n> c. add `git fetch --set-default` in order to set remote.fetchDefault\n> d. add `git fetch --set-remote` in order to set branch..fetchRemote\n> e. add `git pull --set-default` in order to set remote.fetchDefault\n> f. add `git pull --set-remote` in order to set branch..fetchRemote\n>\n> 2.\n> a. add `git push --set-default` in order to set remote.pushDefault\n> b. add `git push --set-remote` in order to set branch..pushRemote\n>\n>\n> What's your opinion about this feature ?\n>\nFor me, the first step would be to actually document a (the?) Triangular \nWorkflow in the documentation, so we are all taking about the same broad \nmethod.\n\nAt the moment there is a choice (assuming a ithub like service) of either \nclone and then fork, or fork and clone the fork, which leave the user with \ndifferent fixups of their config's being required, so describing the easier \none would help folk.\n\nLikewise there are missing terms such as for the third place (the personal \nfork) that is neither the upstream, nor the local repo. Making sure the \nterminology is crisp and clean will greatly ease any implementation issues. \nAnd then there are the possible workflows...\n\n--\nPhilip\n(sorry for the rushed message, a long weekend beckons) \n"},{"id":"287791","messageId":"C4CF51FB-73AB-4500-895A-928582632BDC@grenoble-inp.org","threadId":"42454","inReplyTo":"E83A9439-54C8-4925-8EE3-6AEEDD9416F3@grenoble-inp.org","subject":"[RFC] Triangular Workflow UI improvement","fromName":"Jordan DE GEA","fromEmail":"jordan.de-gea@grenoble-inp.org","sentAt":"2016-05-30T08:39:22Z","receivedAt":"2016-05-30T08:39:22Z","isPatch":false,"sender":{"key":"jordan.de-gea@grenoble-inp.org","avatar":null},"body":"In my last message, I forgot to add some important \ncontributors linked to this feature. Some of you \nalready replied to me. \nI will answer shortly. Sorry for the noise. \n\n> \n> We are working on full implementation of triangular workflow feature.\n> For now, the main options available are: \n> \t - branch..pushRemote\n> \t - remote.pushDefault\n> And only setable by hands. \n> \n> As it can be difficult to understand, here is what we want to do. \n> \n> \n> Context:\n> \t- One main remote repository, e.g. git/git.\n> \t- A remote fork (e.g. a GitHub fork) of git/git, e.g. me/git.\n> \t- A local clone of me/git on the machine\n> \n> Purposes:\n> \t- the local branch master has to fetch to git/git by default\n> \t- the local branch master has to push to me/git by default\n> \n> Configuration wanted:\n> \t- Add a remote to git/git e.g. `git remote add ...`\n> \t- Set the fetch remote for branch as default. \n> \n> For now, we can do that by setting: \n> \t- branch..remote to git/git\n> \t- branch..pushRemote to me/git\n> But many options set `branch..remote`, a suitable solution is to\n> implement an option for the fetch for example. \n> \n> \n> Here is what we want to implement: \n> \n> 1. \n> \ta. add the config var: remote.fetchDefault\n> \tb. add the config var: branch..fetchRemote\n> \tc. add `git fetch --set-default` in order to set remote.fetchDefault\n> \td. add `git fetch --set-remote` in order to set branch..fetchRemote\n> \te. add `git pull --set-default` in order to set remote.fetchDefault\n> \tf. add `git pull --set-remote` in order to set branch..fetchRemote\n> \n> 2. \n> \ta. add `git push --set-default` in order to set remote.pushDefault\n> \tb. add `git push --set-remote` in order to set branch..pushRemote\n> \n> \n> What's your opinion about this feature ?\n"},{"id":"287793","messageId":"521237FA-0DC4-4C47-AB44-778888A7726F@grenoble-inp.org","threadId":"42454","inReplyTo":"xmqqwpmgvfif.fsf@gitster.mtv.corp.google.com","subject":"[RFC] Triangular Workflow UI improvement","fromName":"Jordan DE GEA","fromEmail":"jordan.de-gea@grenoble-inp.org","sentAt":"2016-05-30T08:46:40Z","receivedAt":"2016-05-30T08:46:40Z","isPatch":false,"sender":{"key":"jordan.de-gea@grenoble-inp.org","avatar":null},"body":">> We are working on full implementation of triangular workflow feature.\n>> For now, the main options available are: \n>> \t - branch..pushRemote\n>> \t - remote.pushDefault\n>> And only setable by hands. \n> \n> And once it is set, you do not have to worry about it. I am not\n> sure per-branch thing is all that useful, unless you are always\n> working on a single branch like 'master', but the latter would be\n> just set once and forget about it.\n\nWe got the example of our fork of git(e.g. GitHub). \nWe want : \n - some branches that only fetch from git/git and push to our/git\n - the others branches fetch from and push to our/git. \nFor now, we have to change branch..remote and \nbranch..pushRemote(or remote.pushDefault). \nWith branch..fetchRemote, we only have to set this one. \nfetchRemote is more explicit than remote for that case. \n\nAnother point is that many commands can erase the old \nvalue of branch..remote. \n\n>> Context:\n>> \t- One main remote repository, e.g. git/git.\n>> \t- A remote fork (e.g. a GitHub fork) of git/git, e.g. me/git.\n>> \t- A local clone of me/git on the machine\n>> Purposes:\n>> \t- the local branch master has to fetch to git/git by default\n>> \t- the local branch master has to push to me/git by default\n> \n> Wouldn't remote.pushDefault be the single thing you need to set just\n> once and forget about it? Why would your users even want to do\n> these things …\n\nremote.pushDefault overrides branch..remote for all branches. \nThe goal is to give an easily understandable config for \ncomplex configuration. \nHaving all the configuration in the same part (e.g [branch « master »]) \nis easier to understand and edit. \n\n> \n>> \tc. add `git fetch --set-default` in order to set remote.fetchDefault\n>> \td. add `git fetch --set-remote` in order to set branch..fetchRemote\n>> \te. add `git pull --set-default` in order to set remote.fetchDefault\n>> \tf. add `git pull --set-remote` in order to set branch..fetchRemote\n>> \ta. add `git push --set-default` in order to set remote.pushDefault\n>> \tb. add `git push --set-remote` in order to set branch..pushRemote\n> \n> ... just to configure many variables every time they work on a new\n> branch?\n\nbranch..pushRemote and all these options are optional.\nOptions in commands may not be added. It just gives user \nfriendly interaction with these options. \n\n\n\nTo conclude: \nThis feature is more about configuration clarity than possibility itself. \n"},{"id":"287794","messageId":"9A874F00-ABD8-43D5-A32E-6A39ED333E6D@grenoble-inp.org","threadId":"42454","inReplyTo":"D501BE7EF38A4CDF9ADB786B53CCFE0C@PhilipOakley","subject":"[RFC] Triangular Workflow UI improvments","fromName":"Jordan DE GEA","fromEmail":"jordan.de-gea@grenoble-inp.org","sentAt":"2016-05-30T09:07:30Z","receivedAt":"2016-05-30T09:07:30Z","isPatch":false,"sender":{"key":"jordan.de-gea@grenoble-inp.org","avatar":null},"body":"\n> Le 27 mai 2016 à 09:32, Philip Oakley a écrit :\n> For me, the first step would be to actually document a (the?) Triangular Workflow in the documentation, so we are all taking about the same broad method.\n> \n> At the moment there is a choice (assuming a ithub like service) of either clone and then fork, or fork and clone the fork, which leave the user with different fixups of their config's being required, so describing the easier one would help folk.\n> \n> Likewise there are missing terms such as for the third place (the personal fork) that is neither the upstream, nor the local repo. Making sure the terminology is crisp and clean will greatly ease any implementation issues. And then there are the possible workflows...\n\nYes, you’re right. \n\nWriting a complete tutorial is a good idea. \n\nI start this job and the content will depend \non the result of this discussion. \n"},{"id":"287894","messageId":"1464697717-5751-1-git-send-email-jordan.de-gea@grenoble-inp.org","threadId":"42454","inReplyTo":"9A874F00-ABD8-43D5-A32E-6A39ED333E6D@grenoble-inp.org","subject":"[RFC/PATCH] Triangular Workflow UI improvement: Documentation","fromName":"Jordan DE GEA","fromEmail":"jordan.de-gea@grenoble-inp.org","sentAt":"2016-05-31T12:28:37Z","receivedAt":"2016-05-31T12:28:37Z","isPatch":true,"sender":{"key":"jordan.de-gea@grenoble-inp.org","avatar":null},"body":"Currently, Triangular Workflow can be configured, but there is no\nDocumentation about it. A documentation is useful to keep\nconfiguration possibilities up-to-date.\nThe new documentation file gittriangularworkflow explains\nhow to configure a triangular workflow.\n\nSigned-off-by: Matthieu Moy \nSigned-off-by: Jordan DE GEA \n---\n Documentation/Makefile | 1 +\n Documentation/gittriangularworkflow.txt | 120 ++++++++++++++++++++++++++++++++\n 2 files changed, 121 insertions(+)\n create mode 100644 Documentation/gittriangularworkflow.txt\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex f6e288b..e9f6c80 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -34,6 +34,7 @@ MAN7_TXT += gitrevisions.txt\n MAN7_TXT += gittutorial-2.txt\n MAN7_TXT += gittutorial.txt\n MAN7_TXT += gitworkflows.txt\n+MAN7_TXT += gittriangularworkflow.txt\n \n MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)\n MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))\ndiff --git a/Documentation/gittriangularworkflow.txt b/Documentation/gittriangularworkflow.txt\nnew file mode 100644\nindex 0000000..803eee3\n--- /dev/null\n+++ b/Documentation/gittriangularworkflow.txt\n@@ -0,0 +1,120 @@\n+gittriangularworkflow(7)\n+=======================\n+\n+NAME\n+----\n+gittriangularworkflow - A tutorial about the configuration of a\n+Triangular Workflow\n+\n+SYNOPSIS\n+--------\n+[verse]\n+git fetch\n+git remote\n+git config\n+Options in git-config:\n+- `remote.pushDefault`\n+- `branch..pushRemote`\n+- `branch..origin`\n+\n+DESCRIPTION\n+-----------\n+\n+Triangular Workflow (or Asymmetric Workflow) is a workflow which gives\n+the possibility to:\n+\n+- fetch (or pull) from a repository\n+- push to another repository\n+\n+In some projects, you don't have to push directly to the project but\n+have to suggest your commits to the maintainer (e.g. pull requests).\n+Using Triangular Workflow is a common way for these projects.\n+\n+This document attempts to help you configure a Triangular Workflow.\n+Here is an example of configuration:\n+\n+........................................\n+------------ -----------\n+| UPSTREAM | maintainer | ORIGIN |\n+| git/git |- - - - - - - -| me/git |\n+------------ ← -----------\n+ \\ /\n+ \\ /\n+ fetch↓\\ /↑push\n+ \\ /\n+ \\ /\n+ -------------\n+ | LOCAL |\n+ -------------\n+........................................\n+\n+CREATE YOUR REPOSITORY\n+----------------------\n+The first step is to create your own repository. To do that you can:\n+\n+- a. fork (e.g. GitHub) the main project (e.g git/git), or\n+- b. create an empty repository\n+\n+a. Fork the project\n+~~~~~~~~~~~~~~~~~~~\n+Go to the repository of the project (e.g. git/git) you want\n+and fork it.\n+\n+b. Create from scratch\n+~~~~~~~~~~~~~~~~~~~~~~\n+Create a repository on your prefered Git repository hosting service.\n+\n+Clone it\n+~~~~~~~~\n+Clone your repository on your machine.\n+\n+\n+CONFIGURE BRANCHES\n+------------------\n+In many projects, the branch `master` have to be pulled from\n+the main repository(e.g. git/git) and pushed to your repository\n+(e.g. me/git).\n+\n+Adding the main project remote\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+Add a new remote (e.g. upstream):\n+\n+===================================\n+`git remote add upstream `\n+===================================\n+\n+Pull from upstream by default\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+===================================\n+`git config branch.master.remote upstream`\n+===================================\n+\n+\n+Push to origin by default\n+~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+===================================\n+`git config branch.master.pushRemote origin`\n+===================================\n+\n+\n+GET YOUR PROJECT UP TO DATE\n+---------------------------\n+\n+Now that `branch.master.remote` and `branch.master.pushRemote` are\n+set, you can use the following commands to be up to date:\n+=====================================\n+ * `git pull`\n+ * `git push`\n+=====================================\n+\n+\n+SEE ALSO\n+--------\n+linkgit:git-config[1]\n+linkgit:git-remote[1]\n+linkgit:git-fetch[1]\n+\n+\n+\n-- \n2.7.4 (Apple Git-66)\n"},{"id":"287898","messageId":"vpqy46qs3f3.fsf@anie.imag.fr","threadId":"42454","inReplyTo":"1464697717-5751-1-git-send-email-jordan.de-gea@grenoble-inp.org","subject":"Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2016-05-31T14:33:20Z","receivedAt":"2016-05-31T14:33:20Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"[ +Cc Michael Haggerty ]\n\nJordan DE GEA writes:\n\n> Currently, Triangular Workflow can be configured, but there is no\n> Documentation about it. A documentation is useful to keep\n> configuration possibilities up-to-date.\n\nYou're using capitalization in a strange way. I don't think Triangular\nWorkflow deserves to be capitalized, and Documentation certainly\ndoesn't.\n\nAlso, you're wrapping your text in a strange way. You did see the\nexchange with Antoine about this, right?\n\nA question about your final goal: I had understood that you wanted to\nimprove the UI, and to design a proper UI you wanted to write a tutorial\nabout the future UI, and then implement it. Did I mis-understand? What\nare the next steps in your plan?\n\n> Documentation/Makefile | 1 +\n> Documentation/gittriangularworkflow.txt | 120 ++++++++++++++++++++++++++++++++\n[...]\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -34,6 +34,7 @@ MAN7_TXT += gitrevisions.txt\n> MAN7_TXT += gittutorial-2.txt\n> MAN7_TXT += gittutorial.txt\n> MAN7_TXT += gitworkflows.txt\n> +MAN7_TXT += gittriangularworkflow.txt\n\nAdding documentation is one thing, but it needs to be discoverable. No\none is going to type \"man gittriangularworkflow\" or open\nhttps://git-scm.com/docs/gittriangularworkflow without being told to.\n\nTwo obvious questions/suggestions seeing the above:\n\n* Why not add the new documentation as a subsection of gitworkflows.txt?\n\n* If not, then at the very least a link to gittriangularworkflow should\n appear in the SEE ALSO section of gitworkflows.txt.\n\n> +DESCRIPTION\n> +-----------\n> +\n> +Triangular Workflow (or Asymmetric Workflow) is a workflow which gives\n> +the possibility to:\n> +\n> +- fetch (or pull) from a repository\n> +- push to another repository\n\nI wouldn't say \"gives the possibility to\": you already have this\npossibility all the time when using Git.\n\nI find Michael Haggerty's definition of triangular workflow much\nclearer:\n\nhttps://github.com/blog/2042-git-2-5-including-multiple-worktrees-and-triangular-workflows#improved-support-for-triangular-workflows\n\nI don't see a licence on the GitHub blog, so I don't think it's legal to\ncopy-past directly to our docs, but Michael might allow us to do so?\n\n> +In some projects, you don't have to push directly\n\ns/don't have to/cannot/\n\n?\n\n> +Here is an example of configuration:\n> +\n> +........................................\n> +------------ -----------\n> +| UPSTREAM | maintainer | ORIGIN |\n> +| git/git |- - - - - - - -| me/git |\n> +------------ ← -----------\n> + \\ /\n> + \\ /\n> + fetch↓\\ /↑push\n> + \\ /\n> + \\ /\n> + -------------\n> + | LOCAL |\n> + -------------\n> +........................................\n\nThe most important is missing: what is the role of each repo? which one\nis public and which one is private?\n\nI'd rather avoid using \"ORIGIN\" here, as the name is used for the\ndefault remote when cloning, and it's a valid workflow to \"git clone\"\nfrom UPSTREAM and then \"git remote add\" your public fork. Perhaps\nPUBLIC-FORK?\n\n> +CREATE YOUR REPOSITORY\n> +----------------------\n> +The first step is to create your own repository. To do that you can:\n> +\n> +- a. fork (e.g. GitHub) the main project (e.g git/git), or\n> +- b. create an empty repository\n> +\n> +a. Fork the project\n> +~~~~~~~~~~~~~~~~~~~\n> +Go to the repository of the project (e.g. git/git) you want\n> +and fork it.\n> +\n> +b. Create from scratch\n> +~~~~~~~~~~~~~~~~~~~~~~\n> +Create a repository on your prefered Git repository hosting service.\n> +\n> +Clone it\n> +~~~~~~~~\n> +Clone your repository on your machine.\n\nI don't think this section helps much. If the user knows that he or she\nwants to \"fork (e.g. GitHub) the main project (e.g git/git),\", then\nsaying\n\n +a. Fork the project\n +~~~~~~~~~~~~~~~~~~~\n +Go to the repository of the project (e.g. git/git) you want\n +and fork it.\n\ndoes not help at all, it just says the same thing in a more verbose way.\n\n> +CONFIGURE BRANCHES\n> +------------------\n> +In many projects, the branch `master` have to be pulled from\n> +the main repository(e.g. git/git) and pushed to your repository\n> +(e.g. me/git).\n\nBe precise: you just named 3 repositories UPSTREAM, ORIGIN and LOCAL,\nand now you're writting \"the main repository\" (not 100% clear) and \"your\nrepository\" (100% not clear, you have two repos).\n\nActually, most of the time, you'd pull from UPSTREAM/master and push to\nPUBLIC-FORK/, not PUBLIC-FORK/master.\n\n> +Adding the main project remote\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> +Add a new remote (e.g. upstream):\n> +\n> +===================================\n> +`git remote add upstream `\n> +===================================\n> +\n> +Pull from upstream by default\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> +\n> +===================================\n> +`git config branch.master.remote upstream`\n> +===================================\n> +\n> +\n> +Push to origin by default\n> +~~~~~~~~~~~~~~~~~~~~~~~~~\n> +\n> +===================================\n> +`git config branch.master.pushRemote origin`\n> +===================================\n\n\"by default\" probably needs to be clarified (\"when push/pull is called\nwithout argument\"?)\n\n> +GET YOUR PROJECT UP TO DATE\n> +---------------------------\n> +\n> +Now that `branch.master.remote` and `branch.master.pushRemote` are\n> +set, you can use the following commands to be up to date:\n\nWhat does \"be up to date\" mean?\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"287990","messageId":"2254CE50-8B7C-4FFF-BAA3-26EF1932AAD4@grenoble-inp.org","threadId":"42454","inReplyTo":"vpqy46qs3f3.fsf@anie.imag.fr","subject":"Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation","fromName":"Jordan DE GEA","fromEmail":"jordan.de-gea@grenoble-inp.org","sentAt":"2016-06-01T09:32:19Z","receivedAt":"2016-06-01T09:32:19Z","isPatch":true,"sender":{"key":"jordan.de-gea@grenoble-inp.org","avatar":null},"body":"> Jordan DE GEA writes:\n>> Currently, Triangular Workflow can be configured, but there is no\n>> Documentation about it. A documentation is useful to keep\n>> configuration possibilities up-to-date.\n> \n> You're using capitalization in a strange way. I don't think Triangular\n> Workflow deserves to be capitalized, and Documentation certainly\n> doesn't.\n> \n> Also, you're wrapping your text in a strange way. You did see the\n> exchange with Antoine about this, right?\n\nYes, thank you. I will fix that. \n\n> A question about your final goal: I had understood that you wanted to\n> improve the UI, and to design a proper UI you wanted to write a tutorial\n> about the future UI, and then implement it. Did I mis-understand? What\n> are the next steps in your plan?\n\nThe first goal is to write a documentation on \"how to set up a triangular\nworkflow\" with the current options. After that, we can discuss about the\nUI improvement. \n\n>> Documentation/Makefile | 1 +\n>> Documentation/gittriangularworkflow.txt | 120 ++++++++++++++++++++++++++++++++\n> [...]\n>> --- a/Documentation/Makefile\n>> +++ b/Documentation/Makefile\n>> @@ -34,6 +34,7 @@ MAN7_TXT += gitrevisions.txt\n>> MAN7_TXT += gittutorial-2.txt\n>> MAN7_TXT += gittutorial.txt\n>> MAN7_TXT += gitworkflows.txt\n>> +MAN7_TXT += gittriangularworkflow.txt\n> \n> Adding documentation is one thing, but it needs to be discoverable. No\n> one is going to type \"man gittriangularworkflow\" or open\n> https://git-scm.com/docs/gittriangularworkflow without being told to.\n> \n> Two obvious questions/suggestions seeing the above:\n> \n> * Why not add the new documentation as a subsection of gitworkflows.txt?\n> \n> * If not, then at the very least a link to gittriangularworkflow should\n> appear in the SEE ALSO section of gitworkflows.txt.\n\nYes, adding a subsection in gitworkflows seems to be a better choice.\n\n> \n>> +DESCRIPTION\n>> +-----------\n>> +\n>> +Triangular Workflow (or Asymmetric Workflow) is a workflow which gives\n>> +the possibility to:\n>> +\n>> +- fetch (or pull) from a repository\n>> +- push to another repository\n> \n> I wouldn't say \"gives the possibility to\": you already have this\n> possibility all the time when using Git.\n> \n> I find Michael Haggerty's definition of triangular workflow much\n> clearer:\n> \n> https://github.com/blog/2042-git-2-5-including-multiple-worktrees-and-triangular-workflows#improved-support-for-triangular-workflows\n> \n> I don't see a licence on the GitHub blog, so I don't think it's legal to\n> copy-past directly to our docs, but Michael might allow us to do so?\n\nYou’re right. Can Michael Taggerty allow us to use his text ?\n\n> \n>> +In some projects, you don't have to push directly\n> \n> s/don't have to/cannot/\n\nDone\n\n> ?\n> \n>> +Here is an example of configuration:\n>> +\n>> +........................................\n>> +------------ -----------\n>> +| UPSTREAM | maintainer | ORIGIN |\n>> +| git/git |- - - - - - - -| me/git |\n>> +------------ ← -----------\n>> + \\ /\n>> + \\ /\n>> + fetch↓\\ /↑push\n>> + \\ /\n>> + \\ /\n>> + -------------\n>> + | LOCAL |\n>> + -------------\n>> +........................................\n> \n> The most important is missing: what is the role of each repo? which one\n> is public and which one is private?\n> \n> I'd rather avoid using \"ORIGIN\" here, as the name is used for the\n> default remote when cloning, and it's a valid workflow to \"git clone\"\n> from UPSTREAM and then \"git remote add\" your public fork. Perhaps\n> PUBLIC-FORK?\n\nWith Michael Taggerty’s text, it will be more understandable. \n\n> \n>> +CREATE YOUR REPOSITORY\n>> +----------------------\n>> +The first step is to create your own repository. To do that you can:\n>> +\n>> +- a. fork (e.g. GitHub) the main project (e.g git/git), or\n>> +- b. create an empty repository\n>> +\n>> +a. Fork the project\n>> +~~~~~~~~~~~~~~~~~~~\n>> +Go to the repository of the project (e.g. git/git) you want\n>> +and fork it.\n>> +\n>> +b. Create from scratch\n>> +~~~~~~~~~~~~~~~~~~~~~~\n>> +Create a repository on your prefered Git repository hosting service.\n>> +\n>> +Clone it\n>> +~~~~~~~~\n>> +Clone your repository on your machine.\n> \n> I don't think this section helps much. If the user knows that he or she\n> wants to \"fork (e.g. GitHub) the main project (e.g git/git),\", then\n> saying\n> \n> +a. Fork the project\n> +~~~~~~~~~~~~~~~~~~~\n> +Go to the repository of the project (e.g. git/git) you want\n> +and fork it.\n> \n> does not help at all, it just says the same thing in a more verbose way.\n\nI will shorten for the next iteration. \n\n>> +CONFIGURE BRANCHES\n>> +------------------\n>> +In many projects, the branch `master` have to be pulled from\n>> +the main repository(e.g. git/git) and pushed to your repository\n>> +(e.g. me/git).\n> \n> Be precise: you just named 3 repositories UPSTREAM, ORIGIN and LOCAL,\n> and now you're writting \"the main repository\" (not 100% clear) and \"your\n> repository\" (100% not clear, you have two repos).\n> \n> Actually, most of the time, you'd pull from UPSTREAM/master and push to\n> PUBLIC-FORK/, not PUBLIC-FORK/master.\n> \n>> +Adding the main project remote\n>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>> +Add a new remote (e.g. upstream):\n>> +\n>> +===================================\n>> +`git remote add upstream `\n>> +===================================\n>> +\n>> +Pull from upstream by default\n>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>> +\n>> +===================================\n>> +`git config branch.master.remote upstream`\n>> +===================================\n>> +\n>> +\n>> +Push to origin by default\n>> +~~~~~~~~~~~~~~~~~~~~~~~~~\n>> +\n>> +===================================\n>> +`git config branch.master.pushRemote origin`\n>> +===================================\n> \n> \"by default\" probably needs to be clarified (\"when push/pull is called\n> without argument »?)\n\nYes, that is too verbose. \n\n> \n>> +GET YOUR PROJECT UP TO DATE\n>> +---------------------------\n>> +\n>> +Now that `branch.master.remote` and `branch.master.pushRemote` are\n>> +set, you can use the following commands to be up to date:\n> \n> What does \"be up to date\" mean?\n\nOK. \n\n\nI'll work on these issues and send a new RFC soon. \n"},{"id":"288117","messageId":"57502068.5000500@alum.mit.edu","threadId":"42454","inReplyTo":"vpqy46qs3f3.fsf@anie.imag.fr","subject":"Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation","fromName":"Michael Haggerty","fromEmail":"mhagger@alum.mit.edu","sentAt":"2016-06-02T12:02:48Z","receivedAt":"2016-06-02T12:02:48Z","isPatch":true,"sender":{"key":"mhagger@alum.mit.edu","avatar":"https://avatars.githubusercontent.com/u/119718?v=4"},"body":"On 05/31/2016 04:33 PM, Matthieu Moy wrote:\n> Jordan DE GEA writes:\n> [...]\n>> +DESCRIPTION\n>> +-----------\n>> +\n>> +Triangular Workflow (or Asymmetric Workflow) is a workflow which gives\n>> +the possibility to:\n>> +\n>> +- fetch (or pull) from a repository\n>> +- push to another repository\n> \n> [...]\n> \n> I find Michael Haggerty's definition of triangular workflow much\n> clearer:\n> \n> https://github.com/blog/2042-git-2-5-including-multiple-worktrees-and-triangular-workflows#improved-support-for-triangular-workflows\n> \n> I don't see a licence on the GitHub blog, so I don't think it's legal to\n> copy-past directly to our docs, but Michael might allow us to do so?\n\nI'm glad you find that blog post useful!\n\nYou are correct that the text of GitHub blog posts is copyrighted, so\nindeed you need to ask before using it.\n\nIt is OK with me (and more importantly with GitHub, because I wrote this\ntext in their employ) for you to use the text about triangular workflows\nfrom the blog post mentioned above under the Git project's license.\n\nI strongly suggest that you adapt it to make it fit better with the rest\nof the Git documentation, and because having verbatim copies of the same\ntext in two places seems a little bit silly. But that's up to you.\n\nSigned-off-by: Michael Haggerty \n\nMichael\n"},{"id":"288196","messageId":"9FB65CA220F84B6B882B75435DDA3D65@PhilipOakley","threadId":"42454","inReplyTo":"1464697717-5751-1-git-send-email-jordan.de-gea@grenoble-inp.org","subject":"Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-03T07:25:27Z","receivedAt":"2016-06-03T07:25:27Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"[Just catching up with responses]\n\nFrom: \"Jordan DE GEA\" \nSent: Tuesday, May 31, 2016 1:28 PM\n> Currently, Triangular Workflow can be configured, but there is no\n> Documentation about it. A documentation is useful to keep\n> configuration possibilities up-to-date.\n> The new documentation file gittriangularworkflow explains\n> how to configure a triangular workflow.\n>\n> Signed-off-by: Matthieu Moy \n> Signed-off-by: Jordan DE GEA \n> ---\n> Documentation/Makefile | 1 +\n> Documentation/gittriangularworkflow.txt | 120 \n> ++++++++++++++++++++++++++++++++\n> 2 files changed, 121 insertions(+)\n> create mode 100644 Documentation/gittriangularworkflow.txt\n>\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index f6e288b..e9f6c80 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -34,6 +34,7 @@ MAN7_TXT += gitrevisions.txt\n> MAN7_TXT += gittutorial-2.txt\n> MAN7_TXT += gittutorial.txt\n> MAN7_TXT += gitworkflows.txt\n> +MAN7_TXT += gittriangularworkflow.txt\n>\n> MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)\n> MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))\n> diff --git a/Documentation/gittriangularworkflow.txt \n> b/Documentation/gittriangularworkflow.txt\n> new file mode 100644\n> index 0000000..803eee3\n> --- /dev/null\n> +++ b/Documentation/gittriangularworkflow.txt\n> @@ -0,0 +1,120 @@\n> +gittriangularworkflow(7)\n> +=======================\n> +\n> +NAME\n> +----\n> +gittriangularworkflow - A tutorial about the configuration of a\n> +Triangular Workflow\n> +\n> +SYNOPSIS\n> +--------\n> +[verse]\n> +git fetch\n> +git remote\n> +git config\n> +Options in git-config:\n> +- `remote.pushDefault`\n> +- `branch..pushRemote`\n> +- `branch..origin`\n> +\n> +DESCRIPTION\n> +-----------\n> +\n> +Triangular Workflow (or Asymmetric Workflow) is a workflow which gives\n> +the possibility to:\n> +\n> +- fetch (or pull) from a repository\n> +- push to another repository\n> +\n> +In some projects, you don't have to push directly to the project but\n> +have to suggest your commits to the maintainer (e.g. pull requests).\n> +Using Triangular Workflow is a common way for these projects.\n> +\n> +This document attempts to help you configure a Triangular Workflow.\n> +Here is an example of configuration:\n> +\n> +........................................\n> +------------ -----------\n> +| UPSTREAM | maintainer | ORIGIN |\n\nUPSTREAM and ORIGIN are two different types of description. Origin being a \ntoo generic Git name that is used multiply elsewhere.\n\nThat said, trying to find a good name for that 'third place' is not easy. \nIt's neither upstream, nor downstream (for Junio - the maintainer special \ncase - git.git would be his downstream). The me/git repo is like a \nferryman's landing across the other side of the river flow, a safe harbour \nif you will.\n\nFinding a suitable name has all the same issues as deciding the generic \npublic name for the staging area / index. The ability to have a second \nperfect copy is very new - historically all the dictionary names relate to \ncopies or forgeries (you could only have one master - DVCS breaks that \nmould). Perhaps (poorly) \"MyFork\", or \"MyServer\". There maybe a good French \nword we can use.\n\n> +| git/git |- - - - - - - -| me/git |\n\nI think it is good to reference the use of \"me\" as a short remote name - \npersonally I ended up using \"my\"/remote, but having one in the documentation \nwill set a common trend.\n\n> +------------ ← -----------\n> + \\ /\n> + \\ /\n> + fetch↓\\ /↑push\n> + \\ /\n> + \\ /\n> + -------------\n> + | LOCAL |\n> + -------------\n> +........................................\n> +\n> +CREATE YOUR REPOSITORY\n> +----------------------\n> +The first step is to create your own repository. To do that you can:\n> +\n> +- a. fork (e.g. GitHub) the main project (e.g git/git), or\n> +- b. create an empty repository\n> +\n> +a. Fork the project\n> +~~~~~~~~~~~~~~~~~~~\n> +Go to the repository of the project (e.g. git/git) you want\n> +and fork it.\n\nAs I understand it one issue is to clearly suggest that it is best to fork \nand then clone from your me/fork project such that the origin and it's \nfetch/push are set up the easiest way.\n\nIf the user clones the main project before forking and then tries to add the \nme/fork there are more hoops to jump through to get all the fetch/push \nsettings re-arranged (this does depend on the Github fork method, but at \nleast the issue of which repo is cloned should be noted)\n\n> +\n> +b. Create from scratch\n> +~~~~~~~~~~~~~~~~~~~~~~\n> +Create a repository on your prefered Git repository hosting service.\n> +\n> +Clone it\n> +~~~~~~~~\n> +Clone your repository on your machine.\n> +\n> +\n> +CONFIGURE BRANCHES\n> +------------------\n> +In many projects, the branch `master` have to be pulled from\n> +the main repository(e.g. git/git) and pushed to your repository\n> +(e.g. me/git).\n> +\n> +Adding the main project remote\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> +Add a new remote (e.g. upstream):\n> +\n> +===================================\n> +`git remote add upstream `\n> +===================================\n> +\n> +Pull from upstream by default\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> +\n> +===================================\n> +`git config branch.master.remote upstream`\n> +===================================\n> +\n> +\n> +Push to origin by default\n> +~~~~~~~~~~~~~~~~~~~~~~~~~\n> +\n> +===================================\n> +`git config branch.master.pushRemote origin`\n> +===================================\n> +\n> +\n> +GET YOUR PROJECT UP TO DATE\n> +---------------------------\n> +\n> +Now that `branch.master.remote` and `branch.master.pushRemote` are\n> +set, you can use the following commands to be up to date:\n> +=====================================\n> + * `git pull`\n> + * `git push`\n> +=====================================\n> +\n> +\n> +SEE ALSO\n> +--------\n> +linkgit:git-config[1]\n> +linkgit:git-remote[1]\n> +linkgit:git-fetch[1]\n> +\n> +\n> +\n> -- \n> 2.7.4 (Apple Git-66)\n>\n> \n"},{"id":"288217","messageId":"D1C9E2B7-EA50-4D36-A77F-00BE7E693B8F@grenoble-inp.org","threadId":"42454","inReplyTo":"9FB65CA220F84B6B882B75435DDA3D65@PhilipOakley","subject":"Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation","fromName":"Jordan DE GEA","fromEmail":"jordan.de-gea@grenoble-inp.org","sentAt":"2016-06-03T09:52:22Z","receivedAt":"2016-06-03T09:52:22Z","isPatch":true,"sender":{"key":"jordan.de-gea@grenoble-inp.org","avatar":null},"body":"> From: \"Jordan DE GEA\" \n>> This document attempts to help you configure a Triangular Workflow.\n>> +Here is an example of configuration:\n>> +\n>> +........................................\n>> +------------ -----------\n>> +| UPSTREAM | maintainer | ORIGIN |\n> \n> UPSTREAM and ORIGIN are two different types of description. Origin being a too generic Git name that is used multiply elsewhere.\n> \n> That said, trying to find a good name for that 'third place' is not easy. It's neither upstream, nor downstream (for Junio - the maintainer special case - git.git would be his downstream). The me/git repo is like a ferryman's landing across the other side of the river flow, a safe harbour if you will.\n> \n> Finding a suitable name has all the same issues as deciding the generic public name for the staging area / index. The ability to have a second perfect copy is very new - historically all the dictionary names relate to copies or forgeries (you could only have one master - DVCS breaks that mould). Perhaps (poorly) \"MyFork\", or \"MyServer\". There maybe a good French word we can use.\n> \n\n\nYou’re right, finding a good name is not easy. \nFirstly, I wanted to use DOWNSTREAM and UPSTREAM. But git doesn’t make the difference between those words. \n\nLooking for the description of the third place, I wrote that it’s the remote used to push modifications. \nAssembling the main words push and remote, it creates PUSH_REMOTE which seems a good name. \ne.g. That’s clear to say \"I push to the push_remote\". \n\nAs the option `branch..pushRemote` exists, a little text has to be added in order to prevent confusion. \nBy the way, in the documentation, confusions will be avoided by using `branch..pushRemote` and ‘push_remote`.\n\nLike PUSH_REMOTE, the remote where we fetch can be called FETCH_REMOTE. \ne.g. That’s clear to say \"I fetch from fetch_remote\". \n\nDo you agree?\n\n\n> \n>> +------------ ← -----------\n>> + \\ /\n>> + \\ /\n>> + fetch↓\\ /↑push\n>> + \\ /\n>> + \\ /\n>> + -------------\n>> + | LOCAL |\n>> + -------------\n>> +........................................\n>> +\n>> +CREATE YOUR REPOSITORY\n>> +----------------------\n>> +The first step is to create your own repository. To do that you can:\n>> +\n>> +- a. fork (e.g. GitHub) the main project (e.g git/git), or\n>> +- b. create an empty repository\n>> +\n>> +a. Fork the project\n>> +~~~~~~~~~~~~~~~~~~~\n>> +Go to the repository of the project (e.g. git/git) you want\n>> +and fork it.\n> \n> As I understand it one issue is to clearly suggest that it is best to fork and then clone from your me/fork project such that the origin and it's fetch/push are set up the easiest way.\n> \n> If the user clones the main project before forking and then tries to add the me/fork there are more hoops to jump through to get all the fetch/push settings re-arranged (this does depend on the Github fork method, but at least the issue of which repo is cloned should be noted)\nThank you, I will work on it. \n"},{"id":"288224","messageId":"vpqy46my05v.fsf@anie.imag.fr","threadId":"42454","inReplyTo":"D1C9E2B7-EA50-4D36-A77F-00BE7E693B8F@grenoble-inp.org","subject":"Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2016-06-03T11:36:12Z","receivedAt":"2016-06-03T11:36:12Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Jordan DE GEA writes:\n\n> You’re right, finding a good name is not easy. \n> Firstly, I wanted to use DOWNSTREAM and UPSTREAM. But git doesn’t make the difference between those words. \n\nIn english, \"downstream\" and \"upstream\" are relative terms. If A is\nupstream compared to B, then B is downstream compared to A.\n\nIn terms of Git, you know what your upstream is (i.e. where you get\ncommits from), but you don't necessarily know what your downstream is\n(i.e. who pulls from your repository). So, \"downstream\" wouldn't make\nsense in a config file.\n\n> Like PUSH_REMOTE, the remote where we fetch can be called FETCH_REMOTE. \n> e.g. That’s clear to say \"I fetch from fetch_remote\". \n>\n> Do you agree?\n\nThat is technically correct, but to illustrate the overall flow, I'd\nrather avoid naming the repositories in terms of git commands. If you do\nso, you will probably end up with tautological explanations like this\nlater in the text: \"FETCH_REMOTE is the remote from where you fetch,\nPUSH_REMOTE is the remote to which you push, and LOCAL is local\".\n\nI suggested PUBLIC-FORK earlier, and didn't get any feedback on it. I\nthink it translates the intent better than PUSH_REMOTE. An alternative\nwould be PUBLISH (= the repository you use to publish your changes so\nthat the maintainer can pick them).\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"288226","messageId":"83EF9DDB-34AB-4E91-A516-955DA1CC7AF9@grenoble-inp.org","threadId":"42454","inReplyTo":"vpqy46my05v.fsf@anie.imag.fr","subject":"Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation","fromName":"Jordan DE GEA","fromEmail":"jordan.de-gea@grenoble-inp.org","sentAt":"2016-06-03T11:53:58Z","receivedAt":"2016-06-03T11:53:58Z","isPatch":true,"sender":{"key":"jordan.de-gea@grenoble-inp.org","avatar":null},"body":">> Like PUSH_REMOTE, the remote where we fetch can be called FETCH_REMOTE. \n>> e.g. That’s clear to say \"I fetch from fetch_remote\". \n>> \n>> Do you agree?\n> \n> That is technically correct, but to illustrate the overall flow, I'd\n> rather avoid naming the repositories in terms of git commands. If you do\n> so, you will probably end up with tautological explanations like this\n> later in the text: \"FETCH_REMOTE is the remote from where you fetch,\n> PUSH_REMOTE is the remote to which you push, and LOCAL is local\".\n> \n> I suggested PUBLIC-FORK earlier, and didn't get any feedback on it. I\n> think it translates the intent better than PUSH_REMOTE. An alternative\n> would be PUBLISH (= the repository you use to publish your changes so\n> that the maintainer can pick them).\n\nPUBLISH sounds good. I take it for the next patch. "},{"id":"288261","messageId":"xmqqd1nyqnr6.fsf@gitster.mtv.corp.google.com","threadId":"42454","inReplyTo":"9FB65CA220F84B6B882B75435DDA3D65@PhilipOakley","subject":"Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-06-03T15:46:05Z","receivedAt":"2016-06-03T15:46:05Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> That said, trying to find a good name for that 'third place' is not easy. \n> It's neither upstream, nor downstream (for Junio - the maintainer special \n> case - git.git would be his downstream). The me/git repo is like a \n> ferryman's landing across the other side of the river flow, a safe harbour \n> if you will.\n\nYou raise a good point here.\n\nTo me, the git.git public repository that everybody pulls from is\njust like me/git for everybody else. It is a place where you\npublish your work. I think the @{push} notation during its design\nphase was once called @{publish} instead.\n\nA \"downstream\" that is the opposite of \"upstream\" is not something\nyou would configure and control. They are those who call you\n\"upstream\". You know and actively configure who your \"upstream\" is\nand pull from there. You do not have direct control who are the\npeople who are pulling from you.\n\nSo in that sense, \"downstream\" exists as a concept that is just as\nvalid as \"upstream\", but unlike \"upstream\", \"downstream\" does not\nmanifest itself as something you explicitly tell Git about, either\nfrom the command line, in the remotes definition, or in the\nconfiguration files.\n"},{"id":"288340","messageId":"6C6F62CA4181453BA51BB362DAA5C0C1@PhilipOakley","threadId":"42454","inReplyTo":"xmqqd1nyqnr6.fsf@gitster.mtv.corp.google.com","subject":"Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-03T22:16:41Z","receivedAt":"2016-06-03T22:16:41Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> \"Philip Oakley\" writes:\n>\n>> That said, trying to find a good name for that 'third place' is not easy.\n>> It's neither upstream, nor downstream (for Junio - the maintainer special\n>> case - git.git would be his downstream). The me/git repo is like a\n>> ferryman's landing across the other side of the river flow, a safe \n>> harbour\n>> if you will.\n>\n> You raise a good point here.\n>\n> To me, the git.git public repository that everybody pulls from is\n> just like me/git for everybody else. It is a place where you\n> publish your work. I think the @{push} notation during its design\n> phase was once called @{publish} instead.\n\nI'd agree that your git/git is actually an @{publish} repo, and to my mind \nis a formal 'downstream' for you.\n\nHowever your gitster/git repo feels like it would match the me/git \nviewpoint, in that while it is 'open', it isn't really a formal publishing \nplace. Certainly I don't think that I 'publish' what's in my personal github \nrepos, which I use as an open backup (and any PR's I put to the G4W project \nrepo are referenced from there).\n\nI did have a look at various thesaurus words \n(//www.thesaurus.com/browse/repository) that might be usable and found:-\ndepot, haven, shelter, sanctuary, wharf, bunker, vault, which are all 'near' \nbut not quite right, if only home-depot wasn't taken I'd suggest that!\n\n>\n> A \"downstream\" that is the opposite of \"upstream\" is not something\n> you would configure and control. They are those who call you\n> \"upstream\". You know and actively configure who your \"upstream\" is\n> and pull from there. You do not have direct control who are the\n> people who are pulling from you.\n>\n> So in that sense, \"downstream\" exists as a concept that is just as\n> valid as \"upstream\", but unlike \"upstream\", \"downstream\" does not\n> manifest itself as something you explicitly tell Git about, either\n> from the command line, in the remotes definition, or in the\n> configuration files.\n\nCertainly for contributors, a configured 'downstream' repo doesn't make \nsense, but I do think it's worthwhile for maintainers, Leiutenants, and \ndictators who do have a specific publishing place. \n"},{"id":"288403","messageId":"F57B7CD2-8F8B-4D58-B145-285E69F9B4BE@grenoble-inp.org","threadId":"42454","inReplyTo":"vpqy46my05v.fsf@anie.imag.fr","subject":"Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation","fromName":"Jordan DE GEA","fromEmail":"jordan.de-gea@grenoble-inp.org","sentAt":"2016-06-05T21:28:34Z","receivedAt":"2016-06-05T21:28:34Z","isPatch":true,"sender":{"key":"jordan.de-gea@grenoble-inp.org","avatar":null},"body":"\n> Matthieu Moy a écrit :\n> \n> That is technically correct, but to illustrate the overall flow, I'd\n> rather avoid naming the repositories in terms of git commands. If you do\n> so, you will probably end up with tautological explanations like this\n> later in the text: \"FETCH_REMOTE is the remote from where you fetch,\n> PUSH_REMOTE is the remote to which you push, and LOCAL is local\".\n> \n> I suggested PUBLIC-FORK earlier, and didn't get any feedback on it. I\n> think it translates the intent better than PUSH_REMOTE. An alternative\n> would be PUBLISH (= the repository you use to publish your changes so\n> that the maintainer can pick them).\n\n> \"Philip Oakley\" writes:\n> However your gitster/git repo feels like it would match the me/git viewpoint, in that while it is 'open', it isn't really a formal publishing place. Certainly I don't think that I 'publish' what's in my personal github repos, which I use as an open backup (and any PR's I put to the G4W project repo are referenced from there).\n\n\nFor Philip Oakley, PUBLISH seems to not be a good name. \nFor PUBLIC-FORK, a fork can be private so I think that’s not a good idea. \n\nAs the third-place is the repository used to work on commits/patches, \na simple name can be WORK_REPOSITORY. "},{"id":"288408","messageId":"vpq7fe2rbno.fsf@anie.imag.fr","threadId":"42454","inReplyTo":"F57B7CD2-8F8B-4D58-B145-285E69F9B4BE@grenoble-inp.org","subject":"Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2016-06-06T07:58:51Z","receivedAt":"2016-06-06T07:58:51Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Jordan DE GEA writes:\n\n>> Matthieu Moy a écrit :\n>> \n>> That is technically correct, but to illustrate the overall flow, I'd\n>> rather avoid naming the repositories in terms of git commands. If you do\n>> so, you will probably end up with tautological explanations like this\n>> later in the text: \"FETCH_REMOTE is the remote from where you fetch,\n>> PUSH_REMOTE is the remote to which you push, and LOCAL is local\".\n>> \n>> I suggested PUBLIC-FORK earlier, and didn't get any feedback on it. I\n>> think it translates the intent better than PUSH_REMOTE. An alternative\n>> would be PUBLISH (= the repository you use to publish your changes so\n>> that the maintainer can pick them).\n>\n>> \"Philip Oakley\" writes:\n>> However your gitster/git repo feels like it would match the me/git\n>> viewpoint, in that while it is 'open', it isn't really a formal\n>> publishing place. Certainly I don't think that I 'publish' what's in\n>> my personal github repos, which I use as an open backup (and any\n>> PR's I put to the G4W project repo are referenced from there).\n>\n>\n> For Philip Oakley, PUBLISH seems to not be a good name. \n> For PUBLIC-FORK, a fork can be private so I think that’s not a good idea. \n\nI don't think you will find a name that fits all use-cases. IHMO, best\nis to pick one rather general use-case, make the explanations for it,\nand maybe explain somewhere that there are variants.\n\nIf the fork is completely private, then your diagram with a \"maintainer\"\narrow from it to upstream is not valid. It needs at least to be visible\nto the maintainer. \"public\" may be a bit strong as you don't need to\nmake it \"public\" to everyone on earth, but to me that's OK to describe\nthe use-case.\n\n> As the third-place is the repository used to work on commits/patches, \n> a simple name can be WORK_REPOSITORY.\n\n\"WORK\" is already used to describe \"worktree\" which is precisely not\nthis repository. I don't \"work\" on my public fork, I \"work\" locally and\nthen just send commits there.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"288410","messageId":"1465206518-1780-1-git-send-email-jordan.de-gea@grenoble-inp.org","threadId":"42454","inReplyTo":"1464697717-5751-1-git-send-email-jordan.de-gea@grenoble-inp.org","subject":"[RFC/PATCHv2] Documentation: triangular workflow","fromName":"Jordan DE GEA","fromEmail":"jordan.de-gea@grenoble-inp.org","sentAt":"2016-06-06T09:48:37Z","receivedAt":"2016-06-06T09:48:37Z","isPatch":false,"sender":{"key":"jordan.de-gea@grenoble-inp.org","avatar":null},"body":"Currently, triangular workflow can be configured, but there is no\ndocumentation about it. A documentation is useful to keep\nconfiguration possibilities up-to-date.\n\nA new subsection is created in gitworkflow.\n\nSigned-off-by: Michael Haggerty \nSigned-off-by: Matthieu Moy \nSigned-off-by: Jordan DE GEA \n---\n\nChanges since version 1:\n - content moved in gitworktree\n - content improved\n\n Documentation/gitworkflows.txt | 155 +++++++++++++++++++++++++++++++++++++++++\n 1 file changed, 155 insertions(+)\n\ndiff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\nindex f16c414..cd77893 100644\n--- a/Documentation/gitworkflows.txt\n+++ b/Documentation/gitworkflows.txt\n@@ -463,6 +463,157 @@ if you get conflicts: `git am -3` will use index information contained\n in patches to figure out the merge base. See linkgit:git-am[1] for\n other options.\n \n+TRIANGULAR WORKFLOW\n+-------------------\n+\n+In some projects, you cannot push directly to the project but have to\n+suggest your 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+- Taking the last version of the project by fetching (e.g.\n+ **UPSTREAM**)\n+- Writing modifications and push them to a fork (e.g. **PUBLIC-FORK**)\n+- Opening a pull request\n+- Checking of changes by the maintainer and, merging them into the\n+ **UPSTREAM** repository if accepted\n+\n+\n+........................................\n+------------------ -----------------\n+| UPSTREAM | maintainer | PUBLIC-FORK |\n+| git/git |- - - - - - - -| me/remote |\n+------------------ ← -----------------\n+ \\ /\n+ \\ /\n+ fetch↓\\ /↑push\n+ \\ /\n+ \\ /\n+ -------------\n+ | LOCAL |\n+ -------------\n+........................................\n+\n+Git options to use:\n+~~~~~~~~~~~~~~~~~~~\n+ - `branch..remote`\n+ - `branch..pushRemote`\n+ - `remote.pushDefault`\n+ - `push.default`\n+\n+See linkgit:git-config[1].\n+\n+Push behaviour\n+~~~~~~~~~~~~~~\n+\n+Setting the behavior of push for the triangular workflow:\n+\n+===========================\n+* `git config push.default current`\n+===========================\n+\n+\n+Case 1: LOCAL is a clone of **PUBLIC-FORK**\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+'In this case, the remote named `origin` corresponds to **PUBLIC-FORK**.'\n+\n+Adding **UPSTREAM** remote:\n+\n+===================================\n+* `git remote add upstream `\n+===================================\n+\n+Setting `branch..remote` and `branch..pushRemote` in\n+order to:\n+\n+ - pull from **UPSTREAM** without argument for pull\n+ - push to **PUBLIC-FORK** (`origin`) without argument for push\n+\n+Example with master as :\n+===================================\n+* `git config branch.master.remote upstream`\n+* `git config branch.master.pushRemote origin`\n+===================================\n+\n+Case 2: LOCAL is a clone of **UPSTREAM**\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+'In this case, the remote named `origin` corresponds to\n+**UPSTREAM**.'\n+\n+Adding **PUBLIC-FORK** remote:\n+\n+===================================\n+* `git remote add public_fork `\n+===================================\n+\n+**Method 1: One option for all branches**\n+\n+Setting `remote.pushDefault` in order to push to **PUBLIC-FORK** without\n+argument for push.\n+\n+===================================\n+* `git config remote.pushDefault public_fork`\n+===================================\n+\n+**Method 2: Each branch its option**\n+\n+Setting `branch..pushRemote` in order to push to **PUBLIC-FORK**\n+without argument to push.\n+\n+Example with master as :\n+===================================\n+* `git config branch.master.pushRemote public_fork`\n+===================================\n+\n+\n+Stay up-to-date\n+~~~~~~~~~~~~~~~\n+\n+Retrieving updates from **UPSTREAM** with `git pull` and sending\n+them to **PUBLIC-FORK** with `git push`.\n+\n+Checks\n+~~~~~~\n+\n+Uses of command line shorthand `@{push}` and `@{upstream}`.\n+\n+**Display the push remote's name: **\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+See linkgit:git-rev-parse[1].\n+\n+**Display the fetch remote's name: **\n+\n+===================================\n+* `git rev-parse --abbrev-ref '@{upstream}'`\n+===================================\n+\n+The shorthand \"@{upstream}\" substitutes the name of the\n+\"upstream\" of 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+\n+===============\n+* `git log @{push}..`\n+===============\n+\n+See linkgit:git-log[1].\n+\n+**Display commits added to a specific branch since last push: **\n+\n+==============================\n+* `git log @{push}..`\n+==============================\n \n SEE ALSO\n --------\n@@ -474,6 +625,10 @@ linkgit:git-rebase[1],\n linkgit:git-format-patch[1],\n linkgit:git-send-email[1],\n linkgit:git-am[1]\n+linkgit:git-config[1],\n+linkgit:git-log[1],\n+linkgit:git-rev-parse[1]\n+\n \n GIT\n ---\n-- \n2.7.4 (Apple Git-66)\n"},{"id":"288457","messageId":"A8FD6EF510F149A4A05FE553BEDD8511@PhilipOakley","threadId":"42454","inReplyTo":"vpq7fe2rbno.fsf@anie.imag.fr","subject":"Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-06T16:46:27Z","receivedAt":"2016-06-06T16:46:27Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Matthieu Moy\" \n> Jordan DE GEA writes:\n>\n>>> Matthieu Moy a écrit :\n>>>\n>>> That is technically correct, but to illustrate the overall flow, I'd\n>>> rather avoid naming the repositories in terms of git commands. If you do\n>>> so, you will probably end up with tautological explanations like this\n>>> later in the text: \"FETCH_REMOTE is the remote from where you fetch,\n>>> PUSH_REMOTE is the remote to which you push, and LOCAL is local\".\n>>>\n>>> I suggested PUBLIC-FORK earlier, and didn't get any feedback on it. I\n>>> think it translates the intent better than PUSH_REMOTE. An alternative\n>>> would be PUBLISH (= the repository you use to publish your changes so\n>>> that the maintainer can pick them).\n>>\n>>> \"Philip Oakley\" writes:\n>>> However your gitster/git repo feels like it would match the me/git\n>>> viewpoint, in that while it is 'open', it isn't really a formal\n>>> publishing place. Certainly I don't think that I 'publish' what's in\n>>> my personal github repos, which I use as an open backup (and any\n>>> PR's I put to the G4W project repo are referenced from there).\n>>\n>>\n>> For Philip Oakley, PUBLISH seems to not be a good name.\n>> For PUBLIC-FORK, a fork can be private so I think that’s not a good idea.\n>\n> I don't think you will find a name that fits all use-cases. IHMO, best\n> is to pick one rather general use-case, make the explanations for it,\n> and maybe explain somewhere that there are variants.\n>\n> If the fork is completely private, then your diagram with a \"maintainer\"\n> arrow from it to upstream is not valid.\n\nThat's only true for a Pull Request workflow. For a Patch workflow (such as \nGit) the user's home vault can be completely private.\n\n> It needs at least to be visible\n> to the maintainer. \"public\" may be a bit strong as you don't need to\n> make it \"public\" to everyone on earth, but to me that's OK to describe\n> the use-case.\n>\n>> As the third-place is the repository used to work on commits/patches,\n>> a simple name can be WORK_REPOSITORY.\n>\n> \"WORK\" is already used to describe \"worktree\" which is precisely not\n> this repository. I don't \"work\" on my public fork, I \"work\" locally and\n> then just send commits there.\n>\n> -- \n> Matthieu Moy\n> http://www-verimag.imag.fr/~moy/\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n> \n"},{"id":"288459","messageId":"vpqporucl6g.fsf@anie.imag.fr","threadId":"42454","inReplyTo":"A8FD6EF510F149A4A05FE553BEDD8511@PhilipOakley","subject":"Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2016-06-06T16:54:31Z","receivedAt":"2016-06-06T16:54:31Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"\"Philip Oakley\" writes:\n\n> From: \"Matthieu Moy\" \n>>\n>> I don't think you will find a name that fits all use-cases. IHMO, best\n>> is to pick one rather general use-case, make the explanations for it,\n>> and maybe explain somewhere that there are variants.\n>>\n>> If the fork is completely private, then your diagram with a \"maintainer\"\n>> arrow from it to upstream is not valid.\n>\n> That's only true for a Pull Request workflow. For a Patch workflow\n> (such as Git) the user's home vault can be completely private.\n\nBut then the maintainer is not the one picking changes from it (you're\nsending them by email), so the \"maintainer\" label is not really accurate\nin the diagram:\n\n+------------ -----------\n+| UPSTREAM | maintainer | ORIGIN |\n+| git/git |- - - - - - - -| me/git |\n+------------ ← -----------\n+ \\ /\n+ \\ /\n+ fetch↓\\ /↑push\n+ \\ /\n+ \\ /\n+ -------------\n+ | LOCAL |\n+ -------------\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"288474","messageId":"0B6B083EAEAA4E428C26CDAFE56E2FF6@PhilipOakley","threadId":"42454","inReplyTo":"vpqporucl6g.fsf@anie.imag.fr","subject":"Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-06T19:21:57Z","receivedAt":"2016-06-06T19:21:57Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Matthieu Moy\" \n> \"Philip Oakley\" writes:\n>\n>> From: \"Matthieu Moy\" \n>>>\n>>> I don't think you will find a name that fits all use-cases. IHMO, best\n>>> is to pick one rather general use-case, make the explanations for it,\n>>> and maybe explain somewhere that there are variants.\n>>>\n>>> If the fork is completely private, then your diagram with a \"maintainer\"\n>>> arrow from it to upstream is not valid.\n>>\n>> That's only true for a Pull Request workflow. For a Patch workflow\n>> (such as Git) the user's home vault can be completely private.\n>\n> But then the maintainer is not the one picking changes from it (you're\n> sending them by email), so the \"maintainer\" label is not really accurate\n> in the diagram:\n>\n> +------------ -----------\n> +| UPSTREAM | maintainer | ORIGIN |\n> +| git/git |- - - - - - - -| me/git |\n> +------------ ← -----------\n> + \\ /\n> + \\ /\n> + fetch↓\\ /↑push\n> + \\ /\n> + \\ /\n> + -------------\n> + | LOCAL |\n> + -------------\n>\nAhh, that's a useful clarification. I use my git repo both for the G4W \n(which does take pull requests) and for Junio's Git.\n\nThe use of the 'home-vault' fork as being for\n(a) backup,\n(b) open viewing, and\n(c) sending pull requests\nare subtle distinctions for the naming (of both the forked repo, and the \nworkflow).\n\nIt's probably even worse in a corporate environment as to how personal the \npersonal home vault is, as compared to just having a namespace in a \ncentralised dev server/repo. (the question of how to make such arrangements \nseems to come up moderately often on the various lists)\n\nPhilip \n"},{"id":"288475","messageId":"xmqqk2i2w288.fsf@gitster.mtv.corp.google.com","threadId":"42454","inReplyTo":"1465206518-1780-1-git-send-email-jordan.de-gea@grenoble-inp.org","subject":"Re: [RFC/PATCHv2] Documentation: triangular workflow","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-06-06T19:23:35Z","receivedAt":"2016-06-06T19:23:35Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jordan DE GEA writes:\n\n> +TRIANGULAR WORKFLOW\n> +-------------------\n> +\n> +In some projects, you cannot push directly to the project but have to\n> +suggest your 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> +- Taking the last version of the project by fetching (e.g.\n> + **UPSTREAM**)\n> +- Writing modifications and push them to a fork (e.g. **PUBLIC-FORK**)\n> +- Opening a pull request\n> +- Checking of changes by the maintainer and, merging them into the\n> + **UPSTREAM** repository if accepted\n> +\n> +\n> +........................................\n> +------------------ -----------------\n> +| UPSTREAM | maintainer | PUBLIC-FORK |\n> +| git/git |- - - - - - - -| me/remote |\n> +------------------ ← -----------------\n> + \\ /\n> + \\ /\n> + fetch↓\\ /↑push\n> + \\ /\n> + \\ /\n> + -------------\n> + | LOCAL |\n> + -------------\n> +........................................\n\nI agree with other commenters that \"PUBLIC-FORK\" is a name that does\nnot capture the essense of the triangular being the next step\nforward, compared to the \"central shared repository\" workflow, to\ntake advantage of the distributed nature of Git.\n\n\"Where you push so that somebody else can fetch from there\" does not\nhave to be public. You may be submitting a course assignment there,\nonly to be seen by your professor but not by others in the class.\nAlso, you do not your call \"LOCAL\" a \"LOCAL-FORK\" and that is a good\nthing. In a distributed world, everything is a fork, so adding\n\"-FORK\" to a name is pretty much meaningless.\n\nSo neither \"PUBLIC\" nor \"FORK\" in \"PUBLIC-FORK\" is a good word to\ndescribe this thing.\n\nThe only reason you are pushing there is because your \"LOCAL\" is\neither not accessible from outside world, and/or you do not want to\ngive a direct access to it (otherwise you could have allowed an\naccess to whoever is going to fetch from you direct access to\n\"LOCAL\" and be done with it without creating \"PUBLIC-FORK\").\n\nThat is why I reminded that we earlier in the design phase called\nthis \"publish\"; it is a place you give access to others a selected\nwork of yours that you choose to give them access to. Whether you\nare a leaf contributor, a student who got stuck and wants to ask\nsuggestions from your friends after looking your code over, or an\nintegrator of a big public project, I would view the act to push\ninto such a place you give selective visibility to your work to\nothers as publishing your work.\n"},{"id":"288489","messageId":"12C5A5F1276946DC99A03F30FEE49559@PhilipOakley","threadId":"42454","inReplyTo":"xmqqk2i2w288.fsf@gitster.mtv.corp.google.com","subject":"Re: [RFC/PATCHv2] Documentation: triangular workflow","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-06T22:21:14Z","receivedAt":"2016-06-06T22:21:14Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Jordan DE GEA writes:\n>\n>> +TRIANGULAR WORKFLOW\n>> +-------------------\n>> +\n>> +In some projects, you cannot push directly to the project but have to\n>> +suggest your 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>> +- Taking the last version of the project by fetching (e.g.\n>> + **UPSTREAM**)\n>> +- Writing modifications and push them to a fork (e.g. **PUBLIC-FORK**)\n>> +- Opening a pull request\n>> +- Checking of changes by the maintainer and, merging them into the\n>> + **UPSTREAM** repository if accepted\n>> +\n>> +\n>> +........................................\n>> +------------------ -----------------\n>> +| UPSTREAM | maintainer | PUBLIC-FORK |\n>> +| git/git |- - - - - - - -| me/remote |\n>> +------------------ ← -----------------\n>> + \\ /\n>> + \\ /\n>> + fetch↓\\ /↑push\n>> + \\ /\n>> + \\ /\n>> + -------------\n>> + | LOCAL |\n>> + -------------\n>> +........................................\n>\n> I agree with other commenters that \"PUBLIC-FORK\" is a name that does\n> not capture the essense of the triangular being the next step\n> forward, compared to the \"central shared repository\" workflow, to\n> take advantage of the distributed nature of Git.\n>\n> \"Where you push so that somebody else can fetch from there\" does not\n> have to be public. You may be submitting a course assignment there,\n> only to be seen by your professor but not by others in the class.\n> Also, you do not your call \"LOCAL\" a \"LOCAL-FORK\" and that is a good\n> thing. In a distributed world, everything is a fork, so adding\n> \"-FORK\" to a name is pretty much meaningless.\n>\n> So neither \"PUBLIC\" nor \"FORK\" in \"PUBLIC-FORK\" is a good word to\n> describe this thing.\n>\n> The only reason you are pushing there is because your \"LOCAL\" is\n> either not accessible from outside world, and/or you do not want to\n> give a direct access to it (otherwise you could have allowed an\n> access to whoever is going to fetch from you direct access to\n> \"LOCAL\" and be done with it without creating \"PUBLIC-FORK\").\n>\n> That is why I reminded that we earlier in the design phase called\n> this \"publish\"; it is a place you give access to others a selected\n> work of yours that you choose to give them access to.\n\nGiven that clarification I'd be happier to go with it being one's 'Publish' \nrepo.\n\nMy initial reticence was because of the association of \"publish\" with vanity \npublishing and other forms of over-sharing and self promotion.\n\nA clarification/explanation that calling it a 'publish' repo is about \ngranting access, and possible open access, would make it more acceptable.\n\n> Whether you\n> are a leaf contributor, a student who got stuck and wants to ask\n> suggestions from your friends after looking your code over, or an\n> integrator of a big public project, I would view the act to push\n> into such a place you give selective visibility to your work to\n> others as publishing your work.\n\nAgreed, in that context.\n\n--\nPhilip \n"},{"id":"288526","messageId":"vpqziqxbi3d.fsf@anie.imag.fr","threadId":"42454","inReplyTo":"12C5A5F1276946DC99A03F30FEE49559@PhilipOakley","subject":"Re: [RFC/PATCHv2] Documentation: triangular workflow","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2016-06-07T06:58:46Z","receivedAt":"2016-06-07T06:58:46Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"\"Philip Oakley\" writes:\n\n> Given that clarification I'd be happier to go with it being one's\n> 'Publish' repo.\n>\n> My initial reticence was because of the association of \"publish\" with\n> vanity publishing and other forms of over-sharing and self promotion.\n>\n> A clarification/explanation that calling it a 'publish' repo is about\n> granting access, and possible open access, would make it more\n> acceptable.\n\nI think \"publish\" is the best we found up to now.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"288527","messageId":"vpqportbhw4.fsf@anie.imag.fr","threadId":"42454","inReplyTo":"0B6B083EAEAA4E428C26CDAFE56E2FF6@PhilipOakley","subject":"Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2016-06-07T07:03:07Z","receivedAt":"2016-06-07T07:03:07Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"\"Philip Oakley\" writes:\n\n> From: \"Matthieu Moy\" \n>\n>> But then the maintainer is not the one picking changes from it (you're\n>> sending them by email), so the \"maintainer\" label is not really accurate\n>> in the diagram:\n>>\n>> +------------ -----------\n>> +| UPSTREAM | maintainer | ORIGIN |\n>> +| git/git |- - - - - - - -| me/git |\n>> +------------ ← -----------\n>> + \\ /\n>> + \\ /\n>> + fetch↓\\ /↑push\n>> + \\ /\n>> + \\ /\n>> + -------------\n>> + | LOCAL |\n>> + -------------\n>>\n> Ahh, that's a useful clarification. I use my git repo both for the G4W\n> (which does take pull requests) and for Junio's Git.\n>\n> The use of the 'home-vault' fork as being for\n> (a) backup,\n> (b) open viewing, and\n> (c) sending pull requests\n> are subtle distinctions for the naming (of both the forked repo, and\n> the workflow).\n>\n> It's probably even worse in a corporate environment as to how personal\n> the personal home vault is, as compared to just having a namespace in\n> a centralised dev server/repo. (the question of how to make such\n> arrangements seems to come up moderately often on the various lists)\n\nYes, but again, the point of this thread is to document *one* workflow,\nnot all possible uses of pushRemote. It's much easier to describe \"one\ntypical triangular workflow\" in a concrete way than to try to be\ncompletely general and end up with a description that average users\nwould just not understand.\n\nIt would be different to me if we were writting the pushRemote part of\nconfig.txt, where we have to be as general as possible.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"288533","messageId":"9DE343E5-99FE-4504-AA62-5647FBD76F27@grenoble-inp.org","threadId":"42454","inReplyTo":"vpqziqxbi3d.fsf@anie.imag.fr","subject":"Re: [RFC/PATCHv2] Documentation: triangular workflow","fromName":"Jordan DE GEA","fromEmail":"jordan.de-gea@grenoble-inp.org","sentAt":"2016-06-07T08:02:43Z","receivedAt":"2016-06-07T08:02:43Z","isPatch":false,"sender":{"key":"jordan.de-gea@grenoble-inp.org","avatar":null},"body":"> Le 7 juin 2016 à 08:58, Matthieu Moy a écrit :\n> \n> \"Philip Oakley\" writes:\n> \n>> Given that clarification I'd be happier to go with it being one's\n>> 'Publish' repo.\n>> \n>> My initial reticence was because of the association of \"publish\" with\n>> vanity publishing and other forms of over-sharing and self promotion.\n>> \n>> A clarification/explanation that calling it a 'publish' repo is about\n>> granting access, and possible open access, would make it more\n>> acceptable.\n> \n> I think \"publish\" is the best we found up to now.\n> \n\nIt seems that we choose ‘publish’. \nI’ll send the v3 of the patch soon. "},{"id":"288536","messageId":"1465288693-6295-1-git-send-email-jordan.de-gea@grenoble-inp.org","threadId":"42454","inReplyTo":"1465206518-1780-1-git-send-email-jordan.de-gea@grenoble-inp.org","subject":"[PATCHv3] Documentation: triangular workflow","fromName":"Jordan DE GEA","fromEmail":"jordan.de-gea@grenoble-inp.org","sentAt":"2016-06-07T08:38:13Z","receivedAt":"2016-06-07T08:38:13Z","isPatch":false,"sender":{"key":"jordan.de-gea@grenoble-inp.org","avatar":null},"body":"Currently, triangular workflow can be configured, but there is no\ndocumentation about it. A documentation is useful to keep\nconfiguration possibilities up-to-date.\n\nA new subsection is created in gitworkflow.\n\nSigned-off-by: Michael Haggerty \nSigned-off-by: Matthieu Moy \nSigned-off-by: Jordan DE GEA \n---\nChanges since version 2:\n - PUBLIC-FORK renamed for PUBLISH\n\nChanges since version 1:\n - content moved in gitworktree\n - content improved\n\n Documentation/gitworkflows.txt | 154 +++++++++++++++++++++++++++++++++++++++++\n 1 file changed, 154 insertions(+)\n\ndiff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\nindex f16c414..3b5fd09 100644\n--- a/Documentation/gitworkflows.txt\n+++ b/Documentation/gitworkflows.txt\n@@ -463,6 +463,156 @@ if you get conflicts: `git am -3` will use index information contained\n in patches to figure out the merge base. See linkgit:git-am[1] for\n other options.\n \n+TRIANGULAR WORKFLOW\n+-------------------\n+\n+In some projects, you cannot push directly to the project but have to\n+suggest your 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+- Taking the last version of the project by fetching (e.g.\n+ **UPSTREAM**)\n+- Writing modifications and push them to a fork (e.g. **PUBLISH**)\n+- Opening a pull request\n+- Checking of changes by the maintainer and, merging them into the\n+ **UPSTREAM** repository if accepted\n+\n+\n+........................................\n+------------------ -----------------\n+| UPSTREAM | maintainer | PUBLISH |\n+| git/git |- - - - - - - -| me/remote |\n+------------------ ← -----------------\n+ \\ /\n+ \\ /\n+ fetch↓\\ /↑push\n+ \\ /\n+ \\ /\n+ -------------\n+ | LOCAL |\n+ -------------\n+........................................\n+\n+Git options to use:\n+~~~~~~~~~~~~~~~~~~~\n+ - `branch..remote`\n+ - `branch..pushRemote`\n+ - `remote.pushDefault`\n+ - `push.default`\n+\n+See linkgit:git-config[1].\n+\n+Push behaviour\n+~~~~~~~~~~~~~~\n+\n+Setting the behavior of push for the triangular workflow:\n+\n+===========================\n+* `git config push.default current`\n+===========================\n+\n+\n+Case 1: LOCAL is a clone of **PUBLISH**\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+'In this case, the remote named `origin` corresponds to **PUBLISH**.'\n+\n+Adding **UPSTREAM** remote:\n+\n+===================================\n+* `git remote add upstream `\n+===================================\n+\n+Setting `branch..remote` and `branch..pushRemote` in\n+order to:\n+\n+ - pull from **UPSTREAM** without argument for pull\n+ - push to **PUBLISH** (`origin`) without argument for push\n+\n+Example with master as :\n+===================================\n+* `git config branch.master.remote upstream`\n+* `git config branch.master.pushRemote origin`\n+===================================\n+\n+Case 2: LOCAL is a clone of **UPSTREAM**\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+'In this case, the remote named `origin` corresponds to **UPSTREAM**.'\n+\n+Adding **PUBLISH** remote:\n+\n+===================================\n+* `git remote add publish `\n+===================================\n+\n+**Method 1: One option for all branches**\n+\n+Setting `remote.pushDefault` in order to push to **PUBLISH** without\n+argument for push.\n+\n+===================================\n+* `git config remote.pushDefault publish`\n+===================================\n+\n+**Method 2: Each branch its option**\n+\n+Setting `branch..pushRemote` in order to push to **PUBLISH**\n+without argument to push.\n+\n+Example with master as :\n+===================================\n+* `git config branch.master.pushRemote publish`\n+===================================\n+\n+\n+Stay up-to-date\n+~~~~~~~~~~~~~~~\n+\n+Retrieving updates from **UPSTREAM** with `git pull` and sending\n+them to **PUBLISH** with `git push`.\n+\n+Checks\n+~~~~~~\n+\n+Uses of command line shorthand `@{push}` and `@{upstream}`.\n+\n+**Display the push remote's name: **\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+See linkgit:git-rev-parse[1].\n+\n+**Display the fetch remote's name: **\n+\n+===================================\n+* `git rev-parse --abbrev-ref '@{upstream}'`\n+===================================\n+\n+The shorthand \"@{upstream}\" substitutes the name of the\n+\"upstream\" of 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+\n+===============\n+* `git log @{push}..`\n+===============\n+\n+See linkgit:git-log[1].\n+\n+**Display commits added to a specific branch since last push: **\n+\n+==============================\n+* `git log @{push}..`\n+==============================\n \n SEE ALSO\n --------\n@@ -474,6 +624,10 @@ linkgit:git-rebase[1],\n linkgit:git-format-patch[1],\n linkgit:git-send-email[1],\n linkgit:git-am[1]\n+linkgit:git-config[1],\n+linkgit:git-log[1],\n+linkgit:git-rev-parse[1]\n+\n \n GIT\n ---\n-- \n2.7.4 (Apple Git-66)\n"},{"id":"288629","messageId":"xmqqr3c8q0d5.fsf@gitster.mtv.corp.google.com","threadId":"42454","inReplyTo":"1465288693-6295-1-git-send-email-jordan.de-gea@grenoble-inp.org","subject":"Re: [PATCHv3] Documentation: triangular workflow","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-06-07T19:12:38Z","receivedAt":"2016-06-07T19:12:38Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jordan DE GEA writes:\n\n> diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\n> index f16c414..3b5fd09 100644\n> --- a/Documentation/gitworkflows.txt\n> +++ b/Documentation/gitworkflows.txt\n> @@ -463,6 +463,156 @@ if you get conflicts: `git am -3` will use index information contained\n> in patches to figure out the merge base. See linkgit:git-am[1] for\n> other options.\n> \n> +TRIANGULAR WORKFLOW\n> +-------------------\n> +\n> +In some projects, you cannot push directly to the project but have to\n> +suggest your 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> +- Taking the last version of the project by fetching (e.g.\n> + **UPSTREAM**)\n\n\"by fetching (e.g. UPSTREAM)\" does not finish the sentence nicely.\n\n\"... by fetching from **UPSTREAM**\" would work better. So would\n\"Fetching the latest version from the project (e.g. UPSTREAM)\".\n\n> +- Writing modifications and push them to a fork (e.g. **PUBLISH**)\n> +- Opening a pull request\n> +- Checking of changes by the maintainer and, merging them into the\n> + **UPSTREAM** repository if accepted\n\nYou'd want to end these sentences with full-stop, by the way\n\n> +........................................\n> +------------------ -----------------\n> +| UPSTREAM | maintainer | PUBLISH |\n> +| git/git |- - - - - - - -| me/remote |\n> +------------------ ← -----------------\n> + \\ /\n> + \\ /\n> + fetch↓\\ /↑push\n> + \\ /\n> + \\ /\n> + -------------\n> + | LOCAL |\n> + -------------\n> +........................................\n> +\n> +Git options to use:\n> +~~~~~~~~~~~~~~~~~~~\n> + - `branch..remote`\n> + - `branch..pushRemote`\n> + - `remote.pushDefault`\n> + - `push.default`\n> +\n> +See linkgit:git-config[1].\n\nThe title says \"options\" but listed are configuration variables and\nthe referred document is also about git-config. Perhaps retitle it to\n\n\tUseful configuration variables\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nor something like that?\n\nOne thing after reading the above lines that immediately came to my\nmind was this:\n\n After listing these four and telling the reader to \"See ...\", is\n there anything else the reader needs to learn from below?\n\nIt may make the result a lot more useful document if this gives an\nimpression to the reader as if you are saying (you do not have to\nactually say it) \"We will guide you how to set up your workflow in\ntriangular way, and here are the key configuration variables you\nwill end up using; don't worry about the details of them, we'll\nteach you all about them soon in the following paragraphs.\"\n\nAnd I found that \"See linkgit:git-config[1]\" go directly against\nthat line of narrative.\n\n> +Push behaviour\n> +~~~~~~~~~~~~~~\n> + ...\n> +\n> +Case 2: LOCAL is a clone of **UPSTREAM**\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> +\n> +'In this case, the remote named `origin` corresponds to **UPSTREAM**.'\n> +\n> +Adding **PUBLISH** remote:\n> +\n> +===================================\n> +* `git remote add publish `\n> +===================================\n\nIt may perhaps be only me, but these blind instructions puts me off,\nand what I find lacking is \"Why should I do this?\" \"What benefit do\nI get by doing this\". Start it perhaps like this?\n\n\tBecause you will be pushing into the publish repository\n\toften, instead of having to type its URL every time, you\n\twant a short name you can use to call it.\n\nand then give that \"remote add\".\n\n> +\n> +**Method 1: One option for all branches**\n> +\n> +Setting `remote.pushDefault` in order to push to **PUBLISH** without\n> +argument for push.\n> +\n> +===================================\n> +* `git config remote.pushDefault publish`\n> +===================================\n\nThis is not too bad, but I'd say\n\n\tWith the \"remote add\" above, you can say \"git push publish\"\n\tto push there, instead of saying its URL. But you may want\n\tto be even lazier and say just \"git push\". To do so:\n\nAs a document that is geared toward being a tutorial, I personally\nthink it is better to stick to one arrangement rather than\npresenting case 1/2 as two equivalently valid arrangements and\ndescribe them to equal degree of detail. Otherwise, after finishing\nreading Case 1 and immediately reading Case 2 heading, the reader\nwould start wondering \"Which one should I pick? What are the pros\nand cons?\".\n\nA typical reader of this document would have an upstream in mind,\nperhaps a clone of it locally, and may or may not yet have a publish\nrepository, so one valid choice could be to use Case 2.\n\nWhichever one you choose, the description should not begin with\n\"pushing\". A reader who is the target of this document (i.e. who\nowns the LOCAL and PUBLISH repository) begins by cloning and/or\nfetching, followed by working on her own change while staying up to\ndate, and pushing is the last thing she does in the flow.\n\nSo I'd recommend reordering the description to\n\n * Introduction. As a summary, here are the four configuration\n variables you'll be using to make it easier to arrange.\n\n * \"Preparation\". Clone from the upstream, create an empty\n publish repository and set it as a secondary remote, with\n pushdefault pointing at it.\n\n * \"Staying up-to-date\". You do not have to describe \"git fetch\"\n or \"git pull\" from the upstream aka origin with too much\n detail, as having or not having a publish repository does not\n change anything on this side.\n\n * \"Making your work available\". You would want to reiterate the\n fact that \"git push\" does not go to the upstream but to your\n publishing place thanks to the earlier pushdefault\n configuration.\n\n * \"Alternatively...\". In this section, you could mention\n possible other arrangements. One could be to set pushdefault\n for each and every branch (aka your Case 2/Method 2), which\n shouldn't be necesssary because at the beginning of the\n document we made it clear that we assume that the reader\n cannot push to upstream--the normal place she would be pushing\n is to her own publishing place, and configuring \"usually all\n of them go to my publishing place, but this one alone will go\n someplace else\" (1) is an advanced workflow element, and more\n importantly (2) is not specific to triangular workflow.\n\n Another altenative arrangement worth mentioning may be your\n Case 1, i.e. to point at your publish place and a secondary\n \"upstream\" pointing at where your upstream publishes their\n work. You can describe what needs to be changed compared to\n the above three sections.\n\nso that a first-time reader can learn _one_ workable organization\nquickly without having to choose blindly between many choices.\n\nThanks.\n"},{"id":"288642","messageId":"23D20F2F153B453D8EB5F6B3033911B5@PhilipOakley","threadId":"42454","inReplyTo":"vpqportbhw4.fsf@anie.imag.fr","subject":"Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-07T20:08:39Z","receivedAt":"2016-06-07T20:08:39Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Matthieu Moy\" \n> \"Philip Oakley\" writes:\n>\n>> From: \"Matthieu Moy\" \n>>\n>>> But then the maintainer is not the one picking changes from it (you're\n>>> sending them by email), so the \"maintainer\" label is not really accurate\n>>> in the diagram:\n>>>\n>>> +------------ -----------\n>>> +| UPSTREAM | maintainer | ORIGIN |\n>>> +| git/git |- - - - - - - -| me/git |\n>>> +------------ ← -----------\n>>> + \\ /\n>>> + \\ /\n>>> + fetch↓\\ /↑push\n>>> + \\ /\n>>> + \\ /\n>>> + -------------\n>>> + | LOCAL |\n>>> + -------------\n>>>\n>> Ahh, that's a useful clarification. I use my git repo both for the G4W\n>> (which does take pull requests) and for Junio's Git.\n>>\n>> The use of the 'home-vault' fork as being for\n>> (a) backup,\n>> (b) open viewing, and\n>> (c) sending pull requests\n>> are subtle distinctions for the naming (of both the forked repo, and\n>> the workflow).\n>>\n>> It's probably even worse in a corporate environment as to how personal\n>> the personal home vault is, as compared to just having a namespace in\n>> a centralised dev server/repo. (the question of how to make such\n>> arrangements seems to come up moderately often on the various lists)\n>\n> Yes, but again, the point of this thread is to document *one* workflow,\n\nI'd agree here.\n\n> not all possible uses of pushRemote. It's much easier to describe \"one\n> typical triangular workflow\" in a concrete way\n\nThat *one* workflow would be a _specific_ flow - I'm reading 'typical' as\nimplying common/general workflow(s), which may not be what you hoped to\nconvey.\n\n> than to try to be\n> completely general and end up with a description that average users\n> would just not understand.\n\nI do think that the description of the one specific flow should include the\nclarifications that discriminate it from other, potentially mistakenly\nconfused with this one, flows. It would be that disambiguation that would\nclear up the misunderstanding.\n\n>\n> It would be different to me if we were writting the pushRemote part of\n> config.txt, where we have to be as general as possible.\n\nAs an aside, the discussion has indicated that the documentation may be a\nbit light on describing (and referencing) how multi-user server set-ups can\nbe arranged to faciltate (or may hinder) the different flows.\n--\nPhilip\n(mail delayed by lack of wifi) \n"},{"id":"288694","messageId":"CDB4510C-64D4-4357-A175-18D9B5681BD2@grenoble-inp.org","threadId":"42454","inReplyTo":"xmqqr3c8q0d5.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCHv3] Documentation: triangular workflow","fromName":"Jordan DE GEA","fromEmail":"jordan.de-gea@grenoble-inp.org","sentAt":"2016-06-08T08:37:17Z","receivedAt":"2016-06-08T08:37:17Z","isPatch":false,"sender":{"key":"jordan.de-gea@grenoble-inp.org","avatar":null},"body":"> Le 7 juin 2016 à 21:12, Junio C Hamano a écrit :\n> \n> Jordan DE GEA writes:\n> \n>> +\n>> +- Taking the last version of the project by fetching (e.g.\n>> + **UPSTREAM**)\n> \n> \"by fetching (e.g. UPSTREAM)\" does not finish the sentence nicely.\n> \n> \"... by fetching from **UPSTREAM**\" would work better. So would\n> \"Fetching the latest version from the project (e.g. UPSTREAM) ».\n\nOk. Changed for the next iteration. \n\n>> +- Writing modifications and push them to a fork (e.g. **PUBLISH**)\n>> +- Opening a pull request\n>> +- Checking of changes by the maintainer and, merging them into the\n>> + **UPSTREAM** repository if accepted\n> \n> You'd want to end these sentences with full-stop, by the way\n> \n\nOK too. \n\n>> +........................................\n>> +------------------ -----------------\n>> +| UPSTREAM | maintainer | PUBLISH |\n>> +| git/git |- - - - - - - -| me/remote |\n>> +------------------ ← -----------------\n>> + \\ /\n>> + \\ /\n>> + fetch↓\\ /↑push\n>> + \\ /\n>> + \\ /\n>> + -------------\n>> + | LOCAL |\n>> + -------------\n>> +........................................\n>> +\n>> +Git options to use:\n>> +~~~~~~~~~~~~~~~~~~~\n>> + - `branch..remote`\n>> + - `branch..pushRemote`\n>> + - `remote.pushDefault`\n>> + - `push.default`\n>> +\n>> +See linkgit:git-config[1].\n> \n> The title says \"options\" but listed are configuration variables and\n> the referred document is also about git-config. Perhaps retitle it to\n> \n> \tUseful configuration variables\n> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> \n\nOk too. \n\n\n> or something like that?\n> \n> One thing after reading the above lines that immediately came to my\n> mind was this:\n> \n> After listing these four and telling the reader to \"See ...\", is\n> there anything else the reader needs to learn from below?\n> \n> It may make the result a lot more useful document if this gives an\n> impression to the reader as if you are saying (you do not have to\n> actually say it) \"We will guide you how to set up your workflow in\n> triangular way, and here are the key configuration variables you\n> will end up using; don't worry about the details of them, we'll\n> teach you all about them soon in the following paragraphs.\"\n> \n> And I found that \"See linkgit:git-config[1]\" go directly against\n> that line of narrative.\n\nA link is already added at the end of the document. So I delete this one. \n\n> \n>> +Push behaviour\n>> +~~~~~~~~~~~~~~\n>> + ...\n>> +\n>> +Case 2: LOCAL is a clone of **UPSTREAM**\n>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>> +\n>> +'In this case, the remote named `origin` corresponds to **UPSTREAM**.'\n>> +\n>> +Adding **PUBLISH** remote:\n>> +\n>> +===================================\n>> +* `git remote add publish `\n>> +===================================\n> \n> It may perhaps be only me, but these blind instructions puts me off,\n> and what I find lacking is \"Why should I do this?\" \"What benefit do\n> I get by doing this\". Start it perhaps like this?\n> \n> \tBecause you will be pushing into the publish repository\n> \toften, instead of having to type its URL every time, you\n> \twant a short name you can use to call it.\n> \n> and then give that \"remote add\".\n\nOk. Similar text added for the next iteration. \n\n>> +\n>> +**Method 1: One option for all branches**\n>> +\n>> +Setting `remote.pushDefault` in order to push to **PUBLISH** without\n>> +argument for push.\n>> +\n>> +===================================\n>> +* `git config remote.pushDefault publish`\n>> +===================================\n> \n> This is not too bad, but I'd say\n> \n> \tWith the \"remote add\" above, you can say \"git push publish\"\n> \tto push there, instead of saying its URL. But you may want\n> \tto be even lazier and say just \"git push\". To do so:\n> \n\nOk too. Similar text added for the next iteration. \n\n> As a document that is geared toward being a tutorial, I personally\n> think it is better to stick to one arrangement rather than\n> presenting case 1/2 as two equivalently valid arrangements and\n> describe them to equal degree of detail. Otherwise, after finishing\n> reading Case 1 and immediately reading Case 2 heading, the reader\n> would start wondering \"Which one should I pick? What are the pros\n> and cons?\".\n> \n> A typical reader of this document would have an upstream in mind,\n> perhaps a clone of it locally, and may or may not yet have a publish\n> repository, so one valid choice could be to use Case 2.\n> \n> Whichever one you choose, the description should not begin with\n> \"pushing\". A reader who is the target of this document (i.e. who\n> owns the LOCAL and PUBLISH repository) begins by cloning and/or\n> fetching, followed by working on her own change while staying up to\n> date, and pushing is the last thing she does in the flow.\n> \n> So I'd recommend reordering the description to\n> \n> * Introduction. As a summary, here are the four configuration\n> variables you'll be using to make it easier to arrange.\n> \n> * \"Preparation\". Clone from the upstream, create an empty\n> publish repository and set it as a secondary remote, with\n> pushdefault pointing at it.\n> \n> * \"Staying up-to-date\". You do not have to describe \"git fetch\"\n> or \"git pull\" from the upstream aka origin with too much\n> detail, as having or not having a publish repository does not\n> change anything on this side.\n> \n> * \"Making your work available\". You would want to reiterate the\n> fact that \"git push\" does not go to the upstream but to your\n> publishing place thanks to the earlier pushdefault\n> configuration.\n> \n> * \"Alternatively...\". In this section, you could mention\n> possible other arrangements. One could be to set pushdefault\n> for each and every branch (aka your Case 2/Method 2), which\n> shouldn't be necesssary because at the beginning of the\n> document we made it clear that we assume that the reader\n> cannot push to upstream--the normal place she would be pushing\n> is to her own publishing place, and configuring \"usually all\n> of them go to my publishing place, but this one alone will go\n> someplace else\" (1) is an advanced workflow element, and more\n> importantly (2) is not specific to triangular workflow.\n> \n> Another altenative arrangement worth mentioning may be your\n> Case 1, i.e. to point at your publish place and a secondary\n> \"upstream\" pointing at where your upstream publishes their\n> work. You can describe what needs to be changed compared to\n> the above three sections.\n\nYes, that clearer like that. I reorganize and send a new patch. \n"},{"id":"288717","messageId":"vpq37on4y29.fsf@anie.imag.fr","threadId":"42454","inReplyTo":"xmqqr3c8q0d5.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCHv3] Documentation: triangular workflow","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2016-06-08T13:20:14Z","receivedAt":"2016-06-08T13:20:14Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Junio C Hamano writes:\n\n> * Introduction. As a summary, here are the four configuration\n> variables you'll be using to make it easier to arrange.\n\nI'd actually skip this, and keep configuration variable names for later.\nThe very point of these --set-upstream & friends options is to allow the\nuser to work without knowing about them. Typically:\n\ngit clone http://example.com/foo\ncd foo\n# hack hack hack\ngit commit\ngit push\n\n=> no configuration variable involved for the user, and it just works.\n\nSo, instead of having a flow like \"We need to configure\nbranch..merge, and a shortcut to do so is to use\n--set-upstream\", I'd rather see \"Let's push and ask push to remember\nwhere we're pushing so that we don't have to tell it again next time:\ngit push --set-upstream origin master. Oh, BTW, internally this sets\nbranch..merge.\".\n\nTalking about --set-upstream, it does not appear at all in your\npatch. Is this on purpose?\n\n\nOTOH, an introduction that would motivate the workflow would be very\nuseful IMHO. I see many people using triangular workflows just because\n\"it's cool\" and I can't be satisfied with this. Among real arguments:\n\n* Allows contributor to work with Git even though they do not have write\n access to upstream.\n\n* Symmetrically, this allows maintainers to receive code from\n contributors they don't trust a priori.\n\n* This makes code review more efficient\n\n* This encourrages clean history (because you can \"rebase -i\" and\n force-push as much as you want to your public fork before the code is\n merged)\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"288805","messageId":"1465475708-1912-1-git-send-email-jordan.de-gea@grenoble-inp.org","threadId":"42454","inReplyTo":"1465288693-6295-1-git-send-email-jordan.de-gea@grenoble-inp.org","subject":"[PATCHv4] Documentation: triangular workflow","fromName":"Jordan DE GEA","fromEmail":"jordan.de-gea@grenoble-inp.org","sentAt":"2016-06-09T12:35:08Z","receivedAt":"2016-06-16T02:19:49Z","isPatch":false,"sender":{"key":"jordan.de-gea@grenoble-inp.org","avatar":null},"body":"Currently, triangular workflow can be configured, but there is no\ndocumentation about it. A documentation is useful to keep\nconfiguration possibilities up-to-date.\n\nA new subsection is created in gitworkflow.\n\nSigned-off-by: Michael Haggerty \nSigned-off-by: Matthieu Moy \nSigned-off-by: Jordan DE GEA \n---\nChanges since v3:\n * Text reorganized to follow:\n - Introduction\n - Preparation\n - Staying up-to-date\n - Alternatively\n * Texts added to explain why we use commands in:\n - Preparation\n - Alternatively\n\n Documentation/gitworkflows.txt | 177 ++++++++++++++++++++++++++++++++++++++++-\n 1 file changed, 176 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\nindex f16c414..1ec1f63 100644\n--- a/Documentation/gitworkflows.txt\n+++ b/Documentation/gitworkflows.txt\n@@ -463,6 +463,178 @@ if you get conflicts: `git am -3` will use index information contained\n in patches to figure out the merge base. See linkgit:git-am[1] for\n other options.\n \n+TRIANGULAR WORKFLOW\n+-------------------\n+\n+In some projects, you cannot push directly to the project but have to\n+suggest your 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+- Taking the last version of the project by fetching from **UPSTREAM**\n+- Writing modifications and push them to a fork (e.g. **PUBLISH**)\n+- Opening a pull request\n+- If the maintainer accepts the changes, he merges them into the\n+ **UPSTREAM** repository.\n+\n+\n+........................................\n+------------------ -----------------\n+| UPSTREAM | maintainer | PUBLISH |\n+| git/git |- - - - - - - -| me/remote |\n+------------------ ← -----------------\n+ \\ /\n+ \\ /\n+ fetch↓\\ /↑push\n+ \\ /\n+ \\ /\n+ -------------\n+ | LOCAL |\n+ -------------\n+........................................\n+\n+Motivations\n+~~~~~~~~~~~\n+\n+* Allows contributors to work with Git even though they do not have\n+write access to **UPSTREAM**.\n+\n+* Allows maintainers to receive code from contributors they may not\n+trust.\n+\n+* Code review is more efficient\n+\n+* Encourages clean history by using `rebase -i` and `push --force` to \n+your public fork before the code is merged\n+\n+Preparation\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, `git pull` can pull from\n+**UPSTREAM** without argument.\n+\n+For each branch requiring a triangular workflow, set\n+`branch..remote` and `branch..pushRemote`.\n+\n+Example with master as :\n+===================================\n+* `git config branch.master.remote upstream`\n+* `git config branch.master.pushRemote origin`\n+===================================\n+\n+Stay up-to-date\n+~~~~~~~~~~~~~~~\n+\n+Retrieve updates from **UPSTREAM** with `git pull` and send them to\n+**PUBLISH** with `git push`.\n+\n+Checks\n+~~~~~~\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+Alternative configuration\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 SEE ALSO\n --------\n@@ -473,7 +645,10 @@ linkgit:git-merge[1],\n linkgit:git-rebase[1],\n linkgit:git-format-patch[1],\n linkgit:git-send-email[1],\n-linkgit:git-am[1]\n+linkgit:git-am[1],\n+linkgit:git-config[1],\n+linkgit:git-log[1],\n+linkgit:git-rev-parse[1]\n \n GIT\n ---\n-- \n2.7.4 (Apple Git-66)\n"},{"id":"288823","messageId":"xmqqmvmui9d2.fsf@gitster.mtv.corp.google.com","threadId":"42454","inReplyTo":"1465475708-1912-1-git-send-email-jordan.de-gea@grenoble-inp.org","subject":"Re: [PATCHv4] Documentation: triangular workflow","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-06-09T17:02:17Z","receivedAt":"2016-06-16T02:19:49Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jordan DE GEA writes:\n\n> +Motivations\n> +~~~~~~~~~~~\n\n> +* Allows contributors to work with Git even though they do not have\n> +write access to **UPSTREAM**.\n>\n> +* Allows maintainers to receive code from contributors they may not\n> +trust.\n\nI somehow don't think \"even though\" sits well here. You can work\nwith Git all you want locally even if you do not have write access\nanywhere, but that is stating the obvious. Also, unless the only\nalternative you are contrasting \"triangular\" with is \"a single\ncentral repository workflow\", \"may not trust\" is not a unique\nadvantage of \"triangular\". You can exchange patches and reviews\nwith contributors just like you do.\n\nI think the more important thing to say instead of the above two is\nthat this arrangement allows distributed workflow; you publish to\nyour place at your own pace, they pull from you if and when they\nchoose to, and they publish their result to their place at their own\npace.\n\n> +* Code review is more efficient\n\nI have no idea what data you have to back this claim up. More\nefficient compared to what?\n\nIf you are contrasting \"triangular\" with \"a single central\nrepository everybody pushes into\", then one big advantage\n\"triangular\" can have around \"code review\" is that it allows reviews\nbefore the code hits the authoritative history of the project. If\nyour project works with a single central repository everybody pushes\ninto, things tend to run in reverse--after you push questionable\nstuff into the project history, somebody else has to spot problems,\ngo in and fix it after the fact.\n\n> +* Encourages clean history by using `rebase -i` and `push --force` to \n> +your public fork before the code is merged\n\nThis is a side-effect of \"review before merge\" mentioned earlier.\n\n\n> +Preparation\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, `git pull` can pull from\n> +**UPSTREAM** without argument.\n> +\n> +For each branch requiring a triangular workflow, set\n> +`branch..remote` and `branch..pushRemote`.\n> +\n> +Example with master as :\n> +===================================\n> +* `git config branch.master.remote upstream`\n> +* `git config branch.master.pushRemote origin`\n> +===================================\n\nWouldn't it be much simpler to manage if you instead start from a\nclone of **UPSTREAM** and then fork **PUBLISH** and push your work\nout to the latter? You do not have to do per-branch configuration\nthat way, no? Instead you would set default.pushRemote to publish\njust once, and no matter how many branches you create later, you do\nnot have to do anything special.\n\nIt smells like you are deliberately presenting a more cumbersome\nway, as a prelude to add even more configuration that is not\nnecessary if you started in the right direction in the first place.\n"},{"id":"288840","messageId":"E41AB752AE614E189BC5BE289A8AEB2A@PhilipOakley","threadId":"42454","inReplyTo":"1465475708-1912-1-git-send-email-jordan.de-gea@grenoble-inp.org","subject":"Re: [PATCHv4] Documentation: triangular workflow","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-09T18:19:20Z","receivedAt":"2016-06-16T02:19:50Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Jordan DE GEA\" \n> Currently, triangular workflow can be configured, but there is no\n> documentation about it. A documentation is useful to keep\n> configuration possibilities up-to-date.\n>\n> A new subsection is created in gitworkflow.\n>\n> Signed-off-by: Michael Haggerty \n> Signed-off-by: Matthieu Moy \n> Signed-off-by: Jordan DE GEA \n> ---\n> Changes since v3:\n> * Text reorganized to follow:\n> - Introduction\n> - Preparation\n> - Staying up-to-date\n> - Alternatively\n> * Texts added to explain why we use commands in:\n> - Preparation\n> - Alternatively\n>\n> Documentation/gitworkflows.txt | 177 \n> ++++++++++++++++++++++++++++++++++++++++-\n> 1 file changed, 176 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/gitworkflows.txt \n> b/Documentation/gitworkflows.txt\n> index f16c414..1ec1f63 100644\n> --- a/Documentation/gitworkflows.txt\n> +++ b/Documentation/gitworkflows.txt\n> @@ -463,6 +463,178 @@ if you get conflicts: `git am -3` will use index \n> information contained\n> in patches to figure out the merge base. See linkgit:git-am[1] for\n> other options.\n>\n> +TRIANGULAR WORKFLOW\n> +-------------------\n> +\n> +In some projects, you cannot push directly to the project but have to\n> +suggest your 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> +- Taking the last version of the project by fetching from **UPSTREAM**\n> +- Writing modifications and push them to a fork (e.g. **PUBLISH**)\n\ns/a fork/an accessible fork/\nIsn't one of the key points of the triangle that the user can't push to the \nupstream? (and the maintainer can't see the users local repo)\n\n> +- Opening a pull request\ns/request/request (formally or informally)/\n\n> +- If the maintainer accepts the changes, he merges them into the\na Catch 22 here. The maintainer needs first to fetch, or othewise read, the \nmods before she could accept the changes. Perhaps\n\n- The maintainer fetches, and reviews, the proposed changes; And if \nacceptable, merges them into the upstream.\n\nthe exact timing of the fetch will depend on the review system (see below).\n\n> + **UPSTREAM** repository.\n> +\n> +\n> +........................................\n> +------------------ -----------------\n> +| UPSTREAM | maintainer | PUBLISH |\n> +| git/git |- - - - - - - -| me/remote |\n> +------------------ ← -----------------\n> + \\ /\n> + \\ /\n> + fetch↓\\ /↑push\n> + \\ /\n> + \\ /\n> + -------------\n> + | LOCAL |\n> + -------------\n> +........................................\n> +\n> +Motivations\n> +~~~~~~~~~~~\n> +\n> +* Allows contributors to work with Git even though they do not have\n> +write access to **UPSTREAM**.\n> +\n> +* Allows maintainers to receive code from contributors they may not\n> +trust.\ns/trust/trust with psuh access/\nIt is the push/pull access issues that create the triangular workflow!\n\n> +\n> +* Code review is more efficient\n\nmore efficient than ??? in environment ??? (e.g. a review process of web \nviewing/commenting on GitHub, driven by a limited patch/mail server \ncapability)\n\n\n> +\n> +* Encourages clean history by using `rebase -i` and `push --force` to\n> +your public fork before the code is merged\n> +\n> +Preparation\n> +~~~~~~~~~~~\n> +\n> +Cloning from **PUBLISH**, which is a fork of **UPSTREAM** or an empty\n> +repository.\n\nI agree here. To clone the upstream, to which you have no push access (by \ndefinition), would leave the config badly mis-set for the basic user. It's \nbetter for the user to clone their publish fork (to which they have both \nread and write access).\n\nOne issue may be the different expectations of how the fork is created (it's \nonly one click on the GitHub..)\n\nIt may be worth covering the remote rename option to set that origin to the \nshort and sweet 'me', or 'my', as per the ascii diagram.\n\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, `git pull` can pull from\n> +**UPSTREAM** without argument.\n> +\n> +For each branch requiring a triangular workflow, set\n> +`branch..remote` and `branch..pushRemote`.\n> +\n> +Example with master as :\n> +===================================\n> +* `git config branch.master.remote upstream`\n> +* `git config branch.master.pushRemote origin`\n> +===================================\n> +\n> +Stay up-to-date\n> +~~~~~~~~~~~~~~~\n> +\n> +Retrieve updates from **UPSTREAM** with `git pull` and send them to\n> +**PUBLISH** with `git push`.\n> +\n> +Checks\n> +~~~~~~\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> +Alternative configuration\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** \n> 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> SEE ALSO\n> --------\n> @@ -473,7 +645,10 @@ linkgit:git-merge[1],\n> linkgit:git-rebase[1],\n> linkgit:git-format-patch[1],\n> linkgit:git-send-email[1],\n> -linkgit:git-am[1]\n> +linkgit:git-am[1],\n> +linkgit:git-config[1],\n> +linkgit:git-log[1],\n> +linkgit:git-rev-parse[1]\n>\n> GIT\n> ---\n"},{"id":"288933","messageId":"xmqqinxhf0sx.fsf@gitster.mtv.corp.google.com","threadId":"42454","inReplyTo":"E41AB752AE614E189BC5BE289A8AEB2A@PhilipOakley","subject":"Re: [PATCHv4] Documentation: triangular workflow","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-06-10T16:47:42Z","receivedAt":"2016-06-16T02:19:51Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n>> +Preparation\n>> +~~~~~~~~~~~\n>> +\n>> +Cloning from **PUBLISH**, which is a fork of **UPSTREAM** or an empty\n>> +repository.\n>\n> I agree here. To clone the upstream, to which you have no push access (by \n> definition), would leave the config badly mis-set for the basic user. It's \n> better for the user to clone their publish fork (to which they have both \n> read and write access).\n\nI do not think I agree.\n\nIf you apriori know that you do want to hack on a project's code, then\nforking at GitHub first and then cloning the copy would be OK.\n\nBut I doubt that would be a common set-up, unless you are focusing\nonly on school-like setting where you are told by your instructor to\n\"make changes to this public project, and show the result in your\nfork\". In real life you cannot tell if the project is worth your\ntime modifying until you see it first, can you?\n\nI suspect that the majority of local clones start from something\nlike \"I want to build and use from the tip\", \"I want to use a module\nthat does X, and there are three candidates, so let's clone them all\nto evaluate\", etc. You do not bother \"forking at GitHub\" but just\nclone from the upstream for these clones.\n\nAfter you build it and try things out, you may start making local\nchanges, and you may even record your changes as local commits. You\nplay with your local clone of the upstream. After doing so, you may\nfind that some of the projects do not fit your needs, but for some\nothers, you would find that it is worth your time and effort to\nupstream your changes and/or keep working further on the project.\n\nAnd at that point, you would create a publishing place, push into\nit, and tell others \"Hey I did this interesting thing!\". That\n\"creat a publishing place\" step could be just a one click at GitHub.\n\nIsn't that how you work with other people's projects? Or do you\nalways modify every project you fetch from the outside world?, Do\nyou always fork first, just in case you *might* change and you\n*might* have to have a place to push your changes out?\n\nIf you tell novices \"You fork first and then clone your fork\", and\nin the ideal (to you) case they will follow that advice to the\nletter and they will end up with forks of all projects they will\never look at, in many of which they make no local commit.\n\nWhat is more likely to happen is that they will first ignore you and\nstart from a local clone of the upstream, and then find this\ndocument that says \"triangular workflow requires you to fork first,\nclone that fork and work in it\". Because they would have to fork\nfirst and make another clone, this time a clone of the fork, in\norder to follow the instruction of this document, they oblige,\nending up with two clones. More importantly, this makes the local\nclone of the upstream they made earlier and the changes they made in\nthat clone appear useless. They need to be told how to transplant\nthe work done in the clone to the newly created clone of the fork,\nin order to publish them.\n\nIf your instruction begins with \"You clone from upstream as usual\n(i.e. just like when you make a \"read-only\" clone without any\nintention to make changes or push changes out), and add a publish\nplace if/when it becomes necessary\", the problem described in the\nprevious paragraph goes away, no?\n"},{"id":"289019","messageId":"CALkWK0nJDwH27V9B+X2K=c_X2k82ZXnab1r1zR6_axipxT5gkg@mail.gmail.com","threadId":"42454","inReplyTo":"xmqqmvmui9d2.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCHv4] Documentation: triangular workflow","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2016-06-11T15:58:12Z","receivedAt":"2016-06-16T02:19:52Z","isPatch":false,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Junio C Hamano wrote:\n> Jordan DE GEA wrote:\n>\n> > +* Allows contributors to work with Git even though they do not have\n> > +write access to **UPSTREAM**.\n> >\n> > +* Allows maintainers to receive code from contributors they may not\n> > +trust.\n\nTriangular workflow is the ability to accept changes from contributors\nwithout mailing patches back-and-forth. Whether they send a pull\nrequest or commit directly to the master repository when review is\ndone, is inconsequential. Essentially, they maintain forks of\nupstream, which they work on at their own pace.\n\n> > +* Code review is more efficient\n>\n> I have no idea what data you have to back this claim up. More\n> efficient compared to what?\n\nThey're orthogonal. LLVM has one giant SVN server that everyone\ncommits directly to. However, they review process is a lot more\nefficient than GitHub projects, because they use Phabricator. What\ndoes code review tool have to do with triangular workflow?\n\n> > +Preparation\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, `git pull` can pull from\n> > +**UPSTREAM** without argument.\n> > +\n> > +For each branch requiring a triangular workflow, set\n> > +`branch..remote` and `branch..pushRemote`.\n> > +\n> > +Example with master as :\n> > +===================================\n> > +* `git config branch.master.remote upstream`\n> > +* `git config branch.master.pushRemote origin`\n> > +===================================\n\nIt's much too simple now. Just `git clone `, `git remote add\nmine `, and `git config remote.pushdefault mine`. Only the\nlast line requires an explanation.\n\n> Instead you would set default.pushRemote to publish\n> just once, and no matter how many branches you create later, you do\n> not have to do anything special.\n\nI think you meant remote.pushdefault here?\n"},{"id":"289020","messageId":"5B90624A6DC7442C94B933A07F0CD08D@PhilipOakley","threadId":"42454","inReplyTo":"xmqqinxhf0sx.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCHv4] Documentation: triangular workflow","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-11T19:25:58Z","receivedAt":"2016-06-16T02:19:52Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> \"Philip Oakley\" writes:\n>\n>>> +Preparation\n>>> +~~~~~~~~~~~\n>>> +\n>>> +Cloning from **PUBLISH**, which is a fork of **UPSTREAM** or an empty\n>>> +repository.\n>>\n>> I agree here. To clone the upstream, to which you have no push access (by\n>> definition), would leave the config badly mis-set for the basic user.\n>> It's\n>> better for the user to clone their publish fork (to which they have both\n>> read and write access).\n>\n> I do not think I agree.\n>\n> If you apriori know that you do want to hack on a project's code, then\n> forking at GitHub first and then cloning the copy would be OK.\n>\n\nYou've clipped my other point:\n\n- One issue may be the different expectations of how the fork is\n- created (it's only one click on the GitHub..)\n\nThe fork creation issue is surely an essential part of triangular workflow - \na fork isn't required for a patch workflow. Git uses patch flow, while \nGit-for-Windows makes use of (GitHub's) Pull Requests.\n\nMost projects will be using some form of hosting service to provide their \npublic publish repo, and often allow no public pushes. It's the upstream \nthat choses the hosting service, which decides the users choices.\n\n> But I doubt that would be a common set-up, unless you are focusing\n> only on school-like setting where you are told by your instructor to\n> \"make changes to this public project, and show the result in your\n> fork\". In real life you cannot tell if the project is worth your\n> time modifying until you see it first, can you?\n\nAt this point there are multiple choices depending how the hosting and \nproject is set up. It may already be packaged. It may allow full web \nbrowsing of the code. It probably has tar/zip download of the latest master. \nSome popular sites offer free hosting and forking, which leads to the the \nsuggested method.\n\n>\n> I suspect that the majority of local clones start from something\n> like \"I want to build and use from the tip\", \"I want to use a module\n> that does X, and there are three candidates, so let's clone them all\n> to evaluate\", etc. You do not bother \"forking at GitHub\" but just\n> clone from the upstream for these clones.\n\nAny stat's for this. I'd be far more likely to fork first, giving me a \nbackup vault, and clone that, especially since being bitten (historically) \nby the need to juggle the configs after the fact..\n\n>\n> After you build it and try things out, you may start making local\n> changes, and you may even record your changes as local commits. You\n> play with your local clone of the upstream. After doing so, you may\n> find that some of the projects do not fit your needs, but for some\n> others, you would find that it is worth your time and effort to\n> upstream your changes and/or keep working further on the project.\n\nIn all these cases there is the 'backup' copy question for any of those \nmods, which tends to mean the user will have a fork acting as a home vault.\n\n>\n> And at that point, you would create a publishing place, push into\n> it, and tell others \"Hey I did this interesting thing!\". That\n> \"creat a publishing place\" step could be just a one click at GitHub.\n>\n> Isn't that how you work with other people's projects? Or do you\n> always modify every project you fetch from the outside world?, Do\n> you always fork first, just in case you *might* change and you\n> *might* have to have a place to push your changes out?\n\nAs noted above, yes, if I'm interested enough to go for the clone, then mods \nare a real posibility and I'd typically use the hosting service as a \nvault/triangle.\n\n>\n> If you tell novices \"You fork first and then clone your fork\", and\n> in the ideal (to you) case they will follow that advice to the\n> letter and they will end up with forks of all projects they will\n> ever look at, in many of which they make no local commit.\n>\n> What is more likely to happen is that they will first ignore you and\n> start from a local clone of the upstream, and then find this\n> document that says \"triangular workflow requires you to fork first,\n> clone that fork and work in it\". Because they would have to fork\n> first and make another clone, this time a clone of the fork, in\n> order to follow the instruction of this document, they oblige,\n> ending up with two clones. More importantly, this makes the local\n> clone of the upstream they made earlier and the changes they made in\n> that clone appear useless. They need to be told how to transplant\n> the work done in the clone to the newly created clone of the fork,\n> in order to publish them.\n>\n> If your instruction begins with \"You clone from upstream as usual\n> (i.e. just like when you make a \"read-only\" clone without any\n> intention to make changes or push changes out), and add a publish\n> place if/when it becomes necessary\", the problem described in the\n> previous paragraph goes away, no?\n>\n\nYes, the document does need to cover both routes, which should be the main \noutcome of the discussion.\n\nBut I still think that, by definition of the triangular workflow (and the \nreader will be here because they are expecting to be part of that flow), \nthat the fork first (if available), is to my mind, the easiest was to get \nstarted. And if it's not, i.e. they clone upstream first, create a publish \nserver/host/repo, push to that, and adjust all the configs for that, then \nthat should also be described. It all depends on the phantom 'git fork \n ` command.\n\nE.g.\n* Establishing a triangular workflow using upstream's host fork method.\nYou do not have a local clone of upstream yet and hope to work on the \nproject with a triangular flow. /describe the easiest steps from here/\n\n* Converting a local repo to a triangular workflow.\nYou already have a local clone of the upstream, but no public repo that the \nmaintainer can pull from. /describe the necessary steps to set up a fork, \nand appropriate config settings/\n"},{"id":"289021","messageId":"5A8F8EE0162B49818813DAEFD68F61DA@PhilipOakley","threadId":"42454","inReplyTo":"CALkWK0nJDwH27V9B+X2K=c_X2k82ZXnab1r1zR6_axipxT5gkg@mail.gmail.com","subject":"Re: [PATCHv4] Documentation: triangular workflow","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-11T19:31:46Z","receivedAt":"2016-06-16T02:19:52Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Ramkumar Ramachandra\" \n> Junio C Hamano wrote:\n>> Jordan DE GEA wrote:\n>>\n>> > +* Allows contributors to work with Git even though they do not have\n>> > +write access to **UPSTREAM**.\n>> >\n>> > +* Allows maintainers to receive code from contributors they may not\n>> > +trust.\n>\n> Triangular workflow is the ability to accept changes from contributors\n> without mailing patches back-and-forth. Whether they send a pull\n> request or\n\n> commit directly to the master repository\n\nSurely, if they can do this then they do not need a distinct publish repo.\n\nThe triangle is necessary because of the accessibility 'standoff' between \nthe upstream and local repos when a pull workflow is used.\n\nMatthieu had clarified this (to me \nhttp://article.gmane.org/gmane.comp.version-control.git/296538) - I was (at \nthat time) confusing the use of the fork as a home vault (with passive \npublishing) with the need for actively publishing a branch for a PR.\n\n> when review is\n> done, is inconsequential. Essentially, they maintain forks of\n> upstream, which they work on at their own pace.\n>\n>> > +* Code review is more efficient\n>>\n>> I have no idea what data you have to back this claim up. More\n>> efficient compared to what?\n>\n> They're orthogonal. LLVM has one giant SVN server that everyone\n> commits directly to. However, they review process is a lot more\n> efficient than GitHub projects, because they use Phabricator. What\n> does code review tool have to do with triangular workflow?\n>\n>> > +Preparation\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, `git pull` can pull from\n>> > +**UPSTREAM** without argument.\n>> > +\n>> > +For each branch requiring a triangular workflow, set\n>> > +`branch..remote` and `branch..pushRemote`.\n>> > +\n>> > +Example with master as :\n>> > +===================================\n>> > +* `git config branch.master.remote upstream`\n>> > +* `git config branch.master.pushRemote origin`\n>> > +===================================\n>\n> It's much too simple now. Just `git clone `, `git remote add\n> mine `, and `git config remote.pushdefault mine`. Only the\n> last line requires an explanation.\n\nI note that you use 'mine', Jordan was proposing 'me', while I started using \n'my'. It is useful to see these personal choices, especially as there is no \n'origin' in the nominal triangular flow diagram.\n\nWhether to use branch configs or remote configs is part of the \nclarifications.\n\n>\n>> Instead you would set default.pushRemote to publish\n>> just once, and no matter how many branches you create later, you do\n>> not have to do anything special.\n>\n> I think you meant remote.pushdefault here?\n> \n"},{"id":"289160","messageId":"xmqqa8ipc4y8.fsf@gitster.mtv.corp.google.com","threadId":"42454","inReplyTo":"5B90624A6DC7442C94B933A07F0CD08D@PhilipOakley","subject":"Re: [PATCHv4] Documentation: triangular workflow","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-06-13T18:35:27Z","receivedAt":"2016-06-16T06:55:51Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> From: \"Junio C Hamano\" \n>> I do not think I agree.\n>>\n>> If you apriori know that you do want to hack on a project's code, then\n>> forking at GitHub first and then cloning the copy would be OK.\n>\n> You've clipped my other point:\n>\n> - One issue may be the different expectations of how the fork is\n> - created (it's only one click on the GitHub..)\n\nNot really. I said the same thing paraphrased:\n\n And at that point, you would create a publishing place, push into\n it, and tell others \"Hey I did this interesting thing!\". That\n \"create a publishing place\" step could be just a one click at GitHub.\n\nAnyway, let's step back a bit and agree that your local clone needs\nto be told 4 pieces of information to help you in a triangular\nworkflow. They are:\n\n * The URL of the \"upstream\";\n * The URL of the \"publish\" (aka \"mine\");\n * Your push should go to \"publish\" by default; and\n * Your pull should come from \"upstream\" by default.\n\nAre we still on the same page, or have we already diverged?\n\nIf you start from a clone of \"upstream\", then the local clone\nalready knows two out of these four, namely, \"The URL of the\n'upstream' aka origin\" and \"Your pull should come from upstream by\ndefault\". In order to go triangular, you still need to tell the\nother two to your local clone, namely \"There is another remote\ncalled 'publish'\" and \"Your push should go to 'publish' not to\n'origin'\".\n\nWhen you start by forking at GitHub and then cloning that fork,\nwould it make it easier to go triangular? I do not think so. The\nlocal clone gives you (different) two out of these four, namely \"The\nURL of the 'publish' aka origin, which is your own fork\" and \"Your\npush should go to 'publish'\". You still need to tell the other two,\n\"The URL of the 'upstream'\" and \"Your pull should come from\n'upstream', not from 'origin'\" to your local repository.\n\nSo I really do not see a point in arguing that \"forking at GitHub is\neasy with one click\" favors \"your local clone should start by\ncloning your own fork\". Between starting from a clone of upstream\nand starting from a clone of your own fork, it is the same amount of\nwork to go triangular even for people who fork before having any\nclone locally, like you.\n\nAnd I do not have to repeat myself that it is far more helpful to\ngive a recipe to go triangular starting from a clone of upstream for\npeople who first clone three similar projects to evaluate them,\ndiscard two that do not suit their needs, and fork the best one, by\nadding that fork as \"publish\" aka \"mine\", than giving a recipe to\nstart from a clone of one's own fork.\n\nHaving said that, there are indeed two interesting numbers we may\nwant to ask GitHub folks to help coming up with. Take any popular\nproject with many public forks at GitHub, say rails with 13k forks.\n\n * How many \"clone\" from the upstream (i.e. rails/rails in this\n example) compared to 13k forks it has were made by the users?\n\n Many of them might be just following along (e.g. they want to\n build the tip of the tree that is ahead of any tagged released\n version), but there may be some among these local repositories\n cloned from upstream without forking that record their own\n commits. These are the people who will benefit a version of the\n documentation under discussion if it describes how to start from\n a clone of upstream, then add your own fork as the publishing\n repository so that the user can use a triangular workflow. I\n somehow suspect that there are a lot more than 13k (i.e. the\n number of public forks) of these people, but I do not think\n https://github.com/rails/rails page gives us the number.\n\n\n * What percentage of these 13k public forks are \"empty forks\",\n i.e. forked from the main project but has never been pushed into?\n\n It matters if the answer to this question is a non-trivial\n percentage. It indicates that the owners of these forks did the\n \"fork first and then clone from there\", and had to do an extra\n work of adding the real upstream as another remote and set up to\n pull from there, if they wanted to just keep up to date; they\n would have been better off if they started by cloning the\n upstream first.\n"}]}