Change several instances of "git cl" in the Contributors Guide to "git-cl".

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

diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi
index 84779698997b387d85f9beec5779ac0e1c9d2f28..4a7357878c85e13f87a3aaf5ed289baed674596a 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,16 +209,16 @@ 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
-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
 
 
 @subsubheading Technical details


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


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

-* lilypad::
+* LilyPad::

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


@@ -549,39 +549,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
+@node LilyPad
+@unnumberedsubsubsec LilyPad

 
 Our binary releases on MacOS X and Windows contain a lightweight
 
 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
 
 @example

-https://github.com/gperciva/lilypad
+git push https://UserName@@github.com/gperciva/lilypad.git

 @end example
 
 @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
 
 @node yet more repositories
 @unnumberedsubsubsec yet more repositories


@@ -619,13 +681,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.
 


@@ -673,11 +735,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


@@ -715,7 +777,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:
 


@@ -727,7 +789,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}.


@@ -899,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
 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.}


@@ -1019,12 +1081,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


@@ -1263,7 +1324,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 GNU/Linux 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:
 


@@ -1279,32 +1340,48 @@ LilyDev users should perform these @q{configuration} instructions.
 
 @enumerate
 @item
 
 @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.
 
 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
 
 @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).
+Move into the top source directory and then configure
+@command{git-cl} with the following commands:

 
 @example
 
 @example

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

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

+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.}
 
 @warning{Unless you are familiar with branches, only work on one
 set of changes at once.}
 


@@ -1312,15 +1389,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.


@@ -1335,16 +1413,28 @@ 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
+git pull -r origin master
+@end example
+
+Finally, start the upload by entering:

 
 @example
 
 @example

-git cl upload <reference SHA1 ID>
+git-cl upload <reference SHA1 ID>

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -1353,7 +1443,7 @@ as a reference source for the patch.  Generally, this will be the
 SHA1 ID of origin/master, and in that case the command:
 
 @example
 SHA1 ID of origin/master, and in that case the command:
 
 @example

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

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -1361,6 +1451,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.


@@ -1392,20 +1487,20 @@ 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
 
 @subsubheading Wait for a countdown
 @end example
 
 @subsubheading Wait for a countdown


@@ -1436,7 +1531,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


@@ -1482,7 +1577,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.
 


@@ -1612,7 +1707,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


@@ -2039,6 +2134,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


@@ -2083,7 +2187,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