@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.
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
@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}.
+Further instructions are in @ref{How to use lily-git}.
@node Starting with Git
@menu
* Setting up::
* Git for the impatient::
+* Other repositories::
* Downloading remote branches::
@end menu
@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
@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
+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
-If you are not using lilydev, you may need to install the
+If you are not using LilyDev, you may need to install the
additional @code{git-completion} package, but it is definitely
worth it.
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
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
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
+
+@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. This code is here:
+
+@example
+https://github.com/gperciva/lilypad
+@end example
+
+
+@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::
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.
@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
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
@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:
@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}.
@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
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.}
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
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 Ubuntu (and LilyDev), you can add directories to PATH
by adding this line to a hidden file @file{.bashrc},
located in your home directory:
@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:
@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
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.
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
@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.
@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
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
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
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
@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
@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