Re: Issue 2100: Explanation of branches for CG (issue 5539062)

[Carl . D . Sorensen]

I've responded to comments.  Thanks for all the input.

Carl



http://codereview.appspot.com/5539062/diff/3004/Documentation/contributor/source-code.itexi
File Documentation/contributor/source-code.itexi (right):

http://codereview.appspot.com/5539062/diff/3004/Documentation/contributor/source-code.itexi#newcode291
Documentation/contributor/source-code.itexi:291: @code{dev/}.  Branch
names that don't begin with @code{dev/} are
As I said before, I like the /.  I have added text to describe the
special meaning of branches beginning with origin/.  I think that will
minimize confusion.

http://codereview.appspot.com/5539062/diff/3004/Documentation/contributor/source-code.itexi#newcode297
Documentation/contributor/source-code.itexi:297: git branch dev/cg
I have made the decision not to add the tracking.  I want rebasing to be
done manually, so the user knows when it has been done.

http://codereview.appspot.com/5539062/diff/3004/Documentation/contributor/source-code.itexi#newcode318
Documentation/contributor/source-code.itexi:318: @qq{profit}, I mean
@qq{push stuff to staging}.
On 2012/01/17 20:24:35, janek wrote:
> i think this fragment is irrelevant here.  It confuses me.

> I'd write something like
> "You can switch to your local branches and to the remote branches as
well"
> instead.

Done.

http://codereview.appspot.com/5539062/diff/3004/Documentation/contributor/source-code.itexi#newcode345
Documentation/contributor/source-code.itexi:345: Add a file, then commit
it:
On 2012/01/17 20:24:35, janek wrote:
> I'd write
> "by default, git commit -a only commits changes to the files that
existed before
> you made your changes.  If you want to include a file created by you
in the
> commit, use git add:"

Done.

http://codereview.appspot.com/5539062/diff/3004/Documentation/contributor/source-code.itexi#newcode360
Documentation/contributor/source-code.itexi:360: @subsubheading Save
commits manually (optional)
On 2012/01/17 20:24:35, janek wrote:
> I suggest changing this to
> "save commits to external files" or sth. like that.
> Now it looks like this section will be about doing what was described
above by
> hand (i.e. fiddling with git internals)

Done.

http://codereview.appspot.com/5539062/diff/3004/Documentation/contributor/source-code.itexi#newcode362
Documentation/contributor/source-code.itexi:362: Branches are
nerve-wracking until you get used to them.  You can
On 2012/01/17 20:24:35, janek wrote:
> Insert "After you committed your changes, you can..."

> (format-patch doesn't work with uncommitted changes)

Done.

http://codereview.appspot.com/5539062/diff/3004/Documentation/contributor/source-code.itexi#newcode377
Documentation/contributor/source-code.itexi:377: Update your branch with
the latest master:
On 2012/01/17 20:24:35, janek wrote:
> Maybe we should mention that there shouldn't be any uncommitted
changes before
> contributor tries to checkout master?  IIRC, when someone is on some
branch,
> makes changes but doesn't commit them, and checks out another branch,
these
> changes will "follow him" to this branch.  And with a dirty tree he
won't be
> able to pull.

Done.

http://codereview.appspot.com/5539062/diff/3004/Documentation/contributor/source-code.itexi#newcode377
Documentation/contributor/source-code.itexi:377: Update your branch with
the latest master:
On 2012/01/17 20:24:35, janek wrote:
> Maybe we should mention that there shouldn't be any uncommitted
changes before
> contributor tries to checkout master?  IIRC, when someone is on some
branch,
> makes changes but doesn't commit them, and checks out another branch,
these
> changes will "follow him" to this branch.  And with a dirty tree he
won't be
> able to pull.

Done.

http://codereview.appspot.com/5539062/diff/3004/Documentation/contributor/source-code.itexi#newcode396
Documentation/contributor/source-code.itexi:396: Make sure that you're
on your branch, then upload:
I prefer the original wording.  I think the "then" actually indicates
the sequential nature of the steps better than "and".

http://codereview.appspot.com/5539062/diff/3004/Documentation/contributor/source-code.itexi#newcode413
Documentation/contributor/source-code.itexi:413: @subsubheading Rewrite
history (optional unless you have broken commits)
I chose "Combining commits"

http://codereview.appspot.com/5539062/diff/3004/Documentation/contributor/source-code.itexi#newcode463
Documentation/contributor/source-code.itexi:463: If everything looks
good, push it:
I decided that adding the information is more likely to raise questions
than answer them.  This is just a recipe, or a magic spell.

http://codereview.appspot.com/5539062/diff/3004/Documentation/contributor/source-code.itexi#newcode475
Documentation/contributor/source-code.itexi:475: @warning{It is a best
practice to never rebase one of your branches
"avoid rebasing any of your branches"

http://codereview.appspot.com/5539062/diff/3004/Documentation/contributor/source-code.itexi#newcode480
Documentation/contributor/source-code.itexi:480: changing your working
branch.}
I decided it's too much information.  We're looking at copy and paste
here.

http://codereview.appspot.com/5539062/