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/ _______________________________________________ lilypond-devel mailing list [email protected] https://lists.gnu.org/mailman/listinfo/lilypond-devel
