X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fsource-code.itexi;h=27e30b165a60b326cf7bc87af252181f42484802;hb=0a307371e831a7e956ce4ebee3a35d6c979e2dda;hp=0c837b872d7c3f6fb563cc00590896235aa56602;hpb=223ad8f5799657a5b628d862dd927f4197486b02;p=lilypond.git diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi index 0c837b872d..27e30b165a 100644 --- a/Documentation/contributor/source-code.itexi +++ b/Documentation/contributor/source-code.itexi @@ -20,7 +20,108 @@ @section Using lily-git -FIXME: Add instructions for using @command{lily-git} here. +If you haven't already, download and install Git. Go to +@uref{http://git-scm.com/download}, and in the @qq{Binaries} +section, select the appropriate package for your operating system. +Windows users should visit +@uref{http://code.google.com/p/msysgit/downloads/list} and +download the @file{.exe} file labeled @qq{Full installer for +official Git}. + +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 + +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 + + +@subsubheading 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 complete 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. + + +@subsubheading 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 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've clicked the @qq{New local commit} +button. To amend the most recent commit, edit the source files as +needed and click the button. The earlier version of the commit is +not saved, but is replaced by the new one. + +Note that this does not update patch 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 is +not saved, but is replaced by the new one. + + +@subsubheading 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 @@ -44,7 +145,7 @@ multiple projects concurrently. @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 @@ -73,7 +174,7 @@ Alternatively, you can visit the Git website (@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@}). @@ -142,7 +243,7 @@ change the default editor to @command{nano}, enter: 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 @@ -485,7 +586,7 @@ Note that @command{git@tie{}stash@tie{}pop} will try to apply a 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 @@ -498,7 +599,7 @@ 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.} -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. @@ -810,11 +911,12 @@ will have names that look something like this: ⋮ @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 @@ -1058,7 +1160,7 @@ repositories.} @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} @@ -1140,12 +1242,14 @@ 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/}. + @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} @@ -1159,13 +1263,60 @@ Manager activates your membership. Once your membership is activated, LilyPond should appear under the heading @qq{Groups I'm Contributor of} on your @qq{My Group Membership} page. + +@item +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 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. + +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 -Go to the @qq{My Account Configuration} page. From there, click -on @qq{Edit SSH Keys} and follow the instructions given. +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}. -FIXME: Explain the confusing warning I always get. -mp +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 @@ -1179,13 +1330,66 @@ git config remote.origin.url \ @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: @@ -1248,6 +1452,31 @@ should add these lines to @file{.git/config}: @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 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 @@ -1255,7 +1484,7 @@ should add these lines to @file{.git/config}: @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