Doc: CG: add instructions for staging branch

diff --git a/Documentation/contributor/issues.itexi b/Documentation/contributor/issues.itexi
index b72831ed2e59de4650b4eecb0fb3deff9deff8ab..86976fd3242f450e6f3da96f91e78b2551f0702c 100644 (file)
--- 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.}
 
 @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:
 
 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.
 
 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
 @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
 @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
 
 @item
 If the patch is clearly in response to an existing issue, then


@@ -883,7 +894,7 @@ weeks.
 
 @end itemize
 
 
 @end itemize
 

-
+@end ignore

 
 
 @node Summary of project status
 
 
 @node Summary of project status

diff --git a/Documentation/contributor/quick-start.itexi b/Documentation/contributor/quick-start.itexi
index 9a23906da45c45a143db284949817d9cf4da2da4..d6d7e24d4f5c741612f4bef3e66e45cfb951c23e 100644 (file)
--- 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
 @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:
 
 @item
 Download the Ubuntu LilyPond Developer Remix disk image:


@@ -71,7 +71,7 @@ recognize what they are, then you don't want them:
 }
 
 @item
 }
 
 @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
 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
 (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
 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
 @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
 
 @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
 using gedit.
 
 @item

-Some contributors have recommended: (pdf available for free)
+Some contributors have recommended a free pdf:

 
 @example
 @uref{http://www.ubuntupocketguide.com/}
 
 @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
 
 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}.
 
 @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 27d8236b64e0850783b7b5df12098ffbe6b73a5f..de292c99f6d851cdbc763adf1819e006726e8bdc 100644 (file)
--- 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
 
 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}.
 
 @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}.
 
 
 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
 
 @node Starting with Git
 @section Starting with Git


@@ -125,10 +118,6 @@ multiple projects concurrently.
 @node Setting up
 @subsection Setting up
 
 @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}.}
 @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
 
 @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}
 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}).
 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.
 
 (@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
 
 
 @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
 
 @example

-mkdir ~/lilypond-git/; cd ~/lilypond-git/
-git init
+git clone git://git.sv.gnu.org/lilypond.git ~/lilypond-git

 @end example
 
 @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
 @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}.}
 
 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.
 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
 
 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
 @subsubheading Technical details
 
 Git stores the information entered with


@@ -1076,6 +1055,23 @@ running:
 git cl issue 0
 @end example
 
 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
 
 @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::
 * Sending and receiving patches via email::
 * Cleaning up multiple patches::
 * Commit access::

+* Pushing to staging::

 @end menu
 
 
 @end menu
 
 


@@ -1390,7 +1387,6 @@ remove those commits.}
 @node Commit access
 @subsection Commit access
 
 @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
 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:
 
 @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
 @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.
 
 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
 
 @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
 @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