Issue 5484043: CG: explanation of branches for the impatient (Closed)
|
Created:
12 years, 4 months ago by Graham Percival Modified:
12 years, 3 months ago CC:
lilypond-devel_gnu.org Visibility:
Public. |
DescriptionCG: explanation of branches for the impatient
development on this now takes place at:
http://codereview.appspot.com/5539062/
Patch Set 1 #
Total comments: 11
Patch Set 2 : updated with Keith's suggestions #Patch Set 3 : fix embarrassing typo #Patch Set 4 : fix bad upload #
Total comments: 3
MessagesTotal messages: 11
CG now has N+1 different introductory explanations of git, where N is at least 3. But given the lack of familiarity with branches that I see in our development community, and the new staging stuff, I think this one is good. Once it's been accepted (in whatever form), I'll clean up the rest of this chapter.
Sign in to reply to this message.
Looks fine, except for a couple `git merge` commands where I suggest other things. The closest analogue to applying patch files is not `git merge` but rather `git cherry-pick`. But that is not so useful as the analogue of creating a series of one or more patch files, and applying them in sequence to the current master, which involves either `git rebase master` or `git pull -r` http://codereview.appspot.com/5484043/diff/1/Documentation/contributor/source... File Documentation/contributor/source-code.itexi (right): http://codereview.appspot.com/5484043/diff/1/Documentation/contributor/source... Documentation/contributor/source-code.itexi:215: export PS1="\u@\h \w\$(__git_ps1)$ " requires git-completion to be installed http://codereview.appspot.com/5484043/diff/1/Documentation/contributor/source... Documentation/contributor/source-code.itexi:280: the branch anything you want as long as it starts @code{dev/}. ? Do you mean "Choose a name starting with dev/ to safely distinguish your branch from the shared branches like 'master' 'stable' etc." http://codereview.appspot.com/5484043/diff/1/Documentation/contributor/source... Documentation/contributor/source-code.itexi:317: Edit files. Compile to test. Edit more files. Go eat dinner. insert "Commit your changes (locally)." probably before dinner. http://codereview.appspot.com/5484043/diff/1/Documentation/contributor/source... Documentation/contributor/source-code.itexi:338: @subsubheading Rebasing on top of master (optional) "Rebasing on top of master (one option)" Rebasing, or at least getting the same result as rebasing, is not really optional. One way or another, we want to ensure that each patch going into the repository appears as a simple forward step in the history. http://codereview.appspot.com/5484043/diff/1/Documentation/contributor/source... Documentation/contributor/source-code.itexi:344: @example On branch dev/cg, simply git pull -r http://codereview.appspot.com/5484043/diff/1/Documentation/contributor/source... Documentation/contributor/source-code.itexi:348: git merge master Or, if you want to show all these commands, just make the last one `git rebase master` because the merge might create a "loop" in the history. http://codereview.appspot.com/5484043/diff/1/Documentation/contributor/source... Documentation/contributor/source-code.itexi:354: @subsubheading Save commits manually (optional) "Using patch files (the other option)" http://codereview.appspot.com/5484043/diff/1/Documentation/contributor/source... Documentation/contributor/source-code.itexi:401: git merge dev/cg We do not want exactly this. If the `pull` applies any new commits from savannah, then the following merge will create a loop in the history. We could do the `git pull -r` because the -r means rebase any local changes onto the end of the branch freshly pulled from savannah. Alternatively, the patch saved as a file could be applied to the local staging.
Sign in to reply to this message.
http://codereview.appspot.com/5484043/diff/1/Documentation/contributor/source... File Documentation/contributor/source-code.itexi (right): http://codereview.appspot.com/5484043/diff/1/Documentation/contributor/source... Documentation/contributor/source-code.itexi:401: git merge dev/cg > We could do the `git pull -r` because ... Should have said that we can do the `git pull -r` *last* .
Sign in to reply to this message.
thanks, Keith! I've made all the changes other than the two noted below. http://codereview.appspot.com/5484043/diff/1/Documentation/contributor/source... File Documentation/contributor/source-code.itexi (right): http://codereview.appspot.com/5484043/diff/1/Documentation/contributor/source... Documentation/contributor/source-code.itexi:344: @example On 2011/12/13 07:47:18, Keith wrote: > On branch dev/cg, simply > git pull -r that gives me a complaint that I haven't told it which branch to rebase against. I know I could set up something fancy in .git/config to auto-rebase against origin/master or something like that, but I'd rather keep the instructions usable against a plain git clone git://...lilypond.git Revised instructions going up in a few minutes, which I think resolves this. http://codereview.appspot.com/5484043/diff/1/Documentation/contributor/source... Documentation/contributor/source-code.itexi:354: @subsubheading Save commits manually (optional) On 2011/12/13 07:47:18, Keith wrote: > "Using patch files (the other option)" I'd rather not offer that option -- given another 1 or 2 drafts, I think we can have the branch-based solution being simple enough that there's no need for patch files. I totally want to keep this section in terms of "making a backup" for people (like me) who aren't familiar enough with git to trust it. But I'd rather frame it as *only* a backup method.
Sign in to reply to this message.
Second draft uploaded; more robust with rebases instead of merge. Question: the old docs want translators to avoid rebasing for some reason. Is that reason still valid? Because it would be very nice if we didn't have to have a separate section of "git for translators". http://lilypond.org/doc/v2.15/Documentation/contributor/pulling-and-rebasing
Sign in to reply to this message.
On 12/13/11 7:06 AM, "graham@percival-music.ca" <graham@percival-music.ca> wrote: >Second draft uploaded; more robust with rebases instead of merge. > >Question: the old docs want translators to avoid rebasing for some >reason. Is that reason still valid? Because it would be very nice if >we didn't have to have a separate section of "git for translators". >http://lilypond.org/doc/v2.15/Documentation/contributor/pulling-and-rebasi >ng For some reason, which I don't understand, tranlsations are *always* added to master as a merge commit. For this reason, you don't want to do git pull -r Perhaps Francisco or John can shed more light on this subject. Thanks, Carl
Sign in to reply to this message.
2011/12/13 Carl Sorensen <c_sorensen@byu.edu>: > > > On 12/13/11 7:06 AM, "graham@percival-music.ca" <graham@percival-music.ca> > wrote: > >>Second draft uploaded; more robust with rebases instead of merge. >> >>Question: the old docs want translators to avoid rebasing for some >>reason. Is that reason still valid? Because it would be very nice if >>we didn't have to have a separate section of "git for translators". >>http://lilypond.org/doc/v2.15/Documentation/contributor/pulling-and-rebasi >>ng > > For some reason, which I don't understand, tranlsations are *always* added > to master as a merge commit. > > For this reason, you don't want to do git pull -r > > Perhaps Francisco or John can shed more light on this subject. Not too much light, I'm afraid. John always merged. I just kept on merging. I've got used to see merge commits for ages before I did them by myself, so I never thought about modifying this workflow. If merge commits are undesirable for any reason and you have sorted out on a clean batch of commands to run instead, I am all for changing to that from now on. Merge commits are easy for me because you don't have to give an explicit ID as an argument to the git command, only the branch name. -- Francisco Vila. Badajoz (Spain) www.paconet.org , www.csmbadajoz.com
Sign in to reply to this message.
2011/12/14 Francisco Vila <paconet.org@gmail.com>: > 2011/12/13 Carl Sorensen <c_sorensen@byu.edu>: >> >> >> On 12/13/11 7:06 AM, "graham@percival-music.ca" <graham@percival-music.ca> >> wrote: >>>Second draft uploaded; more robust with rebases instead of merge. >>> >>>Question: the old docs want translators to avoid rebasing for some >>>reason. Is that reason still valid? Because it would be very nice if >>>we didn't have to have a separate section of "git for translators". >>>http://lilypond.org/doc/v2.15/Documentation/contributor/pulling-and-rebasi >>>ng >> >> For some reason, which I don't understand, tranlsations are *always* added >> to master as a merge commit. >> >> For this reason, you don't want to do git pull -r Note that the text talks about translation committishes. Translators need to know how an original file did change since he last updated his translation. This is what committishes are for. The 'make check-translation' script does the task of displaying those differences by means of a mark we put on each translated doc, which is a ref to the commit ID of the original. So what we want to achieve here is that our committishes always are refs to published originals in Savannah, rather than to unpublished, local originals. Otherwise we'd be pushing translations that we are nor going able to track from originals' changes. How 'git pull' alone does get it and 'git pull -r' ruins it, is something outside of my current level of knowledge. -- Francisco Vila. Badajoz (Spain) www.paconet.org , www.csmbadajoz.com
Sign in to reply to this message.
I did say earlier that git rebase was analogous to saving a series of commits and applying them, but there is a difference in that `git rebase http://codereview.appspot.com/5484043/diff/7001/Documentation/contributor/sou... File Documentation/contributor/source-code.itexi (right): http://codereview.appspot.com/5484043/diff/7001/Documentation/contributor/sou... Documentation/contributor/source-code.itexi:446: git rebase dev/cg This makes the history of commits linear, but in the wrong order. (It puts any new commits from the repository /after/ the new commits from dev/cg -- and any conflict resolution would change the commits from the repository.) Git changes the branch that is checked-out, and we want to change the sequence of commits developers branch, so git checkout dev/cg git rebase staging git checkout staging gitk
Sign in to reply to this message.
I did say earlier that git rebase was analogous to saving a series of commits and applying them, but there is a difference in that `git rebase http://codereview.appspot.com/5484043/diff/7001/Documentation/contributor/sou... File Documentation/contributor/source-code.itexi (right): http://codereview.appspot.com/5484043/diff/7001/Documentation/contributor/sou... Documentation/contributor/source-code.itexi:446: git rebase dev/cg This makes the history of commits linear, but in the wrong order. (It puts any new commits from the repository /after/ the new commits from dev/cg -- and any conflict resolution would change the commits from the repository.) Git changes the branch that is checked-out, and we want to change the sequence of commits developers branch, so git checkout dev/cg git rebase staging git checkout staging gitk
Sign in to reply to this message.
A few comments, but otherwise LGTM http://codereview.appspot.com/5484043/diff/7001/Documentation/contributor/sou... File Documentation/contributor/source-code.itexi (right): http://codereview.appspot.com/5484043/diff/7001/Documentation/contributor/sou... Documentation/contributor/source-code.itexi:318: @qq{profit}, I mean @qq{push stuff to staging}. i don't understand how switching branches has anything to do with pushing to staging. http://codereview.appspot.com/5484043/diff/7001/Documentation/contributor/sou... Documentation/contributor/source-code.itexi:446: git rebase dev/cg On 2011/12/16 05:52:34, Keith wrote: > This makes the history of commits linear, but in the wrong order. (It puts any > new commits from the repository /after/ the new commits from dev/cg -- and any > conflict resolution would change the commits from the repository.) > > Git changes the branch that is checked-out, and we want to change the sequence > of commits developers branch, so > git checkout dev/cg > git rebase staging > git checkout staging > gitk +1, this makes much more sense
Sign in to reply to this message.
|
