@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{How to use lily-git}.
@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.
@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
export PS1="\u@\h \w\$(__git_ps1)$ "
@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.
+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
@menu
* lilypond-extra::
* Grand Unified Builder (GUB)::
-* lilypad::
+* LilyPad::
* yet more repositories::
@end menu
@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
+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 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}.
-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
-@uref{http://github.com/janneke/gub}
@uref{http://github.com/gperciva/gub}
@end example
+and the original version by Jan Nieuwenhuizen, kept at
-@node lilypad
-@unnumberedsubsubsec lilypad
+@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. This code is here:
+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
-https://github.com/gperciva/lilypad
+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
@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}.
and @command{upload.py} scripts in one of your PATH
directories (such as @file{$HOME/bin}).
-In Ubuntu (and LilyDev), you can add directories to PATH
+In GNU/Linux you can add directories to PATH
by adding this line to a hidden file @file{.bashrc},
located in your home directory:
@enumerate
@item
-You must have a google 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.
-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.
+@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
+This section assumes that you have already configured the
+@command{git-cl} @q{helper-script}. See @ref{git-cl}.
+
@warning{Unless you are familiar with branches, only work on one
set of changes at once.}
@example
git pull -r
-git cl upload origin/master
+git-cl upload origin/master
@end example
@c Mention staging here?
@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.
@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