Re: CG: explanation of branches for the impatient (issue 5484043)

[k-ohara5a5a]

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-code.itexi
File Documentation/contributor/source-code.itexi (right):

http://codereview.appspot.com/5484043/diff/1/Documentation/contributor/source-code.itexi#newcode215
Documentation/contributor/source-code.itexi:215: export PS1="address@hidden
\w\$(__git_ps1)$ "
requires git-completion to be installed

http://codereview.appspot.com/5484043/diff/1/Documentation/contributor/source-code.itexi#newcode280
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-code.itexi#newcode317
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-code.itexi#newcode338
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-code.itexi#newcode344
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-code.itexi#newcode348
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-code.itexi#newcode354
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-code.itexi#newcode401
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.

http://codereview.appspot.com/5484043/