X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fsource-code.itexi;h=65ac35e3b6b68e20aa5df9b5670c8b522c115264;hb=512542520ca60b7018df2de43e2c5f51bf05432c;hp=80c78edbfe136fe7fc5f2d30976832270bc7415e;hpb=8310faf7732b7e4b26d2951de056b86df76eb113;p=lilypond.git diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi index 80c78edbfe..65ac35e3b6 100644 --- a/Documentation/contributor/source-code.itexi +++ b/Documentation/contributor/source-code.itexi @@ -4,14 +4,13 @@ @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:: * Starting with Git:: * Basic Git procedures:: * Advanced Git procedures:: @@ -21,205 +20,9 @@ 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 - -@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} - -@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 @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 -@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 @command{lily-git.tcl} and enter: - -@example -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 - -@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 - - -@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 @@ -299,7 +102,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