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

[Jordan DE GEA <jordan.de-gea@grenoble-inp.org>]

> 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?

Yes, thank you. I will fix that. 

> 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?

The first goal is to write a documentation on "how to set up a triangular
workflow" with the current options. After that, we can discuss about the
UI improvement. 

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

Yes, adding a subsection in gitworkflows seems to be a better choice.

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

You’re right. Can Michael Taggerty allow us to use his text ?

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

Done

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

With Michael Taggerty’s text, it will be more understandable. 

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

I will shorten for the next iteration. 

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

Yes, that is too verbose. 

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

OK. 


I'll work on these issues and send a new RFC soon.