@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 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.
+
+
+@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}.
+
-FIXME: Add instructions for using @command{lily-git} here.
+@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.
⋮
@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
@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}).
-FIXME: Explain the confusing warning I always get. -mp
+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.
+
+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.
+After your membership has been activated and you’ve configured Git
+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
projects / lilypond.git / blobdiff