[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: janek . lilypond
Subject: Re: Issue 2100: Explanation of branches for CG (issue 5539062)
Date: Tue, 17 Jan 2012 20:24:35 +0000

Some thoughts on making all this less confusing to beginners.
File Documentation/contributor/source-code.itexi (right):
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.
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
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
Documentation/contributor/source-code.itexi:345: Add a file, then commit
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:"
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)
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)
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.
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.
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"?
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).
Documentation/contributor/source-code.itexi:475: @warning{It is a best
practice to never rebase one of your branches
"never rebase your branches"?
Documentation/contributor/source-code.itexi:480: changing your working
Maybe add
"(notice ~0 added to rebase command)"

reply via email to

[Prev in Thread] Current Thread [Next in Thread]