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

[Carl . D . Sorensen]

On 2012/01/17 20:31:24, Graham Percival wrote:
> On Tue, Jan 17, 2012 at 08:24:35PM +0000,
mailto: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.


I don't.  We have / as a directory indicator in file names, and we have
a whole bunch of branches on git that use / as the equivalent thing -- a
grouping of like branches (see, for example, stable/2.12, stable/2.14,
etc.

The / is perfectly consistent as a separator, and it works very similar
to / in unix.  dev/cg is a local branch dev/cg; origin/dev/cg is the
remote branch on origin.

I'd be fine with eliminating the separator, and just calling the branch
local-working (for example).  But at the origin of this all, Graham
wanted people used to putting stuff in dev/*, since origin/dev/* is
where individual users store there work on the public repository if they
want to.  Changing this to origin/dev- would be a mistake, in my
opinion.


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


We absolutely do *not* want tracking, in my opinon.  The only branch I
want tracking in a novice's repository is master.  And we give
instructions that they never merge to master -- only to staging.

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'll come up with some other wording.  I liked the light-hearted words,
but can see that non-native speakers would miss the idiom.


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

This isn't a git tutorial, but a using git with lilypond tutorial.  I'll
add something like
"You can create a local branch with your work on a particular issue to
facilitate patching, review, and merging with the main repository."

> >

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.

I'll think about it and propose changes.

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!

Will make the change.


> >

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


Will fix.

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.

IMO, the goal is to let people use git *to work on lilypond* as
painlessly as possible.  So it's fair (and desirable) to put in
specifics for the organization of our repositories.

Thanks,

Carl


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