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

[janek . lilypond]

Some thoughts on making all this less confusing to beginners.


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
could we change this (and other similar) prefix so that it doesn't
contain a slash?  I mean, change dev/ to dev- or something like that.
The slash confused me a lot, because it's also used to separate a remote
name from the branch name, like in origin/master.  I'm sure that if we
will adopt "dev/blahblah" naming, many people will mistakenly believe
that "dev" is something like "origin", and they will be very confused.

http://codereview.appspot.com/5539062/diff/3004/Documentation/contributor/source-code.itexi#newcode297
Documentation/contributor/source-code.itexi:297: git branch dev/cg
I think it would be good to be verbose, because it will give people more
information about using git (and they won't have to ask certain
questions).  In this case i would suggest

git branch dev/cg --track origin/master

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}.
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.

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:
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:"

http://codereview.appspot.com/5539062/diff/3004/Documentation/contributor/source-code.itexi#newcode360
Documentation/contributor/source-code.itexi:360: @subsubheading Save
commits manually (optional)
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)

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
Insert "After you committed your changes, you can..."

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

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:
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.

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:
"Make sure that you're on your branch and upload:"

I think this won't make an impression that checkout command is a part of
actual uploading process.

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 don't think this title is clear (what history is it and how can i tell
if i have broken commits?)

Maybe "rearranging 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:
maybe "push it to the staging branch located on remote origin"?  This
will give contributor more information about what he is doing (= less
questions to answer).

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
"never rebase 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.}
Maybe add
"(notice ~0 added to rebase command)"

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