CG: explain how to add git-cl to PATH

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

diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi
index 54d8ba7d7e7d94affcf3fb73c395d2129f385cdc..ea8fc8775c59007ed7831b1b3c07260edc1e9887 100644 (file)
--- a/Documentation/contributor/source-code.itexi
+++ b/Documentation/contributor/source-code.itexi
@@ -65,9 +65,9 @@ Download the @command{lily-git.tcl} script from:
 @c don't change the cgit link below to gitweb; gitweb uses
 @c long filenames like "scripts_auxiliar_lily-git.tcl"
 
 @c don't change the cgit link below to gitweb; gitweb uses
 @c long filenames like "scripts_auxiliar_lily-git.tcl"
 

-@example
+@smallexample

 @uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
 @uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}

-@end example
+@end smallexample

 
 @item
 To run the program from the command line, navigate to the
 
 @item
 To run the program from the command line, navigate to the


@@ -82,7 +82,7 @@ Click on the @qq{Get source} button.
 
 This will create a directory called @file{lilypond-git/} within
 your home directory, and will download the source code into that
 
 This will create a directory called @file{lilypond-git/} within
 your home directory, and will download the source code into that

-directory (around 55Mb).  When the process is finished, the
+directory (around 150@tie{}Mb).  When the process is finished, the

 @qq{Command output} window will display @qq{Done}, and the button
 label will change to say @qq{Update source}.
 
 @qq{Command output} window will display @qq{Done}, and the button
 label will change to say @qq{Update source}.
 


@@ -98,13 +98,6 @@ referred to as the @emph{top source directory}.}
 
 Further instructions are in @ref{Daily use of lily-git.tcl}.
 
 
 Further instructions are in @ref{Daily use of lily-git.tcl}.
 

-@advanced{the @qq{Get source} button does not fetch the entire
-history of the git repository, so utilities like @command{gitk}
-will only be able to display the most recent additions.  As you
-continue to work with @command{lily-git.tcl}, the @qq{Update
-source} button will take any new additions and add it to whatever
-is currently in your repository's history.}
-

 
 @node Starting with Git
 @section Starting with Git
 
 @node Starting with Git
 @section Starting with Git


@@ -125,10 +118,6 @@ multiple projects concurrently.
 @node Setting up
 @subsection Setting up
 
 @node Setting up
 @subsection Setting up
 

-
-TODO: Remove this note if incorporating Windows instructions
-throughout this section:
-

 @warning{These instructions assume that you are using the
 command-line version of Git 1.5 or higher.  Windows users should
 skip to @ref{Git on Windows}.}
 @warning{These instructions assume that you are using the
 command-line version of Git 1.5 or higher.  Windows users should
 skip to @ref{Git on Windows}.}


@@ -143,10 +132,9 @@ skip to @ref{Git on Windows}.}
 @node Installing Git
 @unnumberedsubsubsec Installing Git
 
 @node Installing Git
 @unnumberedsubsubsec Installing Git
 

-

 If you are using a Unix-based machine, the easiest way to download
 and install Git is through a package manager such as @command{rpm}
 If you are using a Unix-based machine, the easiest way to download
 and install Git is through a package manager such as @command{rpm}

-or @command{apt-get}---the installation is generally automatic.
+or @command{apt-get} -- the installation is generally automatic.

 The only required package is (usually) called @command{git-core},
 although some of the auxiliary @command{git@var{*}} packages are
 also useful (such as @command{gitk}).
 The only required package is (usually) called @command{git-core},
 although some of the auxiliary @command{git@var{*}} packages are
 also useful (such as @command{gitk}).


@@ -155,25 +143,19 @@ Alternatively, you can visit the Git website
 (@uref{http://git-scm.com/}) for downloadable binaries and
 tarballs.
 
 (@uref{http://git-scm.com/}) for downloadable binaries and
 tarballs.
 

-TODO: add Windows installation instructions (or @@ref@{Git on
-Windows@}).
-

 
 @node Initializing a repository
 @unnumberedsubsubsec Initializing a repository
 
 
 @node Initializing a repository
 @unnumberedsubsubsec Initializing a repository
 

-
-Once Git is installed, you'll need to create a new directory where
-your initial repository will be stored (the example below uses
-@file{~/lilypond-git/}, where @code{~} represents your home
-directory).  Run @command{git@tie{}init} from within the new
-directory to initialize an empty repository:
+Once Git is installed, get a copy of the source code:

 
 @example
 
 @example

-mkdir ~/lilypond-git/; cd ~/lilypond-git/
-git init
+git clone git://git.sv.gnu.org/lilypond.git ~/lilypond-git

 @end example
 
 @end example
 

+The above command will put the it in @file{~/lilypond-git}, where
+@code{~} represents your home directory.
+

 @subsubheading Technical details
 
 This creates (within the @file{~/lilypond-git/} directory) a
 @subsubheading Technical details
 
 This creates (within the @file{~/lilypond-git/} directory) a


@@ -190,13 +172,13 @@ input should be entered from the top directory of the Git
 repository being discussed (eg. @file{~/lilypond-git/}).  This is
 referred to as the @emph{top source directory}.}
 
 repository being discussed (eg. @file{~/lilypond-git/}).  This is
 referred to as the @emph{top source directory}.}
 

-Before downloading a copy of the main LilyPond repository, you
+Before working with the copy of the main LilyPond repository, you

 should configure some basic settings with the
 @command{git@tie{}config} command.  Git allows you to set both
 global and repository-specific options.
 
 To configure settings that affect all repositories, use the
 should configure some basic settings with the
 @command{git@tie{}config} command.  Git allows you to set both
 global and repository-specific options.
 
 To configure settings that affect all repositories, use the

-@command{--global} command line option.  For example, the first
+@option{--global} command line option.  For example, the first

 two options that you should always set are your @var{name} and
 @var{email}, since Git needs these to keep track of commit
 authors:
 two options that you should always set are your @var{name} and
 @var{email}, since Git needs these to keep track of commit
 authors:


@@ -224,9 +206,6 @@ change the default editor to @command{nano}, enter:
 git config --global core.editor @var{nano}
 @end example
 
 git config --global core.editor @var{nano}
 @end example
 

-TODO: Add instructions for changing the editor on Windows, which
-is a little different, I think. -mp
-

 @subsubheading Technical details
 
 Git stores the information entered with
 @subsubheading Technical details
 
 Git stores the information entered with


@@ -247,7 +226,7 @@ by the above commands would look like this:
 @end example
 
 Using the @command{git@tie{}config} command @emph{without} the
 @end example
 
 Using the @command{git@tie{}config} command @emph{without} the

-@command{--global} option configures repository-specific settings,
+@option{--global} option configures repository-specific settings,

 which are stored in the file @file{.git/config}.  This file is
 created when a repository is initialized (using
 @command{git@tie{}init}), and by default contains these lines:
 which are stored in the file @file{.git/config}.  This file is
 created when a repository is initialized (using
 @command{git@tie{}init}), and by default contains these lines:


@@ -522,7 +501,7 @@ git pull    # recommended for translators
 @end example
 
 If you're tracking the remote @code{master} branch, you should add
 @end example
 
 If you're tracking the remote @code{master} branch, you should add

-the @code{-r} option (short for @code{--rebase}) to keep commits
+the @option{-r} option (short for @option{--rebase}) to keep commits

 on your local branch current:
 
 @example
 on your local branch current:
 
 @example


@@ -530,7 +509,7 @@ git pull -r # use with caution when translating
 @end example
 
 If you don't edit translated documentation and don't want to type
 @end example
 
 If you don't edit translated documentation and don't want to type

-@code{-r} every time, configure the master branch to rebase by
+@option{-r} every time, configure the master branch to rebase by

 default with this command:
 
 @example
 default with this command:
 
 @example


@@ -629,7 +608,7 @@ git branch -d @var{name}
 @end example
 
 Git will ask you for confirmation if it sees that data would be
 @end example
 
 Git will ask you for confirmation if it sees that data would be

-lost by deleting the branch.  Use @code{-D} instead of @code{-d}
+lost by deleting the branch.  Use @option{-D} instead of @option{-d}

 to bypass this.  Note that you cannot delete a branch if it is
 currently checked out.
 
 to bypass this.  Note that you cannot delete a branch if it is
 currently checked out.
 


@@ -801,7 +780,7 @@ git commit -a
 @end example
 
 @noindent
 @end example
 
 @noindent

-The @code{-a} is short for @code{--all} which includes modified
+The @option{-a} is short for @option{--all} which includes modified

 and deleted files, but only those newly created files that have
 previously been added.
 
 and deleted files, but only those newly created files that have
 previously been added.
 


@@ -873,7 +852,7 @@ We prefer it if you follow the instructions in
 alternate method here.
 
 You should always run @command{git@tie{}pull@tie{}-r} (translators
 alternate method here.
 
 You should always run @command{git@tie{}pull@tie{}-r} (translators

-should leave off the @code{-r}) before doing this to ensure that
+should leave off the @option{-r}) before doing this to ensure that

 your patches are as current as possible.
 
 Once you have made one or more commits in your local repository,
 your patches are as current as possible.
 
 Once you have made one or more commits in your local repository,


@@ -924,14 +903,28 @@ LilyDev users should skip over these @q{install} instructions.
 Install @command{git-cl} by entering:
 
 @example
 Install @command{git-cl} by entering:
 
 @example

-git clone git://neugierig.org/git-cl.git
+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
 @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}).
+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
 
 
 @end enumerate
 


@@ -941,9 +934,12 @@ LilyDev users should perform these @q{configuration} instructions.
 
 @enumerate
 @item
 
 @enumerate
 @item

-You must have a gmail account; please create one if you do not
+You must have a google account; 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.
+

 @item
 Move into the top source directory and then configure @command{git
 cl} with the following commands.  If you do not understand any
 @item
 Move into the top source directory and then configure @command{git
 cl} with the following commands.  If you do not understand any


@@ -984,6 +980,13 @@ 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.
 
 your patch (with @command{git rebase} or @command{git reset})
 before pushing other stuff.
 

+@c don't make this one an @example; we don't want to make it easy
+@c for people to use this accidently
+Notifications of patches are automatically added to our issue
+tracker to reduce the chance of patches getting lost.  To suppress
+this (not recommended), add the @code{-n / --no-code-issue}
+option.
+

 @item
 @strong{Separate branch}: (complicated option)
 
 @item
 @strong{Separate branch}: (complicated option)
 


@@ -1018,9 +1021,9 @@ patch set will be posted to Rietveld, and you will be given a URL
 for your patch.
 
 @warning{Some installations of git-cl fail when uploading a patch
 for your patch.
 
 @warning{Some installations of git-cl fail when uploading a patch

-set that includes a .scm file.  When this happens, it can
-generally be fixed by editing the file @file{/etc/mime.types}.
-Add a line to this file containing @code{text/x-script.scheme scm}.}
+with certain filename extensions.  If this happens, it can
+generally be fixed by editing the list of exceptions at top of
+@file{git-cl.py}.}

 
 @subsubheading Announcing your patch set
 
 
 @subsubheading Announcing your patch set
 


@@ -1060,6 +1063,23 @@ running:
 git cl issue 0
 @end example
 
 git cl issue 0
 @end example
 

+@subsubheading Wait for a countdown
+
+Your patch will be available for reviews for the next few hours or
+days.  Three times a week, patches with no known problems are
+gathered into a @qq{patch countdown} and their status changed to
+@code{patch-countdown}.  The countdown is a 48-hour waiting period
+in which any final reviews or complaints should be made.
+
+During the countdown, your patch may be set to
+@code{patch-needs_work}, indicating that you should fix something
+(or at least discuss why the patch needs no modification).  If no
+problems are found, the patch will be set to @code{patch-push}.
+
+Once a patch has @code{patch-push}, it should be sent to your
+mentor for uploading.  If you have git push ability, look at
+@ref{Pushing to staging}.
+

 
 @node Advanced Git procedures
 @section Advanced Git procedures
 
 @node Advanced Git procedures
 @section Advanced Git procedures


@@ -1086,7 +1106,9 @@ several Git branches of LilyPond source code is presented.
 * Git log::
 * Applying remote patches::
 * Sending and receiving patches via email::
 * Git log::
 * Applying remote patches::
 * Sending and receiving patches via email::

+* Cleaning up multiple patches::

 * Commit access::
 * Commit access::

+* Pushing to staging::

 @end menu
 
 
 @end menu
 
 


@@ -1193,8 +1215,8 @@ any changes you have made!
 
 Sometimes git will become hopelessly confused, and you just want
 to get back to a known, stable state.  This command destroys any
 
 Sometimes git will become hopelessly confused, and you just want
 to get back to a known, stable state.  This command destroys any

-local changes you have made, but at least you get back to the
-current online version:
+local changes you have made in the currently checked-out branch,
+but at least you get back to the current online version:

 
 @example
 git reset --hard origin/master
 
 @example
 git reset --hard origin/master


@@ -1353,10 +1375,26 @@ provided on the Wine wiki at
 @uref{http://wiki.winehq.org/GitWine}.
 
 
 @uref{http://wiki.winehq.org/GitWine}.
 
 

+@node Cleaning up multiple patches
+@subsection Cleaning up multiple patches
+
+If you have been developing on your own branch for a while, you
+may have more commmits than is really sensible.  To revise your
+work and condense commits, use:
+
+@example
+git rebase origin/master
+git rebase -i origin/master
+@end example
+
+@warning{Be a bit cautious -- if you completely remove commits
+during the interactive session, you will... err... completely
+remove those commits.}
+
+

 @node Commit access
 @subsection Commit access
 
 @node Commit access
 @subsection Commit access
 

-

 Most contributors are not able to commit patches directly to the
 main repository---only members of the LilyPond development team
 have @emph{commit access}.  If you are a contributor and are
 Most contributors are not able to commit patches directly to the
 main repository---only members of the LilyPond development team
 have @emph{commit access}.  If you are a contributor and are


@@ -1378,6 +1416,9 @@ you visit the link, follow the steps for including the CAcert root
 certificate in your browser, given at
 @uref{http://savannah.gnu.org/tls/tutorial/}.
 
 certificate in your browser, given at
 @uref{http://savannah.gnu.org/tls/tutorial/}.
 

+@warning{Savannah will silently put your username in lower-case --
+do not try to use capital letters.}
+

 
 @item
 After registering, if you are not logged in automatically, login
 
 @item
 After registering, if you are not logged in automatically, login


@@ -1401,15 +1442,15 @@ Contributor of} on your @qq{My Group Membership} page.
 
 
 @item
 
 
 @item

-Generate an SSH @q{dsa} key pair.  Enter the following at the
+Generate an SSH @q{rsa} key pair.  Enter the following at the

 command prompt:
 
 @example
 command prompt:
 
 @example

-ssh-keygen -t dsa
+ssh-keygen -t rsa

 @end example
 
 When prompted for a location to save the key, press <ENTER> to
 @end example
 
 When prompted for a location to save the key, press <ENTER> to

-accept the default location (@file{~/.ssh/id_dsa}).
+accept the default location (@file{~/.ssh/id_rsa}).

 
 Next you are asked to enter an optional passphrase.  On most
 systems, if you use a passphrase, you will likely be prompted for
 
 Next you are asked to enter an optional passphrase.  On most
 systems, if you use a passphrase, you will likely be prompted for


@@ -1421,7 +1462,7 @@ though you may find it tedious to keep re-entering it.
 You can change/enable/disable your passphrase at any time with:
 
 @example
 You can change/enable/disable your passphrase at any time with:
 
 @example

-ssh-keygen -f ~/.ssh/id_dsa -p
+ssh-keygen -f ~/.ssh/id_rsa -p

 @end example
 
 Note that the GNOME desktop has a feature which stores your
 @end example
 
 Note that the GNOME desktop has a feature which stores your


@@ -1436,14 +1477,14 @@ gconftool-2 --set -t bool \
 @end example
 
 After setting up your passphrase, your private key is saved as
 @end example
 
 After setting up your passphrase, your private key is saved as

-@file{~/.ssh/id_dsa} and your public key is saved as
-@file{~/.ssh/id_dsa.pub}.
+@file{~/.ssh/id_rsa} and your public key is saved as
+@file{~/.ssh/id_rsa.pub}.

 
 
 @item
 
 
 @item

-Register your public SSH @q{dsa} key with Savannah.  From the
+Register your public SSH @q{rsa} key with Savannah.  From the

 @qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
 @qq{My Account Configuration} page, click on @qq{Edit SSH Keys},

-then paste the contents of your @file{~/.ssh/id_dsa.pub} file into
+then paste the contents of your @file{~/.ssh/id_rsa.pub} file into

 one of the @qq{Authorized keys} text fields, and click
 @qq{Update}.
 
 one of the @qq{Authorized keys} text fields, and click
 @qq{Update}.
 


@@ -1464,7 +1505,7 @@ git config remote.origin.url \
 @end example
 
 @noindent
 @end example
 
 @noindent

-where @var{user} is your username on Savannah.
+replacing @var{user} with your Savannah username.

 
 
 @item
 
 
 @item


@@ -1530,6 +1571,9 @@ Git properly in the previous step.
 @item
 Test your commit access with a dry run:
 
 @item
 Test your commit access with a dry run:
 

+@warning{Do not push directly to master; instead, push to staging.
+See @ref{Pushing to staging}.}
+

 @example
 git push --dry-run --verbose
 @end example
 @example
 git push --dry-run --verbose
 @end example


@@ -1545,9 +1589,17 @@ git config push.default matching
 @noindent
 Then @code{git@tie{}push} should work as before.  For more
 details, consult the @code{git@tie{}push} man page.
 @noindent
 Then @code{git@tie{}push} should work as before.  For more
 details, consult the @code{git@tie{}push} man page.

-@end enumerate

 
 
 
 

+@item
+Repeat the steps from generating an RSA key through to testing
+your commit access, for each machine from which you will be
+making commits, or you may simply copy the files from your
+local @file{~/.ssh} folder to the same folder on the other
+machine.
+
+@end enumerate
+

 @subsubheading Technical details
 
 @itemize
 @subsubheading Technical details
 
 @itemize


@@ -1613,9 +1665,66 @@ broadband may use a slightly smaller MTU for efficient transmission
 over ATM.  If this problem is encountered a possible work-around is
 to set the MTU in the local router to 1500.
 
 over ATM.  If this problem is encountered a possible work-around is
 to set the MTU in the local router to 1500.
 

+
+@node Pushing to staging
+@subsection Pushing to staging
+
+Do not push directly to the git @code{master} branch.  Instead,
+push to @code{staging}.
+
+You will not see your patch on @code{origin/master} until some
+automatic tests have been run.  These tests are run every couple
+of hours; please wait at least 12 hours before wondering if your
+patch has been lost.  Note that you can check the commits on
+@code{origin/staging} by looking at the git web interface on
+savannah.
+
+@subsubheading If your work is in a patch file
+
+Assuming that your patch is in a file called
+@file{0001-my-patch.patch}, and you are currently on git master,
+do:
+
+@example
+git checkout staging
+git pull -r
+git am 0001-my-patch.patch
+gitk
+git push origin staging
+git checkout master
+@end example
+
+@warning{Do not skip the @command{gitk} step; a quick 5-second
+check of the visual history can save a great deal of frustration
+later on.  You should only see that @command{staging} is only 1
+commit ahead of @code{origin/staging}.}
+
+@subsubheading If your work is in a branch
+
+If you are working on branches and your work in is
+@code{my_branch_name}, then do:
+
+@example
+git checkout staging
+git pull -r
+git merge my_branch_name
+gitk
+git push origin staging
+@end example
+
+@warning{Do not skip the @command{gitk} step; a quick 5-second
+check of the visual history can save a great deal of frustration
+later on.  You should see that @code{staging} is only ahead of
+@code{origin/staging} by the commits from your branch.}
+
+
+

 @node Git on Windows
 @section Git on Windows
 
 @node Git on Windows
 @section Git on Windows
 

+@warning{We heavily recommend that development be done with our
+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 If necessary, clear this up later  -td
 @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 If necessary, clear this up later  -td