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

[Graham Percival]

On Tue, Jan 17, 2012 at 08:24:35PM +0000, address@hidden wrote:
> 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.

Good point!  I like it.

> 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

But we don't want it to track origin/master, do we?  People should
merge from master manually (covered in this section).

> 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 don't mind removing it...

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

... but *this* confuses me.  How can git switch to a remote
branch?  Aren't all branches local?  I mean, whenever you switch
to a "remote" branch, doesn't that just create a local copy of the
remote branch, then put you on that local branch?

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

That's much more verbose, and it only affects 1% of git usage.
There's certainly a better wording than what is written currently,
but I don't think this is it.

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

Good idea!

> 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)

+1

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

I think that mentioning "local" or "remote" will only add
confusion.  The goal is not to explain how to use git; the goal is
to let people use git as painlessly as possible.

- Graham