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

["Philip Oakley" <philipoakley@iee.org>]

[Just catching up with responses]

From: "Jordan DE GEA" <jordan.de-gea@grenoble-inp.org>
Sent: Tuesday, May 31, 2016 1:28 PM
> 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.

> +------------       ←       -----------
> +         \                   /
> +          \                 /
> +     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)

> +
> +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)
>
>