@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.
+
+Advanced contributors will find the rest of this material quite
+useful, particularly if they are working on major new features.
@menu
* Using lily-git::
@node Using lily-git
@section Using lily-git
+@subsubheading Install and Configuration
+
+@enumerate
+@item
+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:
+
+@example
+@uref{http://code.google.com/p/msysgit/downloads/list}
+@end example
+
+@item Other operating systems: either install @command{git} with
+your package manager, or download it from the @qq{Binaries}
+section of:
+
+@example
+@uref{http://git-scm.com/download}
+@end example
+
+@end itemize
+
+
+@item
+Download the lily-git script from:
+
+@c don't change the cgit link below to gitweb; gitweb uses
+@c long filenames like "scripts_auxiliar_lily-git.tcl"
+
+@example
+@uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
+@end example
+
+@item
+To run the program from the command line, navigate to the
+directory containing @file{lily-git.tcl} and enter:
+
+@example
+wish lily-git.tcl
+@end example
+
+@end enumerate
+
+
+@subsubheading 1. Get source / Update source
+
+When you click the @qq{Get source} button, @command{lily-git} 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
+@qq{Command output} window will display @qq{Done}, and the button
+label will change to say @qq{Update source}.
+
+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.
+
+@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}, the
+@qq{Update source} button will take any new additions and add it
+to whatever is currently in your repository's history.
+@end quotation
+
+
+@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.
+
+When you're finished making the changes for your first 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. See @ref{Commits and patches}
+for more information regarding commits and commit messages.
+
+After entering a commit message, click @qq{OK} to finalize the
+commit.
+
-FIXME: Add instructions for using @command{lily-git} here.
+@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.
+
+Note that 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}
+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 your mentor if you have one. Otherwise, write
+an email (must be less than 64 KB) to
+@email{lilypond-devel@@gnu.org} briefly explaining your work, with
+the patch files attached. Translators should send patches to
+@email{translations@@lilynet.net}.
+
+
+@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}).
@node Starting with Git
@subsection Setting up
-FIXME: Remove this note if incorporating Windows instructions
+TODO: Remove this note if incorporating Windows instructions
throughout this section:
@warning{These instructions assume that you are using the
(@uref{http://git-scm.com/}) for downloadable binaries and
tarballs.
-FIXME: add Windows installation instructions (or @@ref@{Git on
+TODO: add Windows installation instructions (or @@ref@{Git on
Windows@}).
git config --global core.editor @var{nano}
@end example
-FIXME: Add instructions for changing the editor on Windows, which
+TODO: Add instructions for changing the editor on Windows, which
is a little different, I think. -mp
@subsubheading Technical details
patch, and this may create a conflict. If this happens, see
@ref{Resolving conflicts}.
-FIXME: I think the next paragraph is confusing. Perhaps prepare
+TODO: I think the next paragraph is confusing. Perhaps prepare
the reader for new terms `committish' and `head'? -mp
@warning{translators and documentation editors, if you have
documentation except committishes updates (possibly after having
rebased), then update the committishes and push them.}
-FIXME: when committishes automatic conditional update have been
+TODO: when committishes automatic conditional update have been
tested and documented, append the following to the warning above:
Note that using update-committishes make target generally touches
committishes.
* Making commits::
* Commit messages::
* Making patches::
+* Uploading a patch for review::
@end menu
@example
-# Please enter the commit message for your changes. Lines starting
+# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch master
# Changes to be committed:
@node Making patches
@unnumberedsubsubsec Making patches
-
If you want to share your changes with other contributors and
developers, you need to generate @emph{patches} from your commits.
+We prefer it if you follow the instructions in
+@ref{Uploading a patch for review}. However, we present an
+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
your patches are as current as possible.
⋮
@end example
-Send an email to @email{lilypond-devel@@gnu.org} briefly
-explaining your work, with the patch files attached. Translators
-should send patches to @email{translations@@lilynet.net}. After
-your patches are reviewed, the developers may push one or more of
-them to the main repository or discuss them with you.
+Send an email (must be less than 64 KB) to
+@email{lilypond-devel@@gnu.org} briefly explaining your work, with
+the patch files attached. Translators should send patches to
+@email{translations@@lilynet.net}. After your patches are
+reviewed, the developers may push one or more of them to the main
+repository or discuss them with you.
-@seealso
-If your patch includes a significant amount of code, you may want
-to see @ref{Adding or modifying features}, especially @emph{Post
-patch for comments}.
+@node Uploading a patch for review
+@unnumberedsubsubsec Uploading a patch for review
+
+Any non-trivial change should be uploaded to our @qq{Rietveld}
+code review website:
+
+@example
+@uref{http://codereview.appspot.com/}
+@end example
+
+@subsubheading Initial setup
+
+This requires the use of an external package, git-cl, and an email
+account on Google.
+
+@command{git-cl} is installed by:
+
+@example
+git clone git://neugierig.org/git-cl.git
+@end example
+
+Then, add the @file{git-cl} directory to your PATH, or create a
+symbolic link to the @command{git-cl} and @command{upload.py} in
+one of your PATH directories (like @file{usr/bin}). Then
+configure the program by running:
+
+@example
+git cl config
+@end example
+
+@noindent
+in the LilyPond git directory and answering the questions that
+are asked. If you do not understand the question answer with just
+a newline (CR).
+
+@subsubheading Uploading patch set
+
+There are two methods, depending on your git setup.
+
+@itemize
+@item
+@strong{Separate branch}:
+
+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:
+
+@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:
+
+@example
+git cl upload origin/master
+@end example
+
+@noindent
+can be used.
+
+@item
+@strong{Master branch}:
+
+If you added your patch to @code{master}, then make sure that you
+are up-to-date (by running @code{git pull -r}), and then run:
+
+@example
+git cl upload origin/master
+@end example
+
+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.
+
+@end itemize
+
+After prompting for your Google email address and password, the
+patch set will be posted to Rietveld.
+
+@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.
+
+@subsubheading Revisions
+
+As revisions are made in response to comments, successive patch sets
+for the same issue can be uploaded by reissuing the git-cl command
+with the modified branch checked out.
+
+Sometimes in response to comments on revisions, the best way to
+work may require creation of a new branch in git. In order to
+associate the new branch with an existing Rietveld issue,
+the following command can be used:
+
+@example
+git cl issue issue-number
+@end example
+
+@noindent
+where @code{issue-number} is the number of the existing Rietveld
+issue.
+
+@subsubheading Resetting git cl
+
+If @command{git cl} becomes confused, you can @qq{reset} it by
+running:
+
+@example
+git cl issue 0
+@end example
@node Advanced Git procedures
A @emph{branch} is nothing more than a pointer to a particular
commit, which is called the @emph{head} of the branch; when
-referring to a branch, one often acutally thinks about its head
+referring to a branch, one often actually thinks about its head
and the ancestor commits of the head.
Now we will explain the two last commands you used to get the
The commands above don't only bring you the latest version of the
-sources, but also the full history of revisions (revisons, also
+sources, but also the full history of revisions (revisions, also
called commits, are changes made to the sources), stored in the
@file{.git} directory. You can browse this history with
@subsection Applying remote patches
-FIXME: Explain how to determine if a patch was created with
+TODO: Explain how to determine if a patch was created with
@code{git@tie{}format-patch}.
Well-formed git patches created with @code{git@tie{}format-patch}
certificate in your browser, given at
@uref{http://savannah.gnu.org/tls/tutorial/}.
+
@item
After registering, if you are not logged in automatically, login
at @uref{https://savannah.gnu.org/account/login.php}---this should
take you to your @qq{my} page
(@uref{https://savannah.gnu.org/my/}).
+
@item
Click on the @qq{My Groups} link to access the @qq{My Group
Membership} page. From there, find the @qq{Request for Inclusion}
activated, LilyPond should appear under the heading @qq{Groups I'm
Contributor of} on your @qq{My Group Membership} page.
+
@item
-Go to the @qq{My Account Configuration} page. From there, click
-on @qq{Edit SSH Keys} and follow the instructions given.
+Generate an SSH @q{dsa} key pair. Enter the following at the
+command prompt:
+
+@example
+ssh-keygen -t dsa
+@end example
+
+When prompted for a location to save the key, press <ENTER> to
+accept the default location (@file{~/.ssh/id_dsa}).
+
+Next you are asked to enter an optional passphrase. On most
+systems, if you use a passphrase, you will likely be prompted for
+it every time you use @command{git@tie{}push} or
+@command{git@tie{}pull}. You may prefer this since it can protect
+you from your own mistakes (like pushing when you mean to pull),
+though you may find it tedious to keep re-entering it.
-FIXME: Explain the confusing warning I always get. -mp
+You can change/enable/disable your passphrase at any time with:
+
+@example
+ssh-keygen -f ~/.ssh/id_dsa -p
+@end example
+
+Note that the GNOME desktop has a feature which stores your
+passphrase for you for an entire GNOME session. If you use a
+passphrase to @qq{protect you from yourself}, you will want to
+disable this feature, since you'll only be prompted once. Run the
+following command, then logout of GNOME and log back in:
+
+@example
+gconftool-2 --set -t bool \
+ /apps/gnome-keyring/daemon-components/ssh false
+@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}.
+
+
+@item
+Register your public SSH @q{dsa} 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
+one of the @qq{Authorized keys} text fields, and click
+@qq{Update}.
+
+Savannah should respond with something like:
+
+@example
+Success: Key #1 seen Keys registered
+@end example
-FIXME: Maybe add a note about enabling/disabling SSH passphrase?
@item
Configure Git to use the SSH protocol (instead of the GIT
@noindent
where @var{user} is your username on Savannah.
+
@item
After your membership has been activated and you've configured Git
-to use SSH, try doing a @command{git@tie{}pull} or
-@command{git@tie{}pull@tie{}-r}. If that succeeds, this indicates
-that your SSH key stored at Savannah is working properly.
+to use SSH, test the connection with:
+
+@example
+git pull --verbose
+@end example
+
+SSH should issue the following warning:
+
+@example
+The authenticity of host 'git.sv.gnu.org (140.186.70.72)' can't
+be established.
+RSA key fingerprint is
+80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5.
+Are you sure you want to continue connecting (yes/no)?
+@end example
+
+Make sure the RSA key fingerprint displayed matches the one above.
+If it doesn't, respond @qq{no} and check that you configured Git
+properly in the previous step. If it does match, respond
+@qq{yes}. SSH should then issue another warning:
+
+@example
+Warning: Permanently added 'git.sv.gnu.org,140.186.70.72' (RSA) to
+the list of known hosts.
+@end example
+
+The list of known hosts is stored in the file
+@file{~/.ssh/known_hosts}.
+
+At this point, you are prompted for your passphrase if you have
+one, then Git will attempt a pull.
+
+If @command{git@tie{}pull@tie{}--verbose} fails, you should see
+error messages like these:
+
+@example
+Permission denied (publickey).
+fatal: The remote end hung up unexpectedly
+@end example
+
+If you get the above error, you may have made a mistake when
+registering your SSH key at Savannah. If the key is properly
+registered, you probably just need to wait for the Savannah server
+to activate it. It usually takes a few minutes for the key to be
+active after registering it, but if it still doesn't work after an
+hour, ask for help on the mailing list.
+
+If @command{git@tie{}pull@tie{}--verbose} succeeds, the output
+will include a @q{From} line that shows @q{ssh} as the protocol:
+
+@example
+From ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond
+@end example
+
+If the protocol shown is not @q{ssh}, check that you configured
+Git properly in the previous step.
-FIXME: show what success/failure look like.
@item
Test your commit access with a dry run:
@end example
@end itemize
+@knownissues
+Encryption protocols, including ssh, generally do not permit packet
+fragmentation to avoid introducing a point of insecurity. This
+means that the maximum packet size must not exceed the smallest
+MTU (Maximum Transmission Unit) set in the routers along the path.
+This smallest MTU is determined by a procedure during call set-up
+which relies on the transmission over the path of ICMP packets.
+If any of the routers in the path block ICMP packets this mechanism
+fails, resulting in the possibility of packets being transmitted
+which exceed the MTU of one of the routers. If this happens the
+packet is discarded, causing the ssh session to hang, timeout or
+terminate with the error message
+
+@example
+ssh: connect to host <host ip addr> port 22: Bad file number
+fatal: The remote end hung up unexpectedly
+@end example
+
+depending on precisely when in the proceedings the first large
+packet is transmitted. Most routers on the internet have MTU
+set to 1500, but routers installed in homes to connect via
+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 Git on Windows
@section Git on Windows
@c But it is probably best for windows users to have it all together
@c If necessary, clear this up later -td
-FIXME: Decide what to do with this... Pare it down? Move
+TODO: Decide what to do with this... Pare it down? Move
paragraphs next to analogous Unix instructions? -mp
@subsection Background to nomenclature
Git is a system for tracking the changes made to source files by a
distributed set of editors. It is designed to work without a
-master repository, but we have chosen to have a master respository
+master repository, but we have chosen to have a master repository
for LilyPond files. Editors hold a local copy of the master
repository together with any changes they have made locally.
Local changes are held in a local @q{branch}, of which there may
@subsection Git GUI
Almost all subsequent work will use the Git Graphical User
-Interface, which avoids having to type command line commands. To
+Interface, which avoids having to type command line commands. To
start Git GUI first start the Git bash shell by clicking on the
desktop icon, and type