Doc: CG, explain other git prompt variables

[lilypond.git] / Documentation / contributor / source-code.itexi

diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi
index 6f1744e2e414bd3c2c742a447b1f390bdb746e07..620368280aa9bdb63e84be05462e0dda0032da18 100644 (file)
--- 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
 @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.
 
 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}
 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
 
 @c there's some duplication in this section with stuff covered in
 @c Quick Start, but moving it into a macro inside included/ would


@@ -45,7 +45,7 @@ If you haven't already, download and install Git.
 @qq{Full installer for official Git} from:
 
 @example
 @qq{Full installer for official Git} from:
 
 @example

-@uref{http://code.google.com/p/msysgit/downloads/list}
+@uref{https://git-for-windows.github.io/}

 @end example
 
 @item Other operating systems: either install @command{git} with
 @end example
 
 @item Other operating systems: either install @command{git} with


@@ -93,10 +93,10 @@ files.
 @end enumerate
 
 @warning{Throughout the rest of this manual, most command-line
 @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}.}
 
 referred to as the @emph{top source directory}.}
 

-Further instructions are in @ref{Daily use of lily-git.tcl}.
+Further instructions are in @ref{How to use lily-git}.

 
 
 @node Starting with Git
 
 
 @node Starting with Git


@@ -160,7 +160,7 @@ The above command will put the it in @file{~/lilypond-git}, where
 
 @subsubheading Technical details
 
 
 @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.
 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.


@@ -171,7 +171,7 @@ 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
 
 @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 working with the copy of the main LilyPond repository, you
 referred to as the @emph{top source directory}.}
 
 Before working with the copy of the main LilyPond repository, you


@@ -209,16 +209,28 @@ git config --global core.editor @var{nano}
 @end example
 
 Finally, and in some ways most importantly, let's make sure that
 @end example
 
 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}:
+we can easily see the state of our working copy, without the need
+of typing @code{git status} repeatedly.  If you're not using
+LilyDev, add the following lines to your @file{~/.bashrc}:

 
 @verbatim
 export PS1="\u@\h \w\$(__git_ps1)$ "
 
 @verbatim
 export PS1="\u@\h \w\$(__git_ps1)$ "

+export GIT_PS1_SHOWDIRTYSTATE=true
+export GIT_PS1_SHOWUNTRACKEDFILES=true
+export GIT_PS1_SHOWUPSTREAM=auto

 @end verbatim
 
 @end verbatim
 

-If you are not using lilydev, you may need to install the
-additional @code{git-completion} package, but it is definitely
-worth it.
+The first line will show the branch we're on.  The other lines
+will use some symbols next to the branch name to indicate some
+kind of state. @qq{*} means that there are unstaged changes,
+@qq{+} indicates staged changes; if there are untracked files,
+a @qq{%} will appear.  Finally, we can also see if our HEAD is
+behind (@qq{<}) or ahead (@qq{>}) of its upstream, and if they
+have diverged (@qq{<>}) or they are synced (@qq{=}).
+
+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
 
 
 @subsubheading Technical details


@@ -312,7 +324,7 @@ git checkout dev/cg
 Your prompt now shows you that you're on the other branch:
 
 @example
 Your prompt now shows you that you're on the other branch:
 
 @example

-gperciva@@lilydev:~/lilypond-git (dev/cg)$ 
+gperciva@@LilyDev:~/lilypond-git (dev/cg)$

 @end example
 
 To be able to manage multiple lilypond issues at once, you'll need to switch
 @end example
 
 To be able to manage multiple lilypond issues at once, you'll need to switch


@@ -372,7 +384,7 @@ At this stage, don't worry about how many commits you have.
 
 Branches are nerve-wracking until you get used to them.  You can
 save your hard work as individual @file{.patch} files.  Be sure to
 
 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 chages first.
+commit your changes first.

 
 @example
 git commit -a
 
 @example
 git commit -a


@@ -464,7 +476,7 @@ prepare your upload:
 @example
 git fetch
 git rebase origin/staging dev/cg~0
 @example
 git fetch
 git rebase origin/staging dev/cg~0

-gitk HEAD 
+gitk HEAD

 @end example
 
 @warning{Do not skip the @command{gitk} step; a quick 5-second
 @end example
 
 @warning{Do not skip the @command{gitk} step; a quick 5-second


@@ -531,6 +543,7 @@ We have a few other code repositories.
 @menu
 * lilypond-extra::
 * Grand Unified Builder (GUB)::
 @menu
 * lilypond-extra::
 * Grand Unified Builder (GUB)::

+* LilyPad::

 * yet more repositories::
 @end menu
 
 * yet more repositories::
 @end menu
 


@@ -548,28 +561,101 @@ environment variable to point to that repository.
 @end example
 
 To configure an environment variable in bash (the default for most
 @end example
 
 To configure an environment variable in bash (the default for most

-Linux distributions),
+GNU/Linux distributions),

 
 @example
 export LILYPOND_WEB_MEDIA_GIT=$HOME/dir/of/lilypond-extra/
 @end example
 
 
 @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
 @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 projects as
+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}.
 
 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, which will hopefully
-be kept up-to-date with each other:
+There are two locations for this repository: the version being used to
+build lilypond, which is at

 
 @example
 
 @example

-@uref{http://github.com/janneke/gub}

 @uref{http://github.com/gperciva/gub}
 @end 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/downloads/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
 
 @node yet more repositories
 @unnumberedsubsubsec yet more repositories


@@ -607,13 +693,13 @@ development releases), the documentation (and its translations),
 and the website.  Generally, the @code{master} branch is expected
 to compile successfully.
 
 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
 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
 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.
 
 significant changes to the English documentation.  See
 @ref{Translating the documentation} for details.
 


@@ -661,11 +747,11 @@ git remote add -ft master -m master \
   origin git://git.sv.gnu.org/lilypond.git/
 @end example
 
   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
 
 @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
 @end example
 
 The @command{git@tie{}remote@tie{}add} process could take up to


@@ -703,7 +789,7 @@ git checkout -b @var{branch} origin/@var{branch}
 
 @noindent
 where @code{@var{branch}} is the name of your tracking 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:
 
 
 Git will issue some warnings; this is normal:
 


@@ -715,7 +801,7 @@ Already on 'master'
 @end example
 
 By now the source files should be accessible---you should be able
 @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}.
 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}.


@@ -760,6 +846,9 @@ branch.
 @item @code{stable/XYZ}:
 The branches are kept for archival reasons.
 
 @item @code{stable/XYZ}:
 The branches are kept for archival reasons.
 

+@item @code{archive/XYZ}:
+The branches are kept for archival reasons.
+

 @end itemize
 
 
 @end itemize
 
 


@@ -771,7 +860,10 @@ The branches are kept for archival reasons.
 * The Git contributor's cycle::
 * Pulling and rebasing::
 * Using local branches::
 * The Git contributor's cycle::
 * Pulling and rebasing::
 * Using local branches::

-* Commits and patches::
+* Commits::
+* Patches::
+* Uploading a patch for review::
+* The patch review cycle::

 @end menu
 
 
 @end menu
 
 


@@ -863,7 +955,7 @@ refusing to pull with rebase: your working tree is not up-to-date
 
 @noindent
 it means that you have modified some files in you working tree
 
 @noindent
 it means that you have modified some files in you working tree

-without committing changes (see @ref{Commits and patches}); you
+without committing changes (see @ref{Commits}); you

 can use the @command{git@tie{}stash} command to work around this:
 
 @example
 can use the @command{git@tie{}stash} command to work around this:
 
 @example


@@ -884,7 +976,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
 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.}
 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.}


@@ -1004,24 +1096,20 @@ git merge @var{foo}
 
 If any conflict happens, see @ref{Resolving conflicts}.
 
 
 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
-@subsection Commits and patches

 
 

+@node Commits
+@subsection Commits

 
 @menu
 * Understanding commits::
 
 @menu
 * Understanding commits::

-* Making commits::
+* How to make a commit::

 * Commit messages::
 * Commit messages::

-* Making patches::
-* Uploading a patch for review::

 @end menu
 
 
 @end menu
 
 


@@ -1053,8 +1141,8 @@ branch are available at
 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
 
 
 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
 
 

-@node Making commits
-@unnumberedsubsubsec Making commits
+@node How to make a commit
+@unnumberedsubsubsec How to make a commit

 
 
 Once you have modified some source files in your working
 
 
 Once you have modified some source files in your working


@@ -1159,21 +1247,46 @@ high-res images, fixed cropping on Finale example.
 @end example
 
 Commit messages often start with a short prefix describing the
 @end example
 
 Commit messages often start with a short prefix describing the

-general location of the changes.  If a commit affects the
+general location of the changes.
+
+@itemize
+@item
+Doc: and Doc-@var{**}:  If a commit affects the

 documentation in English (or in several languages simultaneously)
 documentation in English (or in several languages simultaneously)

-the commit message should be prefixed with @qq{Doc:@tie{}}.  If
-the commit affects only one of the translations, the commit
+the commit message should be prefixed with @qq{Doc:@tie{}}.  If the
+commit affects only one of the translations, the commit

 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where

-@var{**} is the two-letter language code.  Commits that affect the
+@var{**} is the two-letter language code.
+
+@item
+Web: and Web-@var{**}:  Commits that affect the

 website should use @qq{Web:@tie{}} for English, and
 website should use @qq{Web:@tie{}} for English, and

-@qq{Web-@var{**}:@tie{}} for the other languages.  Also, changes
-to a single file are often prefixed with the name of the file
-involved.  Visit the links listed in @ref{Understanding commits}
-for examples.
+@qq{Web-@var{**}:@tie{}} for other languages.
+
+@item
+CSS: Commits that change CSS files should use @qq{Web:@tie{}CSS:@tie{}}
+or @qq{Doc:@tie{}CSS:@tie{}} depending on whether they affect the
+website or the documentation/manuals.

 
 

+@item
+Changes to a single file are often prefixed with the name of the file
+involved.
+@end itemize
+
+Visit the links listed in @ref{Understanding commits} for examples.
+
+
+
+@node Patches
+@subsection Patches
+
+@menu
+* How to make a patch::
+* Emailing patches::
+@end menu

 
 

-@node Making patches
-@unnumberedsubsubsec Making patches
+@node How to make a patch
+@unnumberedsubsubsec How to make a patch

 
 If you want to share your changes with other contributors and
 developers, you need to generate @emph{patches} from your commits.
 
 If you want to share your changes with other contributors and
 developers, you need to generate @emph{patches} from your commits.


@@ -1213,82 +1326,48 @@ reviewed, the developers may push one or more of them to the main
 repository or discuss them with you.
 
 
 repository or discuss them with you.
 
 

-@node Uploading a patch for review
-@unnumberedsubsubsec Uploading a patch for review
-
-Any non-trivial change should be uploaded to our @qq{Rietveld}
-code review website:
-
-@example
-@uref{http://codereview.appspot.com/}
-@end example
+@node Emailing patches
+@unnumberedsubsubsec Emailing patches

 
 

-@subsubheading @command{git-cl} install
-
-LilyDev users should skip over these @q{install} instructions.
-
-@enumerate
-
-@item
-Install @command{git-cl} by entering:
-
-@example
-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}).
+The default @code{x-diff} MIME type associated with patch files
+(i.e., files whose name ends in @code{.patch}) means that the
+encoding of line endings may be changed from UNIX to DOS format
+when they are sent as attachments.  Attempting to apply such an
+inadvertently altered patch will cause git to fail with a message
+about @q{whitespace errors}.

 
 

-In Ubuntu (and Lilydev), you can add directories to PATH
-by adding this line to a hidden file @file{.bashrc},
-located in your home directory:
+The solution to such problems is surprisingly simple---just change
+the default file extension of patches generated by git to end in
+@code{.txt}, for example:

 
 @example
 
 @example

-PATH=~/type-here-directory-containing-git-cl:"$@{PATH@}"
+git config format.suffix '.patch.txt'

 @end example
 
 @end example
 

-@end enumerate
-
-@subsubheading @command{git-cl} configuration
-
-LilyDev users should perform these @q{configuration} instructions.
+This should cause email programs to apply the correct base64
+encoding to attached patches.

 
 

-@enumerate
-@item
-You must have a google account; please create one if you do not
-have one already.
+If you receive a patch with DOS instead of UNIX line-endings, it
+can be converted back using the @code{dos2unix} utility.

 
 

-Note that a google account does not need to be a gmail account; you can
-use any email address for your google account when you sign up.
+Lots of useful information on email complications with patches is
+provided on the Wine wiki at
+@uref{http://wiki.winehq.org/GitWine}.

 
 

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

 
 

-@example
-cd $HOME/lilypond-git/
-git cl config
-@end example
+@node Uploading a patch for review
+@subsection Uploading a patch for review

 
 

-The @qq{CC list} question should be answered with:
+Any non-trivial change should be uploaded to our @qq{Rietveld}
+code review website:

 
 @example
 
 @example

-lilypond-devel@@gnu.org
+@uref{http://codereview.appspot.com/}

 @end example
 
 @end example
 

-@end enumerate
-
-@subsubheading Uploading patch set
+You can upload a patch for review by using our custom @code{git-cl}
+@q{helper-script}.  This section assumes you have already installed,
+updated, and configured @code{git-cl}.  See @ref{git-cl}.

 
 @warning{Unless you are familiar with branches, only work on one
 set of changes at once.}
 
 @warning{Unless you are familiar with branches, only work on one
 set of changes at once.}


@@ -1297,15 +1376,16 @@ There are two methods, depending on your git setup.
 
 @itemize
 @item
 
 @itemize
 @item

-@strong{Master branch}: (easy option, and used in @command{lily-git.tcl})
+@strong{Master branch}: (easy option)

 
 If you added your patch to @code{master}, then:
 
 @example
 git pull -r
 
 If you added your patch to @code{master}, then:
 
 @example
 git pull -r

-git cl upload origin/master
+git-cl upload origin/master

 @end example
 
 @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.
 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.


@@ -1320,32 +1400,46 @@ option.
 @item
 @strong{Separate branch}: (complicated option)
 
 @item
 @strong{Separate branch}: (complicated option)
 

-Ensure your changes are committed in a separate branch, which
-should differ from the reference branch to be used by just the
-changes to be uploaded.  If the reference branch is to be
-origin/master, ensure this is up-to-date.  If necessary, use git
-rebase to rebase the branch containing the changes to the head of
-origin/master.  Finally, check out branch with the changes and
-enter the command:
+Ensure your changes are committed in a separate branch, which should
+differ from the reference branch to be used (usually
+@code{origin/master}) by just the changes to be uploaded.  Checkout the
+branch with the changes:
+
+@example
+git checkout some-branch-with-changes
+@end example
+
+If the reference branch is to be @code{origin/master}, ensure that the
+branch containing the changes is up-to-date with it.  Use
+@command{git rebase} or @command{git pull -r} to rebase the branch to
+the head of @code{origin/master}.  For example:

 
 @example
 
 @example

-git cl upload <reference SHA1 ID>
+git pull -r origin master
+@end example
+
+Finally, start the upload by entering:
+
+@example
+git-cl upload <reference SHA1 ID>

 @end example
 
 @noindent
 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
 as a reference source for the patch.  Generally, this will be the
 @end example
 
 @noindent
 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
 as a reference source for the patch.  Generally, this will be the

-SHA1 ID of origin/master, and in that case the command:
+SHA1 ID of origin/master, and in that case you can just use the command:

 
 @example
 
 @example

-git cl upload origin/master
+git-cl upload origin/master

 @end example
 
 @end example
 

-@noindent
-can be used.
-

 @end itemize
 
 @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.
 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.


@@ -1377,23 +1471,25 @@ associate the new branch with an existing Rietveld issue,
 the following command can be used:
 
 @example
 the following command can be used:
 
 @example

-git cl issue issue-number
+git-cl issue issue-number

 @end example
 
 @noindent
 where @code{issue-number} is the number of the existing Rietveld
 issue.
 
 @end example
 
 @noindent
 where @code{issue-number} is the number of the existing Rietveld
 issue.
 

-@subsubheading Resetting git cl
+@subsubheading Resetting git-cl

 
 

-If @command{git cl} becomes confused, you can @qq{reset} it by
+If @command{git-cl} becomes confused, you can @qq{reset} it by

 running:
 
 @example
 running:
 
 @example

-git cl issue 0
+git-cl issue 0

 @end example
 
 @end example
 

-@subsubheading Wait for a countdown
+
+@node The patch review cycle
+@subsection The patch review cycle

 
 Your patch will be available for reviews for the next few hours or
 days.  Three times a week, patches with no known problems are
 
 Your patch will be available for reviews for the next few hours or
 days.  Three times a week, patches with no known problems are


@@ -1410,6 +1506,211 @@ 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}.
 
 mentor for uploading.  If you have git push ability, look at
 @ref{Pushing to staging}.
 

+@itemize
+
+@item
+Patches get added to the tracker and to Rietveld by the @qq{git-cl} tool, with
+a status of @qq{patch-new}.
+
+@item
+The automated tester, Patchy, verifies that the patch can be applied
+to current master.  By default, it checks that the patch allows @code{make}
+and @code{make test} to complete successfully.  It can also be configured to
+check that @code{make doc} is successful. If it passes, Patchy changes the
+status to @qq{patch-review} and emails the developer list.  If the patch
+fails, Patchy sets it to @qq{patch-needs_work} and notifies the developer list.
+
+@item
+The Patch Meister reviews the tracker periodically, to list patches
+which have been on review for at least 24 hours. The list is found at
+
+@smallexample
+@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch%20patch=review&sort=modified+patch&colspec=ID%20Type%20Status%20Priority%20Owner%20Patch%20Summary%20Modified}
+@end smallexample
+
+@item
+For each patch, the Handler reviews any discussion on the tracker
+and on Rietveld, to determine whether the patch can go forward.  If
+there is any indication that a developer thinks the patch is not
+ready, the Handler marks it @qq{patch-needs_work} and makes a comment
+regarding the reason, referring to the Rietveld item if needed.
+
+@item
+Patches with explicit approval, or at least no negative comment, can
+be updated to @qq{patch-countdown}.  When saving the tracker item,
+clear the @qq{send email} box to prevent sending notification for
+each patch.
+
+@item
+The Patch Meister sends an email to the developer list, with a fixed
+subject line, to enable filtering by email clients:
+
+@example
+PATCH: Countdown to 20130113
+@end example
+
+The text of the email sets the deadline for this countdown batch.  At
+present, batches are done on Tuesday, Thursday and Sunday evenings.
+
+To create the countdown announcement, use the
+@code{make-countdown-announcement.sh} script, which takes the
+deadline date, and optionally your name.  Follow the instructions
+provided:
+
+@example
+cd $LILYPOND_GIT
+scripts/auxiliar/make-countdown-announcement.sh "Jan 1, 2001" James
+@end example
+
+The script produces an announcement that is easily readable in all
+email clients.  Also, whenever a new contributor submits a patch,
+you will be prompted to add the new username and author name to
+the script itself, and then commit those changes to the main git
+repository.
+
+
+@item
+On the scheduled countdown day, the Patch Meister reviews the
+previous list of patches on countdown, with the same procedure and
+criteria as before.  Patches with no controversy can be set to
+@qq{patch-push} with a courtesy message added to the comment block.
+
+@item
+Roughly at six month intervals, the Patch Meister can list the
+patches which have been set to @qq{patch-needs-work} and send the
+results to the developer list for review.  In most cases, these
+patches should be marked @qq{patch-abandoned} but this should come
+from the developer if possible.
+
+@item
+As in most organisations of unpaid volunteers, fixed procedures are
+useful in as much as they get the job done.  In our community, there
+is room for senior developers to bypass normal patch handling flows,
+particularly now that the testing of patches is largely automated.
+Similarly, the minimum age of 24 hours can reasonably be waived if
+the patch is minor and from an experienced developer.
+
+
+@end itemize
+
+@ignore
+There is a single Patch Meister, and a number of Patch Helpers
+(rename this?).  The list of known patches awaiting review is:
+
+@example
+@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch&sort=patch}
+@end example
+
+
+@subheading Helpers: adding patches
+
+The primary duty is to add patches to the google tracker; we have
+a bad track record of losing patches in email.  Patches generally
+come to the @code{lilypond-devel} mailing list, but are sometimes
+sent to @code{bug-lilypond}, @code{lilypond-users}, or
+@code{frogs} mailing list instead.
+
+@itemize
+@item
+Unless a patch is clearly in response to an existing issue, add a
+new issue with the @code{Patch-new} label and a link to the patch
+(either on the mailing list archives or the codereview url).
+
+Issue numbers are cheap; losing developers because they got fed up
+with us losing their hard work is expensive.
+
+
+@c if we enter patches immediately, I don't think this is relevant.
+
+@item
+Before adding a patch-reminder issue, do a quick check to see if
+it was pushed without sending any email.  This can be checked for
+searching for relevant terms (from the patch subject or commit
+message) on the webgit page:
+
+@example
+@uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
+@end example
+
+
+@item
+If the patch is clearly in response to an existing issue, then
+update that issue with the @code{Patch-new} label and a link to
+the patch (either on the mailing list archives or the codereview
+url).
+
+@item
+After adding the issue, please send a response email to the same
+group(s) that the initial patch was sent to.
+
+If the initial email was sent to multiple mailing lists (such as
+both @code{bugs} and @code{devel}), then reply to all those
+mailing lists as well.  The email should contain a link to the
+issue you just added.
+
+@end itemize
+
+@subheading Helpers: @code{Patch-review} label
+
+The secondary duty is to do make sure that every issue in the
+tracker with a @code{Patch-review} label has passed these
+@qq{obvious} tests:
+
+@itemize
+@item
+Applies automatically to git master.
+
+It's ok to have offsets, but not conflicts.
+
+@item
+Regtest comparison looks ok; no unexpected changes.
+
+@item
+Descriptive subject line.
+
+Avoid subjects like @qq{fixes 123}; instead write @qq{Doc: discuss
+stacking-dir for BassFigureAlignment (fix 123)}.
+
+@item
+Compiles docs from scratch.  Only check this if you have reason to
+suspect it might not work.
+
+@item
+(maybe)
+
+Check code indentation and style.  This should be easier post-GOP
+when we have a better-defined code style.
+
+@end itemize
+
+
+@subheading Patch Meister
+
+The Patch Meister will:
+
+@itemize
+
+@item
+send @qq{countdown} emails to
+@code{lilypond-devel} when patches appear to be ready.
+
+@item
+send general requests to review patches, or even nasty requests to
+review patches.
+
+@item
+downgrade patches from @code{Patch-review} to
+@code{Patch-needs_work} as appropriate.
+
+@item
+downgrade patches from @code{Patch-needs_work} to
+@code{Patch-abandoned} if no actions have been taken in four
+weeks.
+
+@end itemize
+
+@end ignore
+

 
 @node Advanced Git procedures
 @section Advanced Git procedures
 
 @node Advanced Git procedures
 @section Advanced Git procedures


@@ -1421,7 +1722,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
 
 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
 e.g. @code{stable/2.12}.
 
 Some Git commands are introduced first, then a workflow with


@@ -1436,7 +1737,6 @@ several Git branches of LilyPond source code is presented.
 * Working with remote branches::
 * Git log::
 * Applying remote patches::
 * Working with remote branches::
 * Git log::
 * Applying remote patches::

-* Sending and receiving patches via email::

 * Cleaning up multiple patches::
 * Commit access::
 * Pushing to staging::
 * Cleaning up multiple patches::
 * Commit access::
 * Pushing to staging::


@@ -1467,7 +1767,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
 
 @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.
 
 @ref{Downloading remote branches} to remember which commands you
 issued or which source code you wanted to get.
 


@@ -1597,7 +1897,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},
 @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
 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


@@ -1668,10 +1968,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
 
 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
 
 @example

-git apply @var{patch}
+git apply --index @var{patch}

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -1679,38 +1979,17 @@ 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
 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
 
 @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
-
-
-The default @code{x-diff} MIME type associated with patch files
-(i.e., files whose name ends in @code{.patch}) means that the
-encoding of line endings may be changed from UNIX to DOS format
-when they are sent as attachments.  Attempting to apply such an
-inadvertently altered patch will cause git to fail with a message
-about @q{whitespace errors}.
-
-The solution to such problems is surprisingly simple---just change
-the default file extension of patches generated by git to end in
-@code{.txt}, for example:
-
-@example
-git config format.suffix '.patch.txt'
-@end example
-
-This should cause email programs to apply the correct base64
-encoding to attached patches.
-
-If you receive a patch with DOS instead of UNIX line-endings, it
-can be converted back using the @code{dos2unix} utility.
-
-Lots of useful information on email complications with patches is
-provided on the Wine wiki at
-@uref{http://wiki.winehq.org/GitWine}.

 
 
 @node Cleaning up multiple patches
 
 
 @node Cleaning up multiple patches


@@ -2017,11 +2296,41 @@ patch has been lost.  Note that you can check the commits on
 @code{origin/staging} by looking at the git web interface on
 savannah.
 
 @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.
+
+Before pushing to staging it is a good practice to check whether
+staging is ahead of master, and if so, wait until master has caught up
+with staging before pushing.  This simplifies things if changes to
+staging have to be backed out for some reason.  To check whether
+master has caught up with staging you can look at the git web interface
+on savannah, or do:
+
+@example
+git fetch
+gitk
+@end example
+
+and check that @code{origin/master} is at the same commit as
+@code{origin/staging}.  Another option is to see if any commits are
+listed when you do:
+
+@example
+git fetch
+git log origin/master..origin/staging
+@end example
+

 @subsubheading If your work is in a patch file
 
 Assuming that your patch is in a file called
 @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:
+@file{0001-my-patch.patch} (see @ref{Patches}), and you are currently
+on git master, do:

 
 @example
 git checkout staging
 
 @example
 git checkout staging


@@ -2039,20 +2348,26 @@ commit ahead of @code{origin/staging}.}
 
 @subsubheading If your work is in a branch
 
 
 @subsubheading If your work is in a branch
 

-If you are working on branches and your work in is
+If you are working on branches and your work is in

 @code{my_branch_name}, then do:
 
 @example
 @code{my_branch_name}, then do:
 
 @example

-git checkout staging
-git pull -r
-git merge my_branch_name
+git checkout my_branch_name
+git pull -r origin staging
+@end example
+
+This will rebase your branch on @code{origin/staging}.  At this point
+git will let you know if there are any conflicts.  If so, resolve them
+before continuing:
+
+@example

 gitk
 gitk

-git push origin staging
+git push origin HEAD: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
 @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
+later on.  You should see that @code{my_branch_name} is only ahead of

 @code{origin/staging} by the commits from your branch.}
 
 
 @code{origin/staging} by the commits from your branch.}
 
 


@@ -2061,7 +2376,7 @@ later on.  You should see that @code{staging} is only ahead of
 @section Git on Windows
 
 @warning{We heavily recommend that development be done with our
 @section Git on Windows
 
 @warning{We heavily recommend that development be done with our

-virtual machine @ref{Lilydev}.}
+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 Some of this may duplicate stuff in other sections
 @c But it is probably best for windows users to have it all together


@@ -2097,9 +2412,7 @@ has, either as a complete file or as a @q{diff} or @q{patch}
 @subsection Installing git
 
 Obtain Git from
 @subsection Installing git
 
 Obtain Git from

-@uref{http://code.google.com/p/msysgit/downloads/list} (note, not
-msysGit, which is for Git developers and not PortableGit, which is
-not a full git installation) and install it.
+@uref{https://git-for-windows.github.io/}.

 
 Note that most users will not need to install SSH.  That is not
 required until you have been granted direct push permissions to
 
 Note that most users will not need to install SSH.  That is not
 required until you have been granted direct push permissions to