X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fsource-code.itexi;h=ea8fc8775c59007ed7831b1b3c07260edc1e9887;hb=67f64c0bdf4cd469de73b135df5ba61cbfea15f7;hp=54d8ba7d7e7d94affcf3fb73c395d2129f385cdc;hpb=c1d5bb448321d688185e0c6b798575d4c325ae80;p=lilypond.git diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi index 54d8ba7d7e..ea8fc8775c 100644 --- a/Documentation/contributor/source-code.itexi +++ b/Documentation/contributor/source-code.itexi @@ -65,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 @@ -82,7 +82,7 @@ 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 +directory (around 150@tie{}Mb). 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}. @@ -98,13 +98,6 @@ 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 -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 @@ -125,10 +118,6 @@ multiple projects concurrently. @node Setting up @subsection Setting up - -TODO: Remove this note if incorporating Windows instructions -throughout this section: - @warning{These instructions assume that you are using the command-line version of Git 1.5 or higher. Windows users should skip to @ref{Git on Windows}.} @@ -143,10 +132,9 @@ skip to @ref{Git on Windows}.} @node Installing Git @unnumberedsubsubsec Installing Git - If you are using a Unix-based machine, the easiest way to download and install Git is through a package manager such as @command{rpm} -or @command{apt-get}---the installation is generally automatic. +or @command{apt-get} -- the installation is generally automatic. The only required package is (usually) called @command{git-core}, although some of the auxiliary @command{git@var{*}} packages are also useful (such as @command{gitk}). @@ -155,25 +143,19 @@ Alternatively, you can visit the Git website (@uref{http://git-scm.com/}) for downloadable binaries and tarballs. -TODO: add Windows installation instructions (or @@ref@{Git on -Windows@}). - @node Initializing a repository @unnumberedsubsubsec Initializing a repository - -Once Git is installed, you'll need to create a new directory where -your initial repository will be stored (the example below uses -@file{~/lilypond-git/}, where @code{~} represents your home -directory). Run @command{git@tie{}init} from within the new -directory to initialize an empty repository: +Once Git is installed, get a copy of the source code: @example -mkdir ~/lilypond-git/; cd ~/lilypond-git/ -git init +git clone git://git.sv.gnu.org/lilypond.git ~/lilypond-git @end example +The above command will put the it in @file{~/lilypond-git}, where +@code{~} represents your home directory. + @subsubheading Technical details This creates (within the @file{~/lilypond-git/} directory) a @@ -190,13 +172,13 @@ input should be entered from the top directory of the Git repository being discussed (eg. @file{~/lilypond-git/}). This is referred to as the @emph{top source directory}.} -Before downloading a copy of the main LilyPond repository, you +Before working with the copy of the main LilyPond repository, you should configure some basic settings with the @command{git@tie{}config} command. Git allows you to set both 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: @@ -224,9 +206,6 @@ change the default editor to @command{nano}, enter: git config --global core.editor @var{nano} @end example -TODO: Add instructions for changing the editor on Windows, which -is a little different, I think. -mp - @subsubheading Technical details Git stores the information entered with @@ -247,7 +226,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: @@ -522,7 +501,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 @@ -530,7 +509,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 @@ -629,7 +608,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. @@ -801,7 +780,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. @@ -873,7 +852,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, @@ -924,14 +903,28 @@ LilyDev users should skip over these @q{install} instructions. 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 -Add the @file{git-cl/} directory to your PATH, or create a -symbolic link to the @command{git-cl} and @command{upload.py} -scripts in one of your PATH directories (such as -@file{$HOME/bin}). +Add the @file{git-cl/} directory to your PATH, +or create a symbolic link to the @command{git-cl} +and @command{upload.py} scripts in one of your PATH +directories (such as @file{$HOME/bin}). + +In Ubuntu (and Lilydev), you can add directories to PATH +by adding this line to a hidden file @file{.bashrc}, +located in your home directory: + +@example +PATH=~/type-here-directory-containing-git-cl:"$@{PATH@}" +@end example @end enumerate @@ -941,9 +934,12 @@ LilyDev users should perform these @q{configuration} instructions. @enumerate @item -You must have a gmail account; please create one if you do not +You must have a google account; please create one if you do not have one already. +Note that a google account does not need to be a gmail account; you can +use any email address for your google account when you sign up. + @item Move into the top source directory and then configure @command{git cl} with the following commands. If you do not understand any @@ -984,6 +980,13 @@ If you have git push ability, make sure that you @emph{remove} your patch (with @command{git rebase} or @command{git reset}) before pushing other stuff. +@c don't make this one an @example; we don't want to make it easy +@c for people to use this accidently +Notifications of patches are automatically added to our issue +tracker to reduce the chance of patches getting lost. To suppress +this (not recommended), add the @code{-n / --no-code-issue} +option. + @item @strong{Separate branch}: (complicated option) @@ -1018,9 +1021,9 @@ 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}.} +with certain filename extensions. If this happens, it can +generally be fixed by editing the list of exceptions at top of +@file{git-cl.py}.} @subsubheading Announcing your patch set @@ -1060,6 +1063,23 @@ running: git cl issue 0 @end example +@subsubheading Wait for a countdown + +Your patch will be available for reviews for the next few hours or +days. Three times a week, patches with no known problems are +gathered into a @qq{patch countdown} and their status changed to +@code{patch-countdown}. The countdown is a 48-hour waiting period +in which any final reviews or complaints should be made. + +During the countdown, your patch may be set to +@code{patch-needs_work}, indicating that you should fix something +(or at least discuss why the patch needs no modification). If no +problems are found, the patch will be set to @code{patch-push}. + +Once a patch has @code{patch-push}, it should be sent to your +mentor for uploading. If you have git push ability, look at +@ref{Pushing to staging}. + @node Advanced Git procedures @section Advanced Git procedures @@ -1086,7 +1106,9 @@ 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:: +* Pushing to staging:: @end menu @@ -1193,8 +1215,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 @@ -1353,10 +1375,26 @@ 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 - Most contributors are not able to commit patches directly to the main repository---only members of the LilyPond development team have @emph{commit access}. If you are a contributor and are @@ -1378,6 +1416,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 @@ -1401,15 +1442,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 @@ -1421,7 +1462,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 @@ -1436,14 +1477,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}. @@ -1464,7 +1505,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 @@ -1530,6 +1571,9 @@ Git properly in the previous step. @item Test your commit access with a dry run: +@warning{Do not push directly to master; instead, push to staging. +See @ref{Pushing to staging}.} + @example git push --dry-run --verbose @end example @@ -1545,9 +1589,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 @@ -1613,9 +1665,66 @@ 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 Pushing to staging +@subsection Pushing to staging + +Do not push directly to the git @code{master} branch. Instead, +push to @code{staging}. + +You will not see your patch on @code{origin/master} until some +automatic tests have been run. These tests are run every couple +of hours; please wait at least 12 hours before wondering if your +patch has been lost. Note that you can check the commits on +@code{origin/staging} by looking at the git web interface on +savannah. + +@subsubheading If your work is in a patch file + +Assuming that your patch is in a file called +@file{0001-my-patch.patch}, and you are currently on git master, +do: + +@example +git checkout staging +git pull -r +git am 0001-my-patch.patch +gitk +git push origin staging +git checkout master +@end example + +@warning{Do not skip the @command{gitk} step; a quick 5-second +check of the visual history can save a great deal of frustration +later on. You should only see that @command{staging} is only 1 +commit ahead of @code{origin/staging}.} + +@subsubheading If your work is in a branch + +If you are working on branches and your work in is +@code{my_branch_name}, then do: + +@example +git checkout staging +git pull -r +git merge my_branch_name +gitk +git push origin staging +@end example + +@warning{Do not skip the @command{gitk} step; a quick 5-second +check of the visual history can save a great deal of frustration +later on. You should see that @code{staging} is only ahead of +@code{origin/staging} by the commits from your branch.} + + + @node Git on Windows @section Git on Windows +@warning{We heavily recommend that development be done with our +virtual machine @ref{Lilydev}.} + @c Some of this may duplicate stuff in other sections @c But it is probably best for windows users to have it all together @c If necessary, clear this up later -td