Translates search-box.ihtml

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

diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi
index ee20d3e76e1b64891ea463c8b4c28155e3876f54..6a957052daadc2c4696a37abe1815fb84fc35fb1 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


@@ -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,14 +209,14 @@ 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
+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
 
 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.
 
 additional @code{git-completion} package, but it is definitely
 worth it.
 


@@ -312,7 +312,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 +372,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


@@ -526,6 +526,18 @@ a @code{-D}.
 @node Other repositories
 @subsection Other repositories
 
 @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
 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


@@ -537,12 +549,57 @@ 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
+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.
 
 There are a few other repositories floating around, which will
 hopefully be documented in the near future.


@@ -577,13 +634,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.
 


@@ -631,11 +688,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


@@ -673,7 +730,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:
 


@@ -685,7 +742,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}.


@@ -730,13 +787,10 @@ branch.
 @item @code{stable/XYZ}:
 The branches are kept for archival reasons.
 
 @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
 
 
 @node Basic Git procedures


@@ -860,7 +914,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.}


@@ -980,12 +1034,11 @@ 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
 
 
 @node Commits and patches


@@ -1224,7 +1277,7 @@ 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}).
 
 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:
 
 by adding this line to a hidden file @file{.bashrc},
 located in your home directory:
 


@@ -1248,20 +1301,28 @@ use any email address for your google account when you sign up.
 
 @item
 Move into the top source directory and then configure @command{git
 
 @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
 
 @example

-cd $HOME/lilypond-git/
+cd $LILYPOND_GIT

 git cl config
 @end example
 
 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{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
 @end enumerate
 
 @subsubheading Uploading patch set


@@ -1282,6 +1343,7 @@ git pull -r
 git cl upload origin/master
 @end example
 
 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.
 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.


@@ -1322,6 +1384,11 @@ 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.


@@ -1397,7 +1464,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


@@ -1443,7 +1510,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.
 


@@ -1573,7 +1640,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


@@ -1644,10 +1711,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


@@ -1655,9 +1722,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
 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
 
 @node Sending and receiving patches via email
 @subsection Sending and receiving patches via email


@@ -1993,6 +2067,15 @@ 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.
+

 @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


@@ -2037,7 +2120,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