X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=sidebyside;f=Documentation%2Fcontributor%2Fsource-code.itexi;h=de292c99f6d851cdbc763adf1819e006726e8bdc;hb=b963dc41847ab077d0bf32e74d2e168ea2a84883;hp=8c2c101e446e58e64388090df740079d633cfdda;hpb=618cbed466c3e7fb9b9b3f2d2ad9f60a61a401d6;p=lilypond.git

diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi
index 8c2c101e44..de292c99f6 100644
--- a/Documentation/contributor/source-code.itexi
+++ b/Documentation/contributor/source-code.itexi
@@ -4,14 +4,14 @@
 @node Working with source code
 @chapter Working with source code
 
-New contributors should only read @ref{Using lily-git}.  Please
-ignore the rest of this chapter.
+@warning{New contributors should read @ref{Quick start}, and in
+particular @ref{Using lily-git}, instead of this chapter.}
 
-Advanced contributors will find the rest of 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.
 
 @menu
-* Using lily-git::
+* Manually installing lily-git.tcl::
 * Starting with Git::
 * Basic Git procedures::
 * Advanced Git procedures::
@@ -21,21 +21,19 @@ useful, particularly if they are working on major new features.
 @end menu
 
 
-@c if you change this node name, you'll need to change the @ref in
-@c web/ and/or included/, along with all the translations.
-@node Using lily-git
-@section Using lily-git
+@node Manually installing lily-git.tcl
+@section Manually installing lily-git.tcl
 
-@command{lily-git.tcl} is a graphical tool to help you access and
-share changes to the lilypond source code.
+We have created an easy-to-use GUI to simplify git for new
+contributors.  If you are comfortable with the command-line, then
+skip ahead to @ref{Starting with Git}.
 
-@menu
-* Install and configuration of lily-git.tcl::
-* Daily use of lily-git.tcl::
-@end menu
+@warning{These instructions are only for people who are @emph{not}
+using @ref{Lilydev}.}
 
-@node Install and configuration of lily-git.tcl
-@unnumberedsubsec Install and configuration of @command{lily-git.tcl}
+@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 be getting a bit icky.  -gp
 
 @enumerate
 @item
@@ -43,9 +41,6 @@ If you haven't already, download and install Git.
 
 @itemize
 
-@item
-Lilybuntu users: git has already been installed for you.
-
 @item Windows users: download the @code{.exe} file labeled
 @qq{Full installer for official Git} from:
 
@@ -70,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"
 
-@example
+@smallexample
 @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
@@ -87,139 +82,26 @@ 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
-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}.
 
 @item
 Navigate to the @file{lilypond-git/} directory to view the source
-files.  You should now be able to modify the source files using
-your normal text editor.
+files.
 
 @end enumerate
 
-@quotation
-Advanced note: 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.
-@end quotation
-
-
-@node Daily use of lily-git.tcl
-@unnumberedsubsec Daily use of @command{lily-git.tcl}
-
-@warning{Only work on one set of changes at once.  Do not start
-work on any new changes until your first set has been accepted.}
-
-@subsubheading 1. Update source
-
-At the beginning of each session of lilypond work, you should
-click the @qq{Update source} button to get the latest changes to
-the source code.
-
-@warning{In some rare and unfortunate circumstances, this will
-result in a @emph{merge conflict}.  If this occurs, follow the
-instructions for @qq{Abort changes}, below.  Your work will not be
-lost.}
-
-
-@subsubheading 2a. New local commit
-
-A single commit typically represents one logical set of related
-changes (such as a bug-fix), and may incorporate changes to
-multiple files at the same time.
+@warning{Throughout the rest of this manual, most command-line
+input should be entered from @file{~/lilypond-git/}.  This is
+referred to as the @emph{top source directory}.}
 
-When you're finished making the changes for a commit, click the
-@qq{New local commit} button.  This will open the @qq{Git Commit
-Message} window.  The message header is required, and the message
-body is optional.
-
-After entering a commit message, click @qq{OK} to finalize the
-commit.
-
-@quotation
-Advanced note: For more information regarding commits and commit
-messages, see @ref{Commits and patches}.
-@end quotation
-
-
-@subsubheading 2b. Amend previous commit
-
-You can go back and make changes to the most recent commit with
-the @qq{Amend previous commit} button.  This is useful if a
-mistake is found after you have clicked the @qq{New local commit}
-button.
-
-To amend the most recent commit, re-edit the source files as
-needed and then click the @qq{Amend previous commit} button.  The
-earlier version of the commit is not saved, but is replaced by the
-new one.
-
-@warning{This does not update the patch @strong{files}; if you
-have a patch file from an earlier version of the commit, you will
-need to make another patch set when using this feature.  The old
-patch file will not be saved, but will be replaced by the new one
-after you click on @qq{Make patch set}.}
-
-
-@subsubheading 3. Make patch set
-
-Before making a patch set from any commits, you should click the
-@qq{Update source} button to make sure the commits are based on
-the most recent remote snapshot.
-
-When you click the @qq{Make patch set} button,
-@command{lily-git.tcl} will produce patch files for any new
-commits, saving them to the current directory.  The command output
-will display the name of the new patch files near the end of the
-output:
-
-@example
-0001-CG-add-lily-git-instructions.patch
-Done.
-@end example
-
-Send patch files to the appropriate place:
-
-@itemize
-@item
-If you have a mentor, send it to them via email.
-
-@item
-New contributors should send the patch attached to an email to
-@email{frogs@@lilynet.net}.  Please add @qq{[PATCH]} to the
-subject line.
-
-@item
-Translators should send patches to
-@email{translations@@lilynet.net}.
-
-@item
-More experienced contributors should upload the patch for
-web-based review.  This requires additional software and use of
-the command-line; see @ref{Uploading a patch for review}.
-
-@end itemize
-
-
-@subsubheading The @qq{Abort changes -- Reset to origin} button
-
-@warning{Only use this if your local commit history gets
-hopelessly confused!}
-
-The button labeled @qq{Abort changes -- Reset to origin} will copy
-all changed files to a subdirectory of @file{lilypond-git/} named
-@file{aborted_edits/}, and will reset the repository to the
-current state of the remote repository (at @code{git.sv.gnu.org}).
+Further instructions are in @ref{Daily use of lily-git.tcl}.
 
 
 @node Starting with Git
 @section Starting with Git
 
-
 Using the Git program directly (as opposed to using the
 @command{lily-git.tcl} GUI) allows you to have much greater control
 over the contributing process.  You should consider using Git if
@@ -236,10 +118,6 @@ multiple projects concurrently.
 @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}.}
@@ -254,10 +132,9 @@ skip to @ref{Git on Windows}.}
 @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}
-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}).
@@ -266,25 +143,19 @@ Alternatively, you can visit the Git website
 (@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
 
-
-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
-mkdir ~/lilypond-git/; cd ~/lilypond-git/
-git init
+git clone git://git.sv.gnu.org/lilypond.git ~/lilypond-git
 @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
@@ -299,15 +170,15 @@ 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
-referred to as a @emph{top source directory}.}
+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
-@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:
@@ -335,9 +206,6 @@ change the default editor to @command{nano}, enter:
 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
@@ -358,7 +226,7 @@ by the above commands would look like this:
 @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:
@@ -633,7 +501,7 @@ git pull    # recommended for translators
 @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
@@ -641,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
-@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
@@ -740,7 +608,7 @@ git branch -d @var{name}
 @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.
 
@@ -912,7 +780,7 @@ git commit -a
 @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.
 
@@ -984,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
-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,
@@ -1025,18 +893,23 @@ code review website:
 @uref{http://codereview.appspot.com/}
 @end example
 
-@subsubheading Initial setup
+@subsubheading @command{git-cl} install
 
-@enumerate
+LilyDev users should skip over these @q{install} instructions.
 
-@item
-You must have a gmail account.
+@enumerate
 
 @item
 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
@@ -1045,17 +918,36 @@ symbolic link to the @command{git-cl} and @command{upload.py}
 scripts in one of your PATH directories (such as
 @file{$HOME/bin}).
 
+@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}.  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.  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
@@ -1080,6 +972,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.
 
+@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)
 
@@ -1110,15 +1009,23 @@ can be used.
 @end itemize
 
 After prompting for your Google email address and password, the
-patch set will be posted to Rietveld.
+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
+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
 
-You should then announce the patch by sending an email to
-@code{lilypond-devel}, with a subject line starting with PATCH:,
-asking for comments on the patch.  Alternately, you may Publish +
-Mail a (bogus) comment, in order to send an email to
-lilypond-devel.
+You should then announce the patch by logging into the code review
+issue webpage and using @qq{Publish + Mail Comments} to add a
+(mostly bogus) comment to your issue.  The text of your comment
+will be sent to our developer mailing list.
+
+@warning{There is no automatic notification of a new patch; you
+must add a comment yourself.}
 
 @subsubheading Revisions
 
@@ -1148,6 +1055,23 @@ running:
 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
@@ -1174,7 +1098,9 @@ several Git branches of LilyPond source code is presented.
 * Git log::
 * Applying remote patches::
 * Sending and receiving patches via email::
+* Cleaning up multiple patches::
 * Commit access::
+* Pushing to staging::
 @end menu
 
 
@@ -1281,8 +1207,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
-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
@@ -1441,10 +1367,26 @@ provided on the Wine wiki at
 @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
 
-
 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
@@ -1466,6 +1408,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/}.
 
+@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
@@ -1489,15 +1434,15 @@ Contributor of} on your @qq{My Group Membership} page.
 
 
 @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
-ssh-keygen -t dsa
+ssh-keygen -t rsa
 @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
@@ -1509,7 +1454,7 @@ though you may find it tedious to keep re-entering it.
 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
@@ -1524,14 +1469,14 @@ gconftool-2 --set -t bool \
 @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
-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},
-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}.
 
@@ -1552,7 +1497,7 @@ git config remote.origin.url \
 @end example
 
 @noindent
-where @var{user} is your username on Savannah.
+replacing @var{user} with your Savannah username.
 
 
 @item
@@ -1618,6 +1563,9 @@ Git properly in the previous step.
 @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
@@ -1633,9 +1581,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.
-@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
@@ -1701,9 +1657,54 @@ 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.
 
+
+@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
+git push origin staging
+git checkout master
+@end example
+
+@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
+git push origin staging
+@end example
+
+
+
 @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