X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fsource-code.itexi;h=250ad99d2e6ae476caa26d4d786b9728306ecac0;hb=c30d5621ede95d57d2259b006649d031fa4a0923;hp=ba1875c0d670392e71c52b1269a6eedc5f3b3e0b;hpb=33fd36cc8b74a2a0e80e43a8dc9dbfcb7d1f7df1;p=lilypond.git

diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi
index ba1875c0d6..250ad99d2e 100644
--- a/Documentation/contributor/source-code.itexi
+++ b/Documentation/contributor/source-code.itexi
@@ -5,7 +5,7 @@
 @chapter Working with source code
 
 @warning{New contributors should read @ref{Quick start}, and in
-particular @ref{Using lily-git}, instead of this chapter.}
+particular @ref{lily-git}, instead of this chapter.}
 
 Advanced contributors will find this material quite useful,
 particularly if they are working on major new features.
@@ -29,7 +29,7 @@ contributors.  If you are comfortable with the command-line, then
 skip ahead to @ref{Starting with Git}.
 
 @warning{These instructions are only for people who are @emph{not}
-using @ref{Lilydev}.}
+using @ref{LilyDev}.}
 
 @c there's some duplication in this section with stuff covered in
 @c Quick Start, but moving it into a macro inside included/ would
@@ -65,9 +65,9 @@ Download the @command{lily-git.tcl} script from:
 @c don't change the cgit link below to gitweb; gitweb uses
 @c long filenames like "scripts_auxiliar_lily-git.tcl"
 
-@example
+@smallexample
 @uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
-@end example
+@end smallexample
 
 @item
 To run the program from the command line, navigate to the
@@ -82,7 +82,7 @@ Click on the @qq{Get source} button.
 
 This will create a directory called @file{lilypond-git/} within
 your home directory, and will download the source code into that
-directory (around 55Mb).  When the process is finished, the
+directory (around 150@tie{}Mb).  When the process is finished, the
 @qq{Command output} window will display @qq{Done}, and the button
 label will change to say @qq{Update source}.
 
@@ -93,17 +93,10 @@ files.
 @end enumerate
 
 @warning{Throughout the rest of this manual, most command-line
-input should be entered from @file{~/lilypond-git/}.  This is
+input should be entered from @file{$LILYPOND_GIT}.  This is
 referred to as the @emph{top source directory}.}
 
-Further instructions are in @ref{Daily use of lily-git.tcl}.
-
-@advanced{the @qq{Get source} button does not fetch the entire
-history of the git repository, so utilities like @command{gitk}
-will only be able to display the most recent additions.  As you
-continue to work with @command{lily-git.tcl}, the @qq{Update
-source} button will take any new additions and add it to whatever
-is currently in your repository's history.}
+Further instructions are in @ref{How to use lily-git}.
 
 
 @node Starting with Git
@@ -118,6 +111,8 @@ multiple projects concurrently.
 
 @menu
 * Setting up::
+* Git for the impatient::
+* Other repositories::
 * Downloading remote branches::
 @end menu
 
@@ -125,10 +120,6 @@ multiple projects concurrently.
 @node Setting up
 @subsection Setting up
 
-
-TODO: Remove this note if incorporating Windows instructions
-throughout this section:
-
 @warning{These instructions assume that you are using the
 command-line version of Git 1.5 or higher.  Windows users should
 skip to @ref{Git on Windows}.}
@@ -143,10 +134,9 @@ skip to @ref{Git on Windows}.}
 @node Installing Git
 @unnumberedsubsubsec Installing Git
 
-
 If you are using a Unix-based machine, the easiest way to download
 and install Git is through a package manager such as @command{rpm}
-or @command{apt-get}---the installation is generally automatic.
+or @command{apt-get} -- the installation is generally automatic.
 The only required package is (usually) called @command{git-core},
 although some of the auxiliary @command{git@var{*}} packages are
 also useful (such as @command{gitk}).
@@ -155,28 +145,22 @@ Alternatively, you can visit the Git website
 (@uref{http://git-scm.com/}) for downloadable binaries and
 tarballs.
 
-TODO: add Windows installation instructions (or @@ref@{Git on
-Windows@}).
-
 
 @node Initializing a repository
 @unnumberedsubsubsec Initializing a repository
 
-
-Once Git is installed, you'll need to create a new directory where
-your initial repository will be stored (the example below uses
-@file{~/lilypond-git/}, where @code{~} represents your home
-directory).  Run @command{git@tie{}init} from within the new
-directory to initialize an empty repository:
+Once Git is installed, get a copy of the source code:
 
 @example
-mkdir ~/lilypond-git/; cd ~/lilypond-git/
-git init
+git clone git://git.sv.gnu.org/lilypond.git ~/lilypond-git
 @end example
 
+The above command will put the it in @file{~/lilypond-git}, where
+@code{~} represents your home directory.
+
 @subsubheading Technical details
 
-This creates (within the @file{~/lilypond-git/} directory) a
+This creates (within the @file{$LILYPOND_GIT} directory) a
 subdirectory called @file{.git/}, which Git uses to keep track of
 changes to the repository, among other things.  Normally you don't
 need to access it, but it's good to know it's there.
@@ -187,16 +171,16 @@ need to access it, but it's good to know it's there.
 
 @warning{Throughout the rest of this manual, all command-line
 input should be entered from the top directory of the Git
-repository being discussed (eg. @file{~/lilypond-git/}).  This is
+repository being discussed (eg. @file{$LILYPOND_GIT}).  This is
 referred to as the @emph{top source directory}.}
 
-Before downloading a copy of the main LilyPond repository, you
+Before working with the copy of the main LilyPond repository, you
 should configure some basic settings with the
 @command{git@tie{}config} command.  Git allows you to set both
 global and repository-specific options.
 
 To configure settings that affect all repositories, use the
-@command{--global} command line option.  For example, the first
+@option{--global} command line option.  For example, the first
 two options that you should always set are your @var{name} and
 @var{email}, since Git needs these to keep track of commit
 authors:
@@ -224,8 +208,18 @@ change the default editor to @command{nano}, enter:
 git config --global core.editor @var{nano}
 @end example
 
-TODO: Add instructions for changing the editor on Windows, which
-is a little different, I think. -mp
+Finally, and in some ways most importantly, let's make sure that
+we know what branch we're on.  If you're not using LilyDev, add
+this to your @file{~/.bashrc}:
+
+@verbatim
+export PS1="\u@\h \w\$(__git_ps1)$ "
+@end verbatim
+
+You may need to install the additional @code{bash-completion}
+package, but it is definitely worth it.  After installation
+you must log out, and then log back in again to enable it.
+
 
 @subsubheading Technical details
 
@@ -247,7 +241,7 @@ by the above commands would look like this:
 @end example
 
 Using the @command{git@tie{}config} command @emph{without} the
-@command{--global} option configures repository-specific settings,
+@option{--global} option configures repository-specific settings,
 which are stored in the file @file{.git/config}.  This file is
 created when a repository is initialized (using
 @command{git@tie{}init}), and by default contains these lines:
@@ -266,9 +260,402 @@ setting any now.  Specific recommendations will be mentioned later
 in this manual.
 
 
+@node Git for the impatient
+@subsection Git for the impatient
+
+@advanced{The intent of this subsection is to get you working on lilypond as
+soon as possible.  If you want to learn about git, go read
+@ref{Other Git documentation}.
+@*
+Also, these instructions are designed to eliminate the most common
+problems we have found in using git.  If you already know git and
+have a different way of working, great!  Feel free to ignore the
+advice in this subsection.}
+
+
+Ok, so you've been using @command{lily-git.tcl} for a while, but
+it's time to take the next step.  Since our review process delays
+patches by 60-120 hours, and you want to be able to work on other
+stuff while your previous work is getting reviewed, you're going
+to use @strong{branches}.
+
+You can think of a branch as being a separate copy of the source
+code.  But don't worry about it.
+
+@subsubheading Start work: make a new branch
+
+Let's pretend you want to add a section to the Contributor's Guide
+about using branches.
+
+Start by updating the repository, then making a new branch.  Call
+the branch anything you want as long as the name starts with
+@code{dev/}.  Branch names that don't begin with @code{dev/} are
+reserved for special things in lilypond.
+
+@example
+git checkout master
+git pull -r origin master
+git branch dev/cg
+@end example
+
+@subsubheading Switch to that branch
+
+Nothing has happened to the files yet.  Let's change into the new
+branch.  You can think of this as @qq{loading a file}, although in
+this case it's really @qq{loading a directory and subdirectories
+full of files}.
+
+@example
+git checkout dev/cg
+@end example
+
+Your prompt now shows you that you're on the other branch:
+
+@example
+gperciva@@LilyDev:~/lilypond-git (dev/cg)$
+@end example
+
+To be able to manage multiple lilypond issues at once, you'll need to switch
+branches.  You should have each lilypond issue on a separate branch.
+Switching branches is easy:
+
+@example
+git checkout master
+git checkout origin/staging
+git checkout origin/release/unstable
+git checkout dev/cg
+@end example
+
+Branches that begin with @code{origin/} are part of the remote repository,
+rather than your local repository, so when you check them out you get a 
+temporary local branch.  You should never make changes directly on a
+branch beginning with @code{origin/}.  You get changes into the remote
+repository by making them in local branches, and then pushing them to
+@code{origin/staging} as described below. 
+
+@subsubheading Make your changes
+
+Edit files, then commit them.
+
+@example
+git commit -a
+@end example
+
+
+Remember how I said that switching to a branch was like
+@qq{loading a directory}?  Well, you've just @qq{saved a
+directory}, so that you can @qq{load} it later.
+
+@advanced{If you have used @command{cvs} or @command{svn}, you may
+be very confused: those programs use @qq{commit} to mean
+@qq{upload my changes to the shared source repository}.
+Unfortunately, just to be different, @w{@command{git commit}}
+means @qq{save my changes to the files}.}
+
+When you create a new file, you need to add it to git, then commit it:
+
+@example
+git add input/regression/avoid-crash-on-condition.ly
+git commit -a
+@end example
+
+
+Edit more files.  Commit them again.  Edit yet more files, commit
+them again.  Go eat dinner.  Switch to @code{master} so you can
+play with the latest changes from other developers.  Switch back
+to your branch and edit some more.  Commit those changes.
+
+At this stage, don't worry about how many commits you have.
+
+
+@subsubheading Save commits to external files
+
+Branches are nerve-wracking until you get used to them.  You can
+save your hard work as individual @file{.patch} files.  Be sure to
+commit your changes first.
+
+@example
+git commit -a
+git format-patch master
+@end example
+
+I personally have between 4 and 20 of those files saved in a
+special folder at any point in time.  Git experts might laugh as
+that behavior, but I feel a @emph{lot} better knowing that I've
+got those backups.
+
+
+@subsubheading Prepare your branch for review
+
+After committing, you can update your branch with the latest master:
+
+@example
+git commit -a
+git checkout master
+git pull -r origin master
+git checkout dev/cg
+git rebase master
+@end example
+
+
+Due to the speed of lilypond development, sometimes
+@code{master} has changed so much that your branch can no
+longer be applied to it.  In that happens, you will have a merge
+conflict.  Stop for a moment to either cry or have a stiff drink,
+then proceed to @ref{Merge conflicts}.
+
+
+@subsubheading Upload your branch
+
+Finally, you're finished your changes.  Time to upload for review.
+Make sure that you're on your branch, then upload:
+
+@example
+git checkout dev/cg
+git-cl upload master
+@end example
+
+
+@subsubheading Wait for reviews
+
+While you're waiting for a countdown and reviews, go back to
+master, make a @code{dev/doc-beams} branch, and start adding doc
+suggestions from issue 12345 from the tracker.  Or make a
+@code{dev/page-breaks} and fix bug in page breaking.  Or whatever.
+Don't worry, your @code{dev/cg} is safe.
+
+
+@subsubheading Combining commits (optional unless you have broken commits)
+
+Does the history of your branch look good?
+
+@example
+gitk
+@end example
+
+If you have a lot of commits on your branch, you might want to
+combine some of them.  Alternately, you may like your commits, but
+want to edit the commit messages.
+
+@example
+git rebase -i master
+@end example
+
+Follow instructions on the screen.
+
+@warning{This step gives you the power to completely lose your
+work.  Make a backup of your commits by saving them to
+@file{.patch} files before playing with this.  If you do lose
+your work, don't despair.  You can get it back by using @code{git reflog}.
+The use of @code{git reflog} is not covered here.}
+
+@warning{If any of the commits on your branch represent partial work that will
+not pass @var{make && make doc}, you @strong{must} squash these 
+commits into a working commit.  Otherwise, your push will break staging
+and will not be able to be merged to master.  In general, you will
+be safer to have one commit per push.}
+
+
+@subsubheading Push to staging
+
+When you've got the coveted @code{Patch-push} status, time to
+prepare your upload:
+
+@example
+git fetch
+git rebase origin/staging dev/cg~0
+gitk HEAD 
+@end example
+
+@warning{Do not skip the @command{gitk} step; a quick 5-second
+check of the visual history can save a great deal of frustration
+later on.  You should see a set of your commits that are ahead of
+@code{origin/staging}, with no label for the top commit -- only a
+SHA1 id.}
+
+@warning{If @code{origin/staging} and @code{origin/master} are the
+same commit, your branch (@code{dev/cg} in the example) will also
+be at the top of the @code{gitk} tree.  This is normal.}
+
+If everything looks good, push it:
+
+@example
+git push origin HEAD:staging
+@end example
+
+Then change back to your working branch:
+
+@example
+git checkout dev/cg
+@end example
+
+@warning{It is a best practice to avoid rebasing any of your branches
+to @code{origin/staging}.  If @code{origin/staging} is broken, it
+will be deleted and rebuilt.  If you have rebased one of your branches
+to @code{origin/staging}, the broken commits can end up in your branch.
+The commands given above do the rebase on a temporary branch, and avoid
+changing your working branch.}
+
+
+@subsubheading Delete your branch (safe)
+
+After a few hours, if there's nothing wrong with your branch, it
+should be automatically moved to @code{origin/master}.  Update,
+then try removing your branch:
+
+@example
+git checkout master
+git pull -r origin master
+git branch -d dev/cg
+@end example
+
+The last command will fail if the contents of @code{dev/cg} are
+not present in @code{origin/master}.
+
+
+@subsubheading Delete your branch (UNSAFE)
+
+@c don't give explicit commands here -- this is too dangerous to copy and paste
+Sometimes everything goes wrong.  If you want to remove a branch even though 
+it will cause your work to be lost (that is, if the contents of @code{dev/cg}
+are @strong{not} present in master), follow the instructions in @qq{Delete
+your branch (safe)}, but replace the @code{-d} on the final line with 
+a @code{-D}.
+
+
+@node Other repositories
+@subsection Other repositories
+
+We have a few other code repositories.
+
+@menu
+* lilypond-extra::
+* Grand Unified Builder (GUB)::
+* LilyPad::
+* yet more repositories::
+@end menu
+
+@node lilypond-extra
+@unnumberedsubsubsec lilypond-extra
+
+There is a separate repository for general administrative scripts,
+as well as pictures and media files for the website.  People
+interested in working on the website should download this
+repository, and set their @code{$LILYPOND_WEB_MEDIA_GIT}
+environment variable to point to that repository.
+
+@example
+@uref{https://github.com/gperciva/lilypond-extra}
+@end example
+
+To configure an environment variable in bash (the default for most
+GNU/Linux distributions),
+
+@example
+export LILYPOND_WEB_MEDIA_GIT=$HOME/dir/of/lilypond-extra/
+@end example
+
+Be aware that @code{lilypond-extra} is the definitive source for some binary
+files - in particular PDF versions of papers concerning LilyPond.  To add
+further PDFs of this sort, all that is necessary is to add the PDF to
+@code{lilypond-extra} and then add a reference to it in the documentation.  The
+file will then be copied to the website when @code{make website} is run.
+
+However, pictures that are also used in the documentation build are mastered in
+the main git repository.  If any of these is changed, it should be updated in
+git, and then the updates copied to @code{lilypond-extra}.
+
+@node Grand Unified Builder (GUB)
+@unnumberedsubsubsec Grand Unified Builder (GUB)
+
+Another item of interest might be the Grand Unified Builder, our
+cross-platform building tool.  Since it is used by other projects as
+well, it is not stored in our gub repository.  For more info, see
+@uref{http://lilypond.org/gub}.
+
+There are two locations for this repository: the version being used to
+build lilypond, which is at
+
+@example
+@uref{http://github.com/gperciva/gub}
+@end example
+
+and the original version by Jan Nieuwenhuizen, kept at
+
+@example
+@uref{http://github.com/janneke/gub}
+@end example
+
+
+@node LilyPad
+@unnumberedsubsubsec LilyPad
+
+Our binary releases on MacOS X and Windows contain a lightweight
+text editor.
+
+To make any modifications the Windows editor, you will need to do the
+following:
+
+@enumerate
+@item
+Clone the git repository from @code{https://github.com/gperciva/lilypad}
+
+@item
+Make changes to the source, and check it compiles.  In a Windows environment
+@code{MinGW} provides both a @code{Git} installation and a @code{gcc}
+compiler.  This can be obtained from @code{http://www.mingw.org/}
+
+@item
+Update the version which is contained in the @file{rsrc.rc}.  Check
+this compiles, too.
+
+@item
+Commit the changes with an informative commit message.
+
+@item
+Push the changes to github.  You will need to use syntax similiar to this:
+
+@example
+git push https://UserName@@github.com/gperciva/lilypad.git
+@end example
+
+You will need to have push access to the git repository for this to be
+successful.
+
+@item
+Make a tarball of the source code to be used by GUB by pulling the updated
+repository from GitHub.  Ensure that the tarball has the correct Version
+number.
+
+@item
+Copy the tarball to @code{http://lilypond.org/download/gub-sources/lilypad/}.
+You will need to have SSH access to @code{lilypond.org}.  If you do not, contact
+the Release Manager via the lilypond-devel mailing list.
+
+@item
+Update GUB to make it use the new tarball by editing
+@file{gub/specs/lilypad.py} and changing the @code{source =} line to point to
+the new source.
+
+@item
+Push this updated @file{lilypad.py} version to the GUB repository on GitHub.
+
+@item
+Test the changes with a new GUB compile.
+
+@end enumerate
+
+@node yet more repositories
+@unnumberedsubsubsec yet more repositories
+
+There are a few other repositories floating around, which will
+hopefully be documented in the near future.
+
+
 @node Downloading remote branches
 @subsection Downloading remote branches
 
+@warning{contains obsolete + misleading info}
 
 @menu
 * Organization of remote branches::
@@ -294,13 +681,13 @@ development releases), the documentation (and its translations),
 and the website.  Generally, the @code{master} branch is expected
 to compile successfully.
 
-The @code{lilypond/translation} branch is a side branch that
+The @code{translation} branch is a side branch that
 allows translators to work without needing to worry about
 compilation problems.  Periodically, the Translation Meister
 (after verifying that it doesn't break compilation), will
-@emph{merge} this branch back into @code{master} to incorporate
+@emph{merge} this branch into @code{staging} to incorporate
 recent translations.  Similarly, the @code{master} branch is
-usually merged into the @code{lilypond/translation} branch after
+usually merged into the @code{translation} branch after
 significant changes to the English documentation.  See
 @ref{Translating the documentation} for details.
 
@@ -333,6 +720,8 @@ only be used as a last resort.
 @node Downloading individual branches
 @unnumberedsubsubsec Downloading individual branches
 
+@warning{obsolete, should be deleted!}
+
 
 Once you have initialized an empty Git repository on your system
 (see @ref{Initializing a repository}), you can download a remote
@@ -346,11 +735,11 @@ git remote add -ft master -m master \
   origin git://git.sv.gnu.org/lilypond.git/
 @end example
 
-To download the @code{lilypond/translation} branch, enter:
+To download the @code{translation} branch, enter:
 
 @example
-git remote add -ft lilypond/translation -m \
-  lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
+git remote add -ft translation -m \
+  translation origin git://git.sv.gnu.org/lilypond.git/
 @end example
 
 The @command{git@tie{}remote@tie{}add} process could take up to
@@ -388,7 +777,7 @@ git checkout -b @var{branch} origin/@var{branch}
 
 @noindent
 where @code{@var{branch}} is the name of your tracking branch,
-either @code{master} or @code{lilypond/translation}.
+either @code{master} or @code{translation}.
 
 Git will issue some warnings; this is normal:
 
@@ -400,7 +789,7 @@ Already on 'master'
 @end example
 
 By now the source files should be accessible---you should be able
-to edit any files in the @file{lilypond-git/} directory using a
+to edit any files in the @file{$LILYPOND_GIT} directory using a
 text editor of your choice.  But don't start just yet!  Before
 editing any source files, learn how to keep your changes organized
 and prevent problems later---read @ref{Basic Git procedures}.
@@ -445,13 +834,10 @@ branch.
 @item @code{stable/XYZ}:
 The branches are kept for archival reasons.
 
-@end itemize
+@item @code{archive/XYZ}:
+The branches are kept for archival reasons.
 
-Another item of interest might be the Grand Unified Builder, our
-cross-platform building tool.  Since it is used by projects as
-well, it is not stored in our gub repository.  For more info, see
-@uref{http://lilypond.org/gub}.  The git location is
-@uref{http://github.com/janneke/gub}.
+@end itemize
 
 
 @node Basic Git procedures
@@ -522,7 +908,7 @@ git pull    # recommended for translators
 @end example
 
 If you're tracking the remote @code{master} branch, you should add
-the @code{-r} option (short for @code{--rebase}) to keep commits
+the @option{-r} option (short for @option{--rebase}) to keep commits
 on your local branch current:
 
 @example
@@ -530,7 +916,7 @@ git pull -r # use with caution when translating
 @end example
 
 If you don't edit translated documentation and don't want to type
-@code{-r} every time, configure the master branch to rebase by
+@option{-r} every time, configure the master branch to rebase by
 default with this command:
 
 @example
@@ -575,7 +961,7 @@ changed committishes in the head of translated files using commits
 you have not yet pushed to @code{git.sv.gnu.org}, please do not
 rebase.  If you want to avoid wondering whether you should rebase
 each time you pull, please always use committishes from master
-and/or lilypond/translation branch on @code{git.sv.gnu.org}, which
+and/or translation branch on @code{git.sv.gnu.org}, which
 in particular implies that you must push your changes to
 documentation except committishes updates (possibly after having
 rebased), then update the committishes and push them.}
@@ -629,7 +1015,7 @@ git branch -d @var{name}
 @end example
 
 Git will ask you for confirmation if it sees that data would be
-lost by deleting the branch.  Use @code{-D} instead of @code{-d}
+lost by deleting the branch.  Use @option{-D} instead of @option{-d}
 to bypass this.  Note that you cannot delete a branch if it is
 currently checked out.
 
@@ -695,12 +1081,11 @@ git merge @var{foo}
 
 If any conflict happens, see @ref{Resolving conflicts}.
 
-There are common usage cases for merging: as a translator, you
-will often want to merge @code{master} into
-@code{lilypond/translation}; on the other hand, the Translations
-meister wants to merge @code{lilypond/translation} into
-@code{master} whenever he has checked that
-@code{lilypond/translation} builds successfully.
+There are common usage cases for merging: as a translator, you will
+often want the Translations meister to merge @code{master} into
+@code{translation}; on the other hand, the Translations meister wants
+to merge @code{translation} into @code{staging} whenever he has
+checked that @code{translation} builds successfully.
 
 
 @node Commits and patches
@@ -801,7 +1186,7 @@ git commit -a
 @end example
 
 @noindent
-The @code{-a} is short for @code{--all} which includes modified
+The @option{-a} is short for @option{--all} which includes modified
 and deleted files, but only those newly created files that have
 previously been added.
 
@@ -873,7 +1258,7 @@ We prefer it if you follow the instructions in
 alternate method here.
 
 You should always run @command{git@tie{}pull@tie{}-r} (translators
-should leave off the @code{-r}) before doing this to ensure that
+should leave off the @option{-r}) before doing this to ensure that
 your patches are as current as possible.
 
 Once you have made one or more commits in your local repository,
@@ -924,14 +1309,28 @@ LilyDev users should skip over these @q{install} instructions.
 Install @command{git-cl} by entering:
 
 @example
-git clone git://neugierig.org/git-cl.git
+git clone https://github.com/gperciva/git-cl.git
+@end example
+
+If that command fails for some reason, try this instead:
+
+@example
+git clone git://github.com/gperciva/git-cl.git
 @end example
 
 @item
-Add the @file{git-cl/} directory to your PATH, or create a
-symbolic link to the @command{git-cl} and @command{upload.py}
-scripts in one of your PATH directories (such as
-@file{$HOME/bin}).
+Add the @file{git-cl/} directory to your PATH,
+or create a symbolic link to the @command{git-cl}
+and @command{upload.py} scripts in one of your PATH
+directories (such as @file{$HOME/bin}).
+
+In GNU/Linux you can add directories to PATH
+by adding this line to a hidden file @file{.bashrc},
+located in your home directory:
+
+@example
+PATH=~/type-here-directory-containing-git-cl:"$@{PATH@}"
+@end example
 
 @end enumerate
 
@@ -941,25 +1340,45 @@ LilyDev users should perform these @q{configuration} instructions.
 
 @enumerate
 @item
-You must have a gmail account; please create one if you do not
+You must own a Google account login; please create one if you do not
 have one already.
 
+@noindent
+Note that a google account does not need to be a Gmail account; you can
+use @emph{any} email address for your google account when you sign up.
+
+@warning{In order for @code{git-cl} to work as expected, your Google
+Account Settings must have the @q{Access for less secure apps} set to
+@q{Allowed}.  This is normally the default setting.}
+
 @item
 Move into the top source directory and then configure @command{git
-cl} with the following commands.  If you do not understand any
-question, just answer with a newline (CR).
+cl} with the following commands:
+
+@item
+Move into the top source directory and then configure @command{git
+cl} with the following commands:
 
 @example
-cd $HOME/lilypond-git/
+cd $LILYPOND_GIT
 git cl config
 @end example
 
+For the @qq{Rietveld server} question, the default value
+(@qq{codereview.appspot.com}) should be accepted by
+answering with a newline (CR).
+
 The @qq{CC list} question should be answered with:
 
 @example
 lilypond-devel@@gnu.org
 @end example
 
+The @qq{Tree status URL} value should be left blank.  So should
+the @qq{ViewVC URL} value, since it is used by @command{git cl
+dcommit} which is only for repositories which use @command{git
+svn} (LilyPond doesn't).
+
 @end enumerate
 
 @subsubheading Uploading patch set
@@ -980,10 +1399,18 @@ git pull -r
 git cl upload origin/master
 @end example
 
+@c Mention staging here?
 If you have git push ability, make sure that you @emph{remove}
 your patch (with @command{git rebase} or @command{git reset})
 before pushing other stuff.
 
+@c don't make this one an @example; we don't want to make it easy
+@c for people to use this accidently
+Notifications of patches are automatically added to our issue
+tracker to reduce the chance of patches getting lost.  To suppress
+this (not recommended), add the @code{-n / --no-code-issue}
+option.
+
 @item
 @strong{Separate branch}: (complicated option)
 
@@ -1013,14 +1440,19 @@ can be used.
 
 @end itemize
 
+First you will see a terminal editor where you can edit the
+message that will accompany your patch. @command{git-cl} will
+respect the @env{EDITOR} environment variable if defined,
+otherwise it will use @command{vi} as the default editor.
+
 After prompting for your Google email address and password, the
 patch set will be posted to Rietveld, and you will be given a URL
 for your patch.
 
 @warning{Some installations of git-cl fail when uploading a patch
-set that includes a .scm file.  When this happens, it can
-generally be fixed by editing the file @file{/etc/mime.types}.
-Add a line to this file containing @code{text/x-script.scheme scm}.}
+with certain filename extensions.  If this happens, it can
+generally be fixed by editing the list of exceptions at top of
+@file{git-cl.py}.}
 
 @subsubheading Announcing your patch set
 
@@ -1060,6 +1492,23 @@ running:
 git cl issue 0
 @end example
 
+@subsubheading Wait for a countdown
+
+Your patch will be available for reviews for the next few hours or
+days.  Three times a week, patches with no known problems are
+gathered into a @qq{patch countdown} and their status changed to
+@code{patch-countdown}.  The countdown is a 48-hour waiting period
+in which any final reviews or complaints should be made.
+
+During the countdown, your patch may be set to
+@code{patch-needs_work}, indicating that you should fix something
+(or at least discuss why the patch needs no modification).  If no
+problems are found, the patch will be set to @code{patch-push}.
+
+Once a patch has @code{patch-push}, it should be sent to your
+mentor for uploading.  If you have git push ability, look at
+@ref{Pushing to staging}.
+
 
 @node Advanced Git procedures
 @section Advanced Git procedures
@@ -1071,7 +1520,7 @@ in learning more about git.}
 
 It is possible to work with several branches on the same local Git
 repository; this is especially useful for translators who may have
-to deal with both @code{lilypond/translation} and a stable branch,
+to deal with both @code{translation} and a stable branch,
 e.g. @code{stable/2.12}.
 
 Some Git commands are introduced first, then a workflow with
@@ -1079,6 +1528,7 @@ several Git branches of LilyPond source code is presented.
 
 
 @menu
+* Merge conflicts::
 * Advanced Git concepts::
 * Resolving conflicts::
 * Reverting all local changes::
@@ -1088,9 +1538,17 @@ several Git branches of LilyPond source code is presented.
 * Sending and receiving patches via email::
 * Cleaning up multiple patches::
 * Commit access::
+* Pushing to staging::
 @end menu
 
 
+@node Merge conflicts
+@subsection Merge conflicts
+
+To be filled in later, and/or moved to a different section.  I
+just wanted to make sure that I had a stub ready somewhere.
+
+
 @node Advanced Git concepts
 @subsection Advanced Git concepts
 
@@ -1108,7 +1566,7 @@ git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
 
 @noindent
 where @code{@var{branch}} is typically @code{master} or
-@code{lilypond/translation}; if you do not know or remember, see
+@code{translation}; if you do not know or remember, see
 @ref{Downloading remote branches} to remember which commands you
 issued or which source code you wanted to get.
 
@@ -1238,7 +1696,7 @@ current branch.  For example, if your current branch is
 @subsubheading Local clones, or having several working trees
 
 If you play with several Git branches, e.g. @code{master},
-@code{lilypond/translation}, @code{stable/2.12}), you may want to
+@code{translation}, @code{stable/2.12}), you may want to
 have one source and build tree for each branch; this is possible
 with subdirectories of your local Git repository, used as local
 cloned subrepositories.  To create a local clone for the branch
@@ -1309,10 +1767,10 @@ git am @var{patch}
 
 Patches created without @code{git@tie{}format-patch} can be
 applied in two steps.  The first step is to apply the patch to the
-working tree:
+working tree and the index:
 
 @example
-git apply @var{patch}
+git apply --index @var{patch}
 @end example
 
 @noindent
@@ -1320,9 +1778,16 @@ The second step is to commit the changes and give credit to the
 author of the patch.  This can be done with the following command:
 
 @example
-git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
+git commit --author="@var{John Smith} <@var{john@@example.com}>"
 @end example
 
+Please note that using the @code{--index} option for patching is quite
+important here and @emph{cannot} reliably be replaced by using the
+@code{-a} option when committing: that would only commit files from the
+working tree that are already registered with git, so every file that
+the patch actually @emph{adds}, like a regtest for a fixed bug, would
+get lost.  For the same reason, you should not use the git-independent
+@samp{patch} program for applying patches.
 
 @node Sending and receiving patches via email
 @subsection Sending and receiving patches via email
@@ -1374,7 +1839,6 @@ remove those commits.}
 @node Commit access
 @subsection Commit access
 
-
 Most contributors are not able to commit patches directly to the
 main repository---only members of the LilyPond development team
 have @emph{commit access}.  If you are a contributor and are
@@ -1422,15 +1886,15 @@ Contributor of} on your @qq{My Group Membership} page.
 
 
 @item
-Generate an SSH @q{dsa} key pair.  Enter the following at the
+Generate an SSH @q{rsa} key pair.  Enter the following at the
 command prompt:
 
 @example
-ssh-keygen -t dsa
+ssh-keygen -t rsa
 @end example
 
 When prompted for a location to save the key, press <ENTER> to
-accept the default location (@file{~/.ssh/id_dsa}).
+accept the default location (@file{~/.ssh/id_rsa}).
 
 Next you are asked to enter an optional passphrase.  On most
 systems, if you use a passphrase, you will likely be prompted for
@@ -1442,7 +1906,7 @@ though you may find it tedious to keep re-entering it.
 You can change/enable/disable your passphrase at any time with:
 
 @example
-ssh-keygen -f ~/.ssh/id_dsa -p
+ssh-keygen -f ~/.ssh/id_rsa -p
 @end example
 
 Note that the GNOME desktop has a feature which stores your
@@ -1457,14 +1921,14 @@ gconftool-2 --set -t bool \
 @end example
 
 After setting up your passphrase, your private key is saved as
-@file{~/.ssh/id_dsa} and your public key is saved as
-@file{~/.ssh/id_dsa.pub}.
+@file{~/.ssh/id_rsa} and your public key is saved as
+@file{~/.ssh/id_rsa.pub}.
 
 
 @item
-Register your public SSH @q{dsa} key with Savannah.  From the
+Register your public SSH @q{rsa} key with Savannah.  From the
 @qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
-then paste the contents of your @file{~/.ssh/id_dsa.pub} file into
+then paste the contents of your @file{~/.ssh/id_rsa.pub} file into
 one of the @qq{Authorized keys} text fields, and click
 @qq{Update}.
 
@@ -1485,7 +1949,7 @@ git config remote.origin.url \
 @end example
 
 @noindent
-where @var{user} is your username on Savannah.
+replacing @var{user} with your Savannah username.
 
 
 @item
@@ -1541,7 +2005,7 @@ If @command{git@tie{}pull@tie{}--verbose} succeeds, the output
 will include a @q{From} line that shows @q{ssh} as the protocol:
 
 @example
-From ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond
+From ssh://git.sv.gnu.org/srv/git/lilypond
 @end example
 
 If the protocol shown is not @q{ssh}, check that you configured
@@ -1551,6 +2015,9 @@ Git properly in the previous step.
 @item
 Test your commit access with a dry run:
 
+@warning{Do not push directly to master; instead, push to staging.
+See @ref{Pushing to staging}.}
+
 @example
 git push --dry-run --verbose
 @end example
@@ -1566,9 +2033,17 @@ git config push.default matching
 @noindent
 Then @code{git@tie{}push} should work as before.  For more
 details, consult the @code{git@tie{}push} man page.
-@end enumerate
 
 
+@item
+Repeat the steps from generating an RSA key through to testing
+your commit access, for each machine from which you will be
+making commits, or you may simply copy the files from your
+local @file{~/.ssh} folder to the same folder on the other
+machine.
+
+@end enumerate
+
 @subsubheading Technical details
 
 @itemize
@@ -1634,9 +2109,75 @@ broadband may use a slightly smaller MTU for efficient transmission
 over ATM.  If this problem is encountered a possible work-around is
 to set the MTU in the local router to 1500.
 
+
+@node Pushing to staging
+@subsection Pushing to staging
+
+Do not push directly to the git @code{master} branch.  Instead,
+push to @code{staging}.
+
+You will not see your patch on @code{origin/master} until some
+automatic tests have been run.  These tests are run every couple
+of hours; please wait at least 12 hours before wondering if your
+patch has been lost.  Note that you can check the commits on
+@code{origin/staging} by looking at the git web interface on
+savannah.
+
+It may happen occasionally that the staging branch breaks automated
+testing.  In this case the automatic move of staging material to
+master gets halted in order to avoid broken material entering master.
+This is a safety net.  Please do not try breaking out from it by
+adding fixes on top of staging: in that case the whole sequence will
+end up in master after all, defeating the purpose of the system.  The
+proper fix usually involves rewriting the staging branch and is best
+left to core developers after discussion on the developer list.
+
+@subsubheading If your work is in a patch file
+
+Assuming that your patch is in a file called
+@file{0001-my-patch.patch}, and you are currently on git master,
+do:
+
+@example
+git checkout staging
+git pull -r
+git am 0001-my-patch.patch
+gitk
+git push origin staging
+git checkout master
+@end example
+
+@warning{Do not skip the @command{gitk} step; a quick 5-second
+check of the visual history can save a great deal of frustration
+later on.  You should only see that @command{staging} is only 1
+commit ahead of @code{origin/staging}.}
+
+@subsubheading If your work is in a branch
+
+If you are working on branches and your work in is
+@code{my_branch_name}, then do:
+
+@example
+git checkout staging
+git pull -r
+git merge my_branch_name
+gitk
+git push origin staging
+@end example
+
+@warning{Do not skip the @command{gitk} step; a quick 5-second
+check of the visual history can save a great deal of frustration
+later on.  You should see that @code{staging} is only ahead of
+@code{origin/staging} by the commits from your branch.}
+
+
+
 @node Git on Windows
 @section Git on Windows
 
+@warning{We heavily recommend that development be done with our
+virtual machine @ref{LilyDev}.}
+
 @c Some of this may duplicate stuff in other sections
 @c But it is probably best for windows users to have it all together
 @c If necessary, clear this up later  -td
@@ -2013,5 +2554,10 @@ More in-depth tutorials: @uref{http://git-scm.com/documentation}
 
 @item
 Book about git: @uref{http://progit.org/,Pro Git}
+
+@item
+Github help: @uref{http://help.github.com/}
+(very highly recommended by Graham)
+
 @end itemize