X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fsource-code.itexi;h=719c85e041ba80021059c338d3c0b1047f76cc13;hb=88a5dbc589b0d0434f8e640467b5ab57d14dc461;hp=ee20d3e76e1b64891ea463c8b4c28155e3876f54;hpb=cf039a0cae992c1437514440478e136c5051e653;p=lilypond.git

diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi
index ee20d3e76e..719c85e041 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
@@ -93,10 +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}.
+Further instructions are in @ref{How to use lily-git}.
 
 
 @node Starting with Git
@@ -160,7 +160,7 @@ The above command will put the it in @file{~/lilypond-git}, where
 
 @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.
@@ -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
-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
@@ -209,16 +209,16 @@ git config --global core.editor @var{nano}
 @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
-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
@@ -312,7 +312,7 @@ git checkout dev/cg
 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
@@ -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
-commit your chages first.
+commit your changes first.
 
 @example
 git commit -a
@@ -526,6 +526,18 @@ 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
@@ -537,12 +549,104 @@ environment variable to point to that repository.
 @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 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.
@@ -577,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.
 
@@ -631,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
@@ -673,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:
 
@@ -685,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}.
@@ -730,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
@@ -860,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.}
@@ -980,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
@@ -1199,72 +1299,9 @@ code review website:
 @uref{http://codereview.appspot.com/}
 @end example
 
-@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}).
-
-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:
-
-@example
-PATH=~/type-here-directory-containing-git-cl:"$@{PATH@}"
-@end example
-
-@end enumerate
-
-@subsubheading @command{git-cl} configuration
-
-LilyDev users should perform these @q{configuration} instructions.
-
-@enumerate
-@item
-You must have a google account; 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.
-
-@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
-
-The @qq{CC list} question should be answered with:
-
-@example
-lilypond-devel@@gnu.org
-@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.}
@@ -1273,15 +1310,16 @@ There are two methods, depending on your git setup.
 
 @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
-git cl upload origin/master
+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.
@@ -1296,32 +1334,46 @@ 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
-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
-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
-git cl upload origin/master
+git-cl upload origin/master
 @end example
 
-@noindent
-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.
@@ -1353,20 +1405,20 @@ associate the new branch with an existing Rietveld issue,
 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.
 
-@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
-git cl issue 0
+git-cl issue 0
 @end example
 
 @subsubheading Wait for a countdown
@@ -1397,7 +1449,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
@@ -1443,7 +1495,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.
 
@@ -1573,7 +1625,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
@@ -1644,10 +1696,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
@@ -1655,9 +1707,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
@@ -1993,6 +2052,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.
 
+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
@@ -2037,7 +2105,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
-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