X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fsource-code.itexi;h=ba1875c0d670392e71c52b1269a6eedc5f3b3e0b;hb=24bcb253054634563f444440ea38443349c14355;hp=80c78edbfe136fe7fc5f2d30976832270bc7415e;hpb=cdcb5b726073cb2d8d794146f0d128891ac81e7e;p=lilypond.git diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi index 80c78edbfe..ba1875c0d6 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: @@ -93,133 +88,27 @@ 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. - -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 - +@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}.} -@subsubheading The @qq{Abort changes -- Reset to origin} button +Further instructions are in @ref{Daily use of lily-git.tcl}. -@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}). +@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 +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.} @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 @@ -299,7 +188,7 @@ 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 should configure some basic settings with the @@ -1025,12 +914,11 @@ 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: @@ -1045,11 +933,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/ @@ -1119,6 +1017,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 @@ -1126,6 +1029,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 @@ -1180,6 +1086,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 @@ -1287,8 +1194,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 @@ -1447,6 +1354,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 @@ -1472,6 +1396,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