git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation

From
Philip Oakley <philipoakley@iee.org>
Date
Jun 3, 2016, 07:25 UTC
Message-ID
<9FB65CA220F84B6B882B75435DDA3D65@PhilipOakley>
In-Reply-To
<1464697717-5751-1-git-send-email-jordan.de-gea@grenoble-inp.org>
[Just catching up with responses]
From: "Jordan DE GEA" <jordan.de-gea@grenoble-inp.org>
Sent: Tuesday, May 31, 2016 1:28 PM
Show 72 quoted lines
> Currently, Triangular Workflow can be configured, but there is no
> Documentation about it. A documentation is useful to keep
> configuration possibilities up-to-date.
> The new documentation file gittriangularworkflow explains
> how to configure a triangular workflow.
>
> Signed-off-by: Matthieu Moy <Matthieu.Moy@grenoble-inp.fr>
> Signed-off-by: Jordan DE GEA <jordan.de-gea@grenoble-inp.org>
> ---
> Documentation/Makefile                  |   1 +
> Documentation/gittriangularworkflow.txt | 120 
> ++++++++++++++++++++++++++++++++
> 2 files changed, 121 insertions(+)
> create mode 100644 Documentation/gittriangularworkflow.txt
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index f6e288b..e9f6c80 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -34,6 +34,7 @@ MAN7_TXT += gitrevisions.txt
> MAN7_TXT += gittutorial-2.txt
> MAN7_TXT += gittutorial.txt
> MAN7_TXT += gitworkflows.txt
> +MAN7_TXT += gittriangularworkflow.txt
>
> MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
> MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
> diff --git a/Documentation/gittriangularworkflow.txt 
> b/Documentation/gittriangularworkflow.txt
> new file mode 100644
> index 0000000..803eee3
> --- /dev/null
> +++ b/Documentation/gittriangularworkflow.txt
> @@ -0,0 +1,120 @@
> +gittriangularworkflow(7)
> +=======================
> +
> +NAME
> +----
> +gittriangularworkflow - A tutorial about the configuration of a
> +Triangular Workflow
> +
> +SYNOPSIS
> +--------
> +[verse]
> +git fetch
> +git remote
> +git config
> +Options in git-config:
> +- `remote.pushDefault`
> +- `branch.<branch>.pushRemote`
> +- `branch.<branch>.origin`
> +
> +DESCRIPTION
> +-----------
> +
> +Triangular Workflow (or Asymmetric Workflow) is a workflow which gives
> +the possibility to:
> +
> +- fetch (or pull) from a repository
> +- push to another repository
> +
> +In some projects, you don't have to push directly to the project but
> +have to suggest your commits to the maintainer (e.g. pull requests).
> +Using Triangular Workflow is a common way for these projects.
> +
> +This document attempts to help you configure a Triangular Workflow.
> +Here is an example of configuration:
> +
> +........................................
> +------------               -----------
> +| UPSTREAM |  maintainer   | ORIGIN  |

UPSTREAM and ORIGIN are two different types of description. Origin being a too generic Git name that is used multiply elsewhere.

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.

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.

> +|  git/git |- - - - - - - -|  me/git |

I think it is good to reference the use of "me" as a short remote name - personally I ended up using "my"/remote, but having one in the documentation will set a common trend.

Show 22 quoted lines
> +------------       ←       -----------
> +         \                   /
> +          \                 /
> +     fetch↓\               /↑push
> +            \             /
> +             \           /
> +             -------------
> +             |   LOCAL   |
> +             -------------
> +........................................
> +
> +CREATE YOUR REPOSITORY
> +----------------------
> +The first step is to create your own repository. To do that you can:
> +
> +- a. fork (e.g. GitHub) the main project (e.g git/git), or
> +- b. create an empty repository
> +
> +a. Fork the project
> +~~~~~~~~~~~~~~~~~~~
> +Go to the repository of the project (e.g. git/git) you want
> +and fork it.

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.

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)

Show 63 quoted lines
> +
> +b. Create from scratch
> +~~~~~~~~~~~~~~~~~~~~~~
> +Create a repository on your prefered Git repository hosting service.
> +
> +Clone it
> +~~~~~~~~
> +Clone your repository on your machine.
> +
> +
> +CONFIGURE BRANCHES
> +------------------
> +In many projects, the branch `master` have to be pulled from
> +the main repository(e.g. git/git) and pushed to your repository
> +(e.g. me/git).
> +
> +Adding the main project remote
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Add a new remote (e.g. upstream):
> +
> +===================================
> +`git remote add upstream <main_project_url>`
> +===================================
> +
> +Pull from upstream by default
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +===================================
> +`git config branch.master.remote upstream`
> +===================================
> +
> +
> +Push to origin by default
> +~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +===================================
> +`git config branch.master.pushRemote origin`
> +===================================
> +
> +
> +GET YOUR PROJECT UP TO DATE
> +---------------------------
> +
> +Now that `branch.master.remote` and `branch.master.pushRemote` are
> +set, you can use the following commands to be up to date:
> +=====================================
> + * `git pull`
> + * `git push`
> +=====================================
> +
> +
> +SEE ALSO
> +--------
> +linkgit:git-config[1]
> +linkgit:git-remote[1]
> +linkgit:git-fetch[1]
> +
> +
> +
> -- 
> 2.7.4 (Apple Git-66)
>
>
Previous: Michael HaggertyNext: Jordan DE GEA
Message 11 of 41 in “[RFC] Triangular Workflow: user friendly full implementation”
  1. Jordan DE GEAMay 26, 2016
  2. Matthieu MoyMay 26, 2016
  3. Junio C HamanoMay 26, 2016
  4. [RFC] Triangular Workflow UI improvementJordan DE GEA, May 30, 2016
  5. Philip OakleyMay 27, 2016
  6. [RFC] Triangular Workflow UI improvmentsJordan DE GEA, May 30, 2016
  7. Triangular Workflow UI improvement: DocumentationJordan DE GEA, May 31, 2016
  8. Matthieu MoyMay 31, 2016
  9. Jordan DE GEAJun 1, 2016
  10. Michael HaggertyJun 2, 2016
  11. Philip OakleyJun 3, 2016
  12. Jordan DE GEAJun 3, 2016
  13. Matthieu MoyJun 3, 2016
  14. Jordan DE GEAJun 3, 2016
  15. Jordan DE GEAJun 5, 2016
  16. Matthieu MoyJun 6, 2016
  17. Philip OakleyJun 6, 2016
  18. Matthieu MoyJun 6, 2016
  19. Philip OakleyJun 6, 2016
  20. Matthieu MoyJun 7, 2016
  21. Philip OakleyJun 7, 2016
  22. Junio C HamanoJun 3, 2016
  23. Philip OakleyJun 3, 2016
  24. [RFC/PATCHv2] Documentation: triangular workflowJordan DE GEA, Jun 6, 2016
  25. Junio C HamanoJun 6, 2016
  26. Philip OakleyJun 6, 2016
  27. Matthieu MoyJun 7, 2016
  28. Jordan DE GEAJun 7, 2016
  29. [PATCHv3] Documentation: triangular workflowJordan DE GEA, Jun 7, 2016
  30. Junio C HamanoJun 7, 2016
  31. Jordan DE GEAJun 8, 2016
  32. Matthieu MoyJun 8, 2016
  33. [PATCHv4] Documentation: triangular workflowJordan DE GEA, Jun 9, 2016
  34. Junio C HamanoJun 9, 2016
  35. Ramkumar RamachandraJun 11, 2016
  36. Philip OakleyJun 11, 2016
  37. Philip OakleyJun 9, 2016
  38. Junio C HamanoJun 10, 2016
  39. Philip OakleyJun 11, 2016
  40. Junio C HamanoJun 13, 2016
  41. [RFC] Triangular Workflow UI improvementJordan DE GEA, May 30, 2016

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.