@menu
* Meta-policy for this document::
+* Environment variables::
* Meisters::
* Patchy::
* Administrative mailing list::
@end itemize
+@node Environment variables
+@section Environment variables
+
+Some maintenance scripts and instructions in this guide rely on
+the following environment variables. They should be predefined in
+LilyDev distribution (see @ref{LilyDev}); if you set up your own
+development environment, you can set them by appending these settings to
+your @file{~/.bashrc} (or whatever defines your default environment
+variables for the user account for LilyPond development), then logging
+out and in (adapt directories to your setup):
+
+@example
+LILYPOND_GIT=~/lilypond-git
+export LILYPOND_GIT
+LILYPOND_BUILD_DIR=~/lilypond-git/build
+export LILYPOND_BUILD_DIR
+@end example
+
+The standard build and install procedure (with @code{autogen.sh},
+@code{configure}, @code{make}, @code{make install}, @code{make doc}
+@dots{}) does not rely on them.
+
+In addition, for working on the website, @code{LILYPOND_WEB_MEDIA_GIT}
+should be set to the repository lilypond-extra, see
+@ref{lilypond-extra}.
+
@node Meisters
@section Meisters
would be far too much work -- his/her job is @qq{only} to guide
completed patches through our process.
-Currently: Carl
+Currently: Mike Solomon
@end itemize
(completely automatic)
@item
-@code{test-patches.py}: checks that patches apply to git master,
+@code{test-patches.py}: checks that patches apply to Git @code{master},
compile, and lets a human check that there are no big unintended
changes to the regtests.
@end itemize
-@subheading Installing patchy
+@subheading Installing Patchy
-To install patchy, you should do the following:
+To install Patchy, you should do the following:
@enumerate
@item
-Create a new user on your box to run patchy; this is a security
+Create a new user on your box 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
+Get the Patchy scripts from
@example
@uref{https://github.com/gperciva/lilypond-extra/}
@end example
Patchy is in the @file{patches/} directory.
@item
-Put the scripts in a sensible place on your system
+Put the scripts and Python libraries contained in @file{patches} in a
+sensible place on your system; this can be done by appending
+@file{patches/} full path to the @var{PATH} of the user that runs
+Patchy.
@item
Create a new git repository with
(assuming you want to follow the standard naming conventions).
@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 @file{$HOME/.profile} and adding the line:
-@example
-export LILYPOND_GIT=~/lilypond-git
-@end example
-then logging out and in.
+Create environment variables @var{LILYPOND_GIT} and
+@var{LILYPOND_BUILD_DIR}, see @ref{Environment variables}.
@item
-Run patchy once to set up config files. Cancel this build
-(ctrl-c).
+Run Patchy once to set up config files, answer @q{@code{n}} when it
+asks for going on, unless the default config file happens to suit your
+setup:
+@example
+lilypond-patchy-staging.py
+@end example
@item
-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:}.
+Edit @file{$HOME/.lilypond-patchy-config} to provide the location of
+your local lilypond Git repository, 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
instructions in the CG at @ref{Commit access}. Do not set
-password protection for the key - if you do you will not be able
+password protection for the key --- if you do you will not be able
to run patchy unattended.
@end enumerate
@subheading lilypond-patchy-staging.py
-lilypond-patchy-staging.py is run with
+@code{lilypond-patchy-staging.py} is run with
@example
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
+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
@code{lilypond-patchy-staging.py} unless there is 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.
+@code{staging} to be merged to @code{master}, however, if there's
+nothing new in @code{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
-these complete error-free. If you have set patchy up to use email,
+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 staging into master.
+them in a logfile. It also merges @code{staging} into @code{master}.
+
+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
+email flood:
+
+@example
+[notification]
+notify_non_action = no
+@end example
+
+Then, assuming Patchy run with user account @code{patchy}, write the
+following to @file{$HOME/lilypond-patchy.cron}, adapting it as
+necessary (the @code{/2} means @qq{run this every 2 hours}):
+@example
+02 0-23/2 * * * /home/patchy/git/lilypond-extra/patches/lilypond-patchy-staging.py
+@end example
+
+@warning{@code{cron} will not inherit environment variables from
+your main setup, so you must re-define any variables inside
+@file{$HOME/lilypond-patchy.cron}. For instance, @var{LILYPOND_GIT}
+may need to be defined if @var{git_repository_dir} is not correctly
+set in @file{$HOME/.lilypond-patchy-config}.}
+
+Finally, install the cron job (you may need superuser privileges for
+this):
+@example
+crontab -u patchy /home/patchy/lilypond-patchy.cron
+@end example
@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. After
-looking at the comparison (or the lack of a comparison in the case
-of problems), run @code{accept-patch.py} or
+@code{test-patches.py} prepares a regtest comparison for a human to
+quickly 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
is strictly additional to the log files.
@item
-Logfiles from calling lilypond (as part of lilypond-book) will go
-in the relevant @file{build/out/lybook-db/12/lily-123456.log}
-file. All other logfiles will go in the @file{build/logfiles/}
+Logfiles from calling lilypond (as part of lilypond-book) will go in
+the relevant
+@file{$LILYPOND_BUILD_DIR/out/lybook-db/12/lily-123456.log} file. All
+other logfiles will go in the @file{$LILYPOND_BUILD_DIR/logfiles/}
directory.
A single @code{make doc} will therefore result in hundreds of log
projects / lilypond.git / blobdiff