X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fsource-code.itexi;h=75363f4d40be7d54eb615b0c66f1fd2e837d8d14;hb=25e22b5ae7e6c1c5a8ffa82fd8217909ef3fa124;hp=bac6bed2d6a3f50405d5059caa86b92801b4b9d7;hpb=3ef893f1fe182e9f6cf5841cbff0706789bd3361;p=lilypond.git diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi index bac6bed2d6..75363f4d40 100644 --- a/Documentation/contributor/source-code.itexi +++ b/Documentation/contributor/source-code.itexi @@ -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 @@ -118,6 +111,7 @@ multiple projects concurrently. @menu * Setting up:: +* Git for the impatient:: * Downloading remote branches:: @end menu @@ -125,10 +119,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 +133,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 +144,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,7 +173,7 @@ 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. @@ -224,8 +207,18 @@ 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 +Finally, and in some ways most importantly, let's make sure that +we know what branch we're on. If you're not using lilydev, add +this to your @file{~/.bashrc}: + +@verbatim +export PS1="\u@\h \w\$(__git_ps1)$ " +@end verbatim + +If you are not using lilydev, you may need to install the +additional @code{git-completion} package, but it is definitely +worth it. + @subsubheading Technical details @@ -266,6 +259,269 @@ setting any now. Specific recommendations will be mentioned later in this manual. +@node Git for the impatient +@subsection Git for the impatient + +@advanced{The intent of this subsection is to get you working on lilypond as +soon as possible. If you want to learn about git, go read +@ref{Other Git documentation}. +@* +Also, these instructions are designed to eliminate the most common +problems we have found in using git. If you already know git and +have a different way of working, great! Feel free to ignore the +advice in this subsection.} + + +Ok, so you've been using @command{lily-git.tcl} for a while, but +it's time to take the next step. Since our review process delays +patches by 60-120 hours, and you want to be able to work on other +stuff while your previous work is getting reviewed, you're going +to use @strong{branches}. + +You can think of a branch as being a separate copy of the source +code. But don't worry about it. + +@subsubheading Start work: make a new branch + +Let's pretend you want to add a section to the Contributor's Guide +about using branches. + +Start by updating the repository, then making a new branch. Call +the branch anything you want as long as the name starts with +@code{dev/}. Branch names that don't begin with @code{dev/} are +reserved for special things in lilypond. + +@example +git checkout master +git pull -r origin master +git branch dev/cg +@end example + +@subsubheading Switch to that branch + +Nothing has happened to the files yet. Let's change into the new +branch. You can think of this as @qq{loading a file}, although in +this case it's really @qq{loading a directory and subdirectories +full of files}. + +@example +git checkout dev/cg +@end example + +Your prompt now shows you that you're on the other branch: + +@example +gperciva@@lilydev:~/lilypond-git (dev/cg)$ +@end example + +To be able to manage multiple lilypond issues at once, you'll need to switch +branches. You should have each lilypond issue on a separate branch. +Switching branches is easy: + +@example +git checkout master +git checkout origin/staging +git checkout origin/release/unstable +git checkout dev/cg +@end example + +Branches that begin with @code{origin/} are part of the remote repository, +rather than your local repository, so when you check them out you get a +temporary local branch. You should never make changes directly on a +branch beginning with @code{origin/}. You get changes into the remote +repository by making them in local branches, and then pushing them to +@code{origin/staging} as described below. + +@subsubheading Make your changes + +Edit files, then commit them. + +@example +git commit -a +@end example + + +Remember how I said that switching to a branch was like +@qq{loading a directory}? Well, you've just @qq{saved a +directory}, so that you can @qq{load} it later. + +@advanced{If you have used @command{cvs} or @command{svn}, you may +be very confused: those programs use @qq{commit} to mean +@qq{upload my changes to the shared source repository}. +Unfortunately, just to be different, @w{@command{git commit}} +means @qq{save my changes to the files}.} + +When you create a new file, you need to add it to git, then commit it: + +@example +git add input/regression/avoid-crash-on-condition.ly +git commit -a +@end example + + +Edit more files. Commit them again. Edit yet more files, commit +them again. Go eat dinner. Switch to @code{master} so you can +play with the latest changes from other developers. Switch back +to your branch and edit some more. Commit those changes. + +At this stage, don't worry about how many commits you have. + + +@subsubheading Save commits to external files + +Branches are nerve-wracking until you get used to them. You can +save your hard work as individual @file{.patch} files. Be sure to +commit your chages first. + +@example +git commit -a +git format-patch master +@end example + +I personally have between 4 and 20 of those files saved in a +special folder at any point in time. Git experts might laugh as +that behavior, but I feel a @emph{lot} better knowing that I've +got those backups. + + +@subsubheading Prepare your branch for review + +After committing, you can update your branch with the latest master: + +@example +git commit -a +git checkout master +git pull -r origin master +git checkout dev/cg +git rebase master +@end example + + +Due to the speed of lilypond development, sometimes +@code{master} has changed so much that your branch can no +longer be applied to it. In that happens, you will have a merge +conflict. Stop for a moment to either cry or have a stiff drink, +then proceed to @ref{Merge conflicts}. + + +@subsubheading Upload your branch + +Finally, you're finished your changes. Time to upload for review. +Make sure that you're on your branch, then upload: + +@example +git checkout dev/cg +git-cl upload master +@end example + + +@subsubheading Wait for reviews + +While you're waiting for a countdown and reviews, go back to +master, make a @code{dev/doc-beams} branch, and start adding doc +suggestions from issue 12345 from the tracker. Or make a +@code{dev/page-breaks} and fix bug in page breaking. Or whatever. +Don't worry, your @code{dev/cg} is safe. + + +@subsubheading Combining commits (optional unless you have broken commits) + +Does the history of your branch look good? + +@example +gitk +@end example + +If you have a lot of commits on your branch, you might want to +combine some of them. Alternately, you may like your commits, but +want to edit the commit messages. + +@example +git rebase -i master +@end example + +Follow instructions on the screen. + +@warning{This step gives you the power to completely lose your +work. Make a backup of your commits by saving them to +@file{.patch} files before playing with this. If you do lose +your work, don't despair. You can get it back by using @code{git reflog}. +The use of @code{git reflog} is not covered here.} + +@warning{If any of the commits on your branch represent partial work that will +not pass @var{make && make doc}, you @strong{must} squash these +commits into a working commit. Otherwise, your push will break staging +and will not be able to be merged to master. In general, you will +be safer to have one commit per push.} + + +@subsubheading Push to staging + +When you've got the coveted @code{Patch-push} status, time to +prepare your upload: + +@example +git fetch +git rebase origin/staging dev/cg~0 +gitk HEAD +@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 a set of your commits that are ahead of +@code{origin/staging}, with no label for the top commit -- only a +SHA1 id.} + +@warning{If @code{origin/staging} and @code{origin/master} are the +same commit, your branch (@code{dev/cg} in the example) will also +be at the top of the @code{gitk} tree. This is normal.} + +If everything looks good, push it: + +@example +git push origin HEAD:staging +@end example + +Then change back to your working branch: + +@example +git checkout dev/cg +@end example + +@warning{It is a best practice to avoid rebasing any of your branches +to @code{origin/staging}. If @code{origin/staging} is broken, it +will be deleted and rebuilt. If you have rebased one of your branches +to @code{origin/staging}, the broken commits can end up in your branch. +The commands given above do the rebase on a temporary branch, and avoid +changing your working branch.} + + +@subsubheading Delete your branch (safe) + +After a few hours, if there's nothing wrong with your branch, it +should be automatically moved to @code{origin/master}. Update, +then try removing your branch: + +@example +git checkout master +git pull -r origin master +git branch -d dev/cg +@end example + +The last command will fail if the contents of @code{dev/cg} are +not present in @code{origin/master}. + + +@subsubheading Delete your branch (UNSAFE) + +@c don't give explicit commands here -- this is too dangerous to copy and paste +Sometimes everything goes wrong. If you want to remove a branch even though +it will cause your work to be lost (that is, if the contents of @code{dev/cg} +are @strong{not} present in master), follow the instructions in @qq{Delete +your branch (safe)}, but replace the @code{-d} on the final line with +a @code{-D}. + + @node Downloading remote branches @subsection Downloading remote branches @@ -934,10 +1190,18 @@ 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 @@ -947,9 +1211,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 @@ -990,6 +1257,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) @@ -1024,9 +1298,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 @@ -1066,6 +1340,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 @@ -1085,6 +1376,7 @@ several Git branches of LilyPond source code is presented. @menu +* Merge conflicts:: * Advanced Git concepts:: * Resolving conflicts:: * Reverting all local changes:: @@ -1094,9 +1386,17 @@ several Git branches of LilyPond source code is presented. * Sending and receiving patches via email:: * Cleaning up multiple patches:: * Commit access:: +* Pushing to staging:: @end menu +@node Merge conflicts +@subsection Merge conflicts + +To be filled in later, and/or moved to a different section. I +just wanted to make sure that I had a stub ready somewhere. + + @node Advanced Git concepts @subsection Advanced Git concepts @@ -1380,7 +1680,6 @@ 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 @@ -1557,6 +1856,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 @@ -1648,9 +1950,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 @@ -2027,5 +2386,10 @@ More in-depth tutorials: @uref{http://git-scm.com/documentation} @item Book about git: @uref{http://progit.org/,Pro Git} + +@item +Github help: @uref{http://help.github.com/} +(very highly recommended by Graham) + @end itemize