X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fsource-code.itexi;h=bac6bed2d6a3f50405d5059caa86b92801b4b9d7;hb=02c66956a342eccc4858111ad587ce8b8a5e44b8;hp=533eca6a10f5d6933140a456409d2e2dd574fd6d;hpb=737bdcc2e6e75483d8ce6e824f211a36c969a1ea;p=lilypond.git diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi index 533eca6a10..bac6bed2d6 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,62 +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. - -@menu -* Install and configuration of lily-git.tcl:: -* Daily use of lily-git.tcl:: -@end menu - -@node Install and configuration of lily-git.tcl -@unnumberedsubsec Install and configuration of @command{lily-git.tcl} - -@subsubheading Lilybuntu - -@warning{The rest of this manual assumes that you are using the -command-line; go to @clicksequence{Applications @click{} -Accessories @click{} Terminal}.} - -@enumerate -@item -@code{lily-git.tcl} has already been install for you. Simply type -(or copy&paste): - -@example -cd -wish lily-git.tcl -@end example - -@item -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 -@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. - -@end enumerate - -You should now progress to @ref{Compiling with lilybuntu}. - -@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}.} +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}. +@warning{These instructions are only for people who are @emph{not} +using @ref{Lilydev}.} -@subsubheading Other operating music systems +@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 @@ -84,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: @@ -111,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 @@ -124,11 +78,26 @@ wish lily-git.tcl @end example @item -Go read the lilybuntu instructions, starting from the @qq{get -source} step. +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 +@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. @end enumerate +@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}.} + +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 @@ -137,116 +106,9 @@ source} button will take any new additions and add it to whatever is currently in your repository's history.} -@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. - -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. - -@advanced{for more information regarding commits and commit -messages, see @ref{Commits and patches}.} - - -@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}). - - @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 @@ -334,7 +196,7 @@ should configure some basic settings with the 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: @@ -385,7 +247,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: @@ -660,7 +522,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 @@ -668,7 +530,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 @@ -767,7 +629,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. @@ -939,7 +801,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. @@ -1011,7 +873,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, @@ -1052,18 +914,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 @@ -1072,11 +939,21 @@ 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 gmail account; please create one if you do not +have one already. @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/ @@ -1146,6 +1023,11 @@ After prompting for your Google email address and password, the 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 +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}.} + @subsubheading Announcing your patch set You should then announce the patch by logging into the code review @@ -1153,6 +1035,9 @@ 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 As revisions are made in response to comments, successive patch sets @@ -1207,6 +1092,7 @@ 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:: @end menu @@ -1314,8 +1200,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 @@ -1474,6 +1360,23 @@ 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 @@ -1499,6 +1402,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 @@ -1522,15 +1428,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 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 @@ -1542,7 +1448,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 @@ -1557,14 +1463,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}. @@ -1585,7 +1491,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 @@ -1666,9 +1572,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