From: Graham Percival Date: Fri, 2 Dec 2011 11:00:20 +0000 (-0800) Subject: Doc: CG: add instructions for staging branch X-Git-Tag: release/2.15.22-1~20^2~1 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=b963dc41847ab077d0bf32e74d2e168ea2a84883;p=lilypond.git Doc: CG: add instructions for staging branch --- diff --git a/Documentation/contributor/issues.itexi b/Documentation/contributor/issues.itexi index b72831ed2e..86976fd324 100644 --- a/Documentation/contributor/issues.itexi +++ b/Documentation/contributor/issues.itexi @@ -769,6 +769,15 @@ email should contain a link to the issue you just added. @warning{This is not a Bug Squad responsibility; we have a separate person handling this task.} +For contributors/developers: follow the steps in +@ref{Commits and patches}, and @ref{Pushing to staging}. + +For people doing maintenance tasks: git-cl is adding issues, James +is testing them, Colin is selecting them for countdowns, and +Patchy is merging from staging to master. In the coming weeks, +these tasks will be more and more automated. + +@ignore There is a single Patch Meister, and a number of Patch Helpers (rename this?). The list of known patches awaiting review is: @@ -794,6 +803,7 @@ new issue with the @code{Patch-new} label and a link to the patch Issue numbers are cheap; losing developers because they got fed up with us losing their hard work is expensive. +@end ignore @c if we enter patches immediately, I don't think this is relevant. @ignore @item @@ -806,6 +816,7 @@ message) on the webgit page: @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git} @end example @end ignore +@ignore @item If the patch is clearly in response to an existing issue, then @@ -883,7 +894,7 @@ weeks. @end itemize - +@end ignore @node Summary of project status diff --git a/Documentation/contributor/quick-start.itexi b/Documentation/contributor/quick-start.itexi index 9a23906da4..d6d7e24d4f 100644 --- a/Documentation/contributor/quick-start.itexi +++ b/Documentation/contributor/quick-start.itexi @@ -52,7 +52,7 @@ Any virtualization tool can be used, but we recommend VirtualBox: @end example In virtualization terminology, your main operating system is the -@qq{host}, while lilydev is the @qq{guest}. +@strong{host}, while lilydev is the @strong{guest}. @item Download the Ubuntu LilyPond Developer Remix disk image: @@ -71,7 +71,7 @@ recognize what they are, then you don't want them: } @item -Create a music new @qq{virtual machine} inside your virtualization +Create a new @qq{virtual machine} inside your virtualization software. If possible, use at least 700 MB of RAM (1GB would be better) for @@ -80,7 +80,7 @@ for the virtual hard drive. A complete compile of everything (code, docs, regression tests) can reach 10 GB. @item -Install @file{ubuntu-lilydev-remix-1.1.iso} as the @qq{guest} +Install @file{ubuntu-lilydev-remix-1.1.iso} as the @strong{guest} operating system on your virtualized system. @enumerate @@ -96,7 +96,8 @@ install @item At the @qq{Prepare disk space} stage, do not be afraid to select @qq{Erase and use the entire disk}, since this refers to your -@emph{virtual disk}, not your machine's actual hard drive. +@strong{@emph{virtual disk}}, not your machine's actual hard +drive. @item When prompted to remove the installation CD, go to @@ -223,7 +224,7 @@ Right-click allows you to edit a file with gedit. We recommend using gedit. @item -Some contributors have recommended: (pdf available for free) +Some contributors have recommended a free pdf: @example @uref{http://www.ubuntupocketguide.com/} @@ -263,7 +264,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 121Mb). 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}. diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi index 27d8236b64..de292c99f6 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 @@ -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,7 +172,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,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 @@ -1076,6 +1055,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 @@ -1104,6 +1100,7 @@ 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 @@ -1390,7 +1387,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 @@ -1567,6 +1563,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 @@ -1658,9 +1657,54 @@ 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 +git push origin staging +git checkout master +@end example + +@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 +git push origin staging +@end example + + + @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