CG: minor revisions to Patchy description

diff --git a/Documentation/contributor/administration.itexi b/Documentation/contributor/administration.itexi
index c724a4836bb20ae3a4c13f7976bae753e1f020ac..36886d19cb7acf89195b0850891024b6eb87bb67 100644 (file)
--- a/Documentation/contributor/administration.itexi
+++ b/Documentation/contributor/administration.itexi
@@ -128,22 +128,25 @@ Currently: Carl
 
 @subheading Introduction
 
-Patchy is a set of Python scripts written by Graham to automate
-two administrative tasks:
+Patchy is a set of Python scripts to automate two administrative
+tasks:
 
 @itemize
 @item
-checking that patches compile
+@code{lilypond-patchy-staging.py}: checks that new commits in
+@code{staging} can compile the regtests and documentation before
+merging @code{staging} into @code{master}.
+
+(completely automatic)
 
 @item
-trying to ensure that git master is not corrupted by non-compiling
-patches.
+@code{test-patches.py}: checks that patches apply to git master,
+compile, and lets a human check that there are no big unintended
+changes to the regtests.
 
-@end itemize
+(requires some human input)
 
-Checking that patches compile is the job of @code{test-patches.py},
-whilst @code{lilypond-patchy-staging.py} tests patches in staging
-before pushing them to master.
+@end itemize
 
 @subheading Installing patchy
 
@@ -151,16 +154,17 @@ To install patchy, you should run do the following:
 
 @enumerate
 @item
-Create a new user on your box - use this solely to run patchy.  It
-is recommended that this should not be an administrator. New
-users are created from System; Administration; Users and Groups.
+Create a new user on your box to to run patchy; this is a security
+step for your own protection.  It is recommended that this should
+not be an administrator.  New users are created from System;
+Administration; Users and Groups.
 
 @item
 Get the patchy scripts from
 @example
 https://github.com/gperciva/lilypond-extra/
 @end example
-Patchy is in the @code{patches} directory.
+Patchy is in the @file{patches/} directory.
 
 @item
 Put the scripts in a sensible place on your system
@@ -177,18 +181,22 @@ Make sure it's where you want it and name it lilypond-git
 @item
 Create an environment variable called LILYPOND_GIT and make it
 equal to the location of your new git repo.  You can do this by
-editing .profile and adding the line:
+editing @file{$HOME/.profile} and adding the line:
 @example
 export LILYPOND_GIT=~/lilypond-git
 @end example
-and logging out and in.
+then logging out and in.
+
+@item
+Run patchy once to set up config files.  Cancel this build
+(ctrl-c).
 
 @item
-Edit lilypond-patchy-config-DEFAULT to provide working directories
-for your build directory, your results directory, compiler options
-and notification method.  If you don't want to use email
-notification, then delete everything after @code{smtp_command:}.
-Save this as lilypond-patchy-config.
+Edit @file{$HOME/.lilypond-patchy-config} to provide working
+directories for your build directory, your results directory,
+compiler options and notification method.  If you don't want to
+use email notification, then delete everything after
+@code{smtp_command:}.
 
 @item
 Ensure that your new user has git push access.  Follow the
@@ -206,8 +214,10 @@ python lilypond-patchy-staging.py
 @end example
 Not much appears to happen except you can see a lot of CPU gets
 used if you open System Monitor. There's not much point running
-patch-merge unless there something in staging to be merged to
-master.
+@code{lilypond-patchy-staging.py} unless there something in
+staging to be merged to master, however, if there's nothing in
+staging then the script won't waste resources by compiling
+anything.
 
 The script fetches the current patches in staging and runs
 @code{make}, @code{make test} and @code{make doc} to ensure that all of
@@ -217,11 +227,15 @@ them in a logfile.  It also merges staging into master.
 
 @subheading test-patches.py
 test-patches prepares a regtest comparison for a human to quickly
-glance at, to determine if the patch is ready for a review.  If
-the patch passes test-patches, it should be reviewed by relevant
-developers, and if it passes this, it can be considered for
-countdown (see @ref{Commits and patches}) and pushing to staging
-(see @ref{Pushing to staging}).
+glance at, to determine if the patch is ready for a review.  After
+looking at the comparison (or the lack of a comparison in the case
+of problems), run @code{accept-patch.py} or
+@code{reject-patch.py}.
+
+Once a patch has gotten a "LGTM" from Patchy, it should be
+reviewed by relevant developers, and if it passes this, it can be
+considered for countdown (see @ref{Commits and patches}) and
+pushing to staging (see @ref{Pushing to staging}).
 
 
 @node Administrative mailing list