Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation
- From
Matthieu Moy <matthieu.moy@grenoble-inp.fr>
- Date
- May 31, 2016, 14:33 UTC
- Message-ID
- <vpqy46qs3f3.fsf@anie.imag.fr>
- In-Reply-To
- <1464697717-5751-1-git-send-email-jordan.de-gea@grenoble-inp.org>
[ +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 ++++++++++++++++++++++++++++++++
[...]
Show 7 quoted lines
> --- 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.
Show 8 quoted lines
> +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/
?
Show 16 quoted lines
> +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?
Show 19 quoted lines
> +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.
Show 5 quoted lines
> +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.
Show 22 quoted lines
> +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"?)
Show 5 quoted lines
> +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/