CG: clarify staging branch policy

The big paragraph is suggested by David Kastrup in
http://lists.gnu.org/archive/html/lilypond-devel/2012-07/msg00472.html

diff --git a/Documentation/contributor/administration.itexi b/Documentation/contributor/administration.itexi
index 88c66bea775ba1c741463d11c79d42fb1bf98499..73c317855eb84dc09c65a0b8c96ffa25a79e319b 100644 (file)
--- a/Documentation/contributor/administration.itexi
+++ b/Documentation/contributor/administration.itexi
@@ -254,6 +254,9 @@ these complete error-free. If you have set Patchy up to use email,
 it emails its results to you.  If you haven't, then you can view
 them in a logfile.  It also merges @code{staging} into @code{master}.
 
+@warning{in case the build fails, do not try to push fixes on top of
+staging branch, for details see @ref{Pushing to staging}.}
+
 When you have run Patchy a few successful times with email sending,
 you are ready for running it as a cron job. First, make sure you have
 the following in @file{$HOME/.lilypond-patchy-config} to avoid

diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi
index 7ec9022f5994b55b4195bea2b18b691871dd324c..2567484e7075ab4627ad1ab8c51479d9a275ea4f 100644 (file)
--- a/Documentation/contributor/source-code.itexi
+++ b/Documentation/contributor/source-code.itexi
@@ -2044,6 +2044,15 @@ patch has been lost.  Note that you can check the commits on
 @code{origin/staging} by looking at the git web interface on
 savannah.
 
+It may happen occasionally that the staging branch breaks automated
+testing.  In this case the automatic move of staging material to
+master gets halted in order to avoid broken material entering master.
+This is a safety net.  Please do not try breaking out from it by
+adding fixes on top of staging: in that case the whole sequence will
+end up in master after all, defeating the purpose of the system.  The
+proper fix usually involves rewriting the staging branch and is best
+left to core developers after discussion on the developer list.
+
 @subsubheading If your work is in a patch file
 
 Assuming that your patch is in a file called