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

[Matthieu Moy <Matthieu.Moy@grenoble-inp.fr>]

[ +Cc Michael Haggerty ]

Jordan DE GEA <jordan.de-gea@grenoble-inp.org> writes:

> Currently, Triangular Workflow can be configured, but there is no
> Documentation about it. A documentation is useful to keep
> configuration possibilities up-to-date.

You're using capitalization in a strange way. I don't think Triangular
Workflow deserves to be capitalized, and Documentation certainly
doesn't.

Also, you're wrapping your text in a strange way. You did see the
exchange with Antoine about this, right?

A question about your final goal: I had understood that you wanted to
improve the UI, and to design a proper UI you wanted to write a tutorial
about the future UI, and then implement it. Did I mis-understand? What
are the next steps in your plan?

>  Documentation/Makefile                  |   1 +
>  Documentation/gittriangularworkflow.txt | 120 ++++++++++++++++++++++++++++++++
[...]
> --- 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

Adding documentation is one thing, but it needs to be discoverable. No
one is going to type "man gittriangularworkflow" or open
https://git-scm.com/docs/gittriangularworkflow without being told to.

Two obvious questions/suggestions seeing the above:

* Why not add the new documentation as a subsection of gitworkflows.txt?

* If not, then at the very least a link to gittriangularworkflow should
  appear in the SEE ALSO section of gitworkflows.txt.

> +DESCRIPTION
> +-----------
> +
> +Triangular Workflow (or Asymmetric Workflow) is a workflow which gives
> +the possibility to:
> +
> +- fetch (or pull) from a repository
> +- push to another repository

I wouldn't say "gives the possibility to": you already have this
possibility all the time when using Git.

I find Michael Haggerty's definition of triangular workflow much
clearer:

https://github.com/blog/2042-git-2-5-including-multiple-worktrees-and-triangular-workflows#improved-support-for-triangular-workflows

I don't see a licence on the GitHub blog, so I don't think it's legal to
copy-past directly to our docs, but Michael might allow us to do so?

> +In some projects, you don't have to push directly

s/don't have to/cannot/

?

> +Here is an example of configuration:
> +
> +........................................
> +------------               -----------
> +| UPSTREAM |  maintainer   | ORIGIN  |
> +|  git/git |- - - - - - - -|  me/git |
> +------------       ←       -----------
> +         \                   /
> +          \                 /
> +     fetch↓\               /↑push
> +            \             /
> +             \           /
> +             -------------
> +             |   LOCAL   |
> +             -------------
> +........................................

The most important is missing: what is the role of each repo? which one
is public and which one is private?

I'd rather avoid using "ORIGIN" here, as the name is used for the
default remote when cloning, and it's a valid workflow to "git clone"
from UPSTREAM and then "git remote add" your public fork. Perhaps
PUBLIC-FORK?

> +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.
> +
> +b. Create from scratch
> +~~~~~~~~~~~~~~~~~~~~~~
> +Create a repository on your prefered Git repository hosting service.
> +
> +Clone it
> +~~~~~~~~
> +Clone your repository on your machine.

I don't think this section helps much. If the user knows that he or she
wants to "fork (e.g. GitHub) the main project (e.g git/git),", then
saying

  +a. Fork the project
  +~~~~~~~~~~~~~~~~~~~
  +Go to the repository of the project (e.g. git/git) you want
  +and fork it.

does not help at all, it just says the same thing in a more verbose way.

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

Be precise: you just named 3 repositories UPSTREAM, ORIGIN and LOCAL,
and now you're writting "the main repository" (not 100% clear) and "your
repository" (100% not clear, you have two repos).

Actually, most of the time, you'd pull from UPSTREAM/master and push to
PUBLIC-FORK/<topic-branch>, not PUBLIC-FORK/master.

> +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`
> +===================================

"by default" probably needs to be clarified ("when push/pull is called
without argument"?)

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

What does "be up to date" mean?

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/