> Jordan DE GEA <jordan.de-gea@xxxxxxxxxxxxxxxx> 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. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html