@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
on which part of their job, checks to make sure that everything is
running smoothly, and has final say on our policy for Issues.
-Currently: Phil
+Currently: Colin H
@item
Doc Meister: trains new doc editors/writers, organizes who works
@w{@code{-devel}} community into actually reviewing said patches, and
finally pushes the patches once they're accepted. This person is
@emph{not} responsible for training new programmers, because that
-would be far too much work -- he job is @qq{only} to guide
+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
@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
-To install patchy, you should run do the following:
+To install patchy, you should 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 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/
+@uref{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
(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 .profile and adding the line:
+Create environment variables @var{LILYPOND_GIT} and
+@var{LILYPOND_BUILD_DIR}, see @ref{Environment variables}.
+
+@item
+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
-export LILYPOND_GIT=~/lilypond-git
+cd PATH/TO/lilypond-extra.git/patches
+lilypond-patchy-staging.py
@end example
-and logging out and in.
+Following calls of @code{lilypond-patchy-staging.py} need not be made
+from the directory where it stands.
@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 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
@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
-patch-merge unless there something in staging to be merged to
-master.
+@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.
The script fetches the current patches in staging and runs
@code{make}, @code{make test} and @code{make doc} to ensure that all of
@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
@section Administrative mailing list
-An mailing list for administrative issues is maintained at
+A mailing list for administrative issues is maintained at
@code{lilypond-hackers@@gnu.org}.
This list is intended to be used for discussions that should be kept
@itemize
@item
-Clarify the various development tasks by writing down the polices
+Clarify the various development tasks by writing down the policies
and techniques and/or simplifying the tasks directly.
@item
code.
Having 1 more normal user answering emails on lilypond-user won't
-have a dramatic trick-up affect all by himself, of course. But if
+have a dramatic @q{trickle-up} effect all by itself, of course. But if
we had 8 users volunteering to answer emails, 6 users starting to
write documentation, and 2 users editing LSR... well, that would
free up a lot of current bug-fixing-capable contributors to focus
Although GOP is a short-term project, the main goal is to train
more people to handle ongoing jobs. The more people doing these
-jobs, the ligher the work will be, and the more we can get done
+jobs, the lighter the work will be, and the more we can get done
with lilypond!
Also, it would be nice if we had at least one "replacement" /
documentation. It would be great if somebody could create
properly-formatted patches for these corrections.
-Technical requirements: ability to run @ref{Lilydev}.
+Technical requirements: ability to run @ref{LilyDev}.
@item LSR editor:
LSR contains many useful examples of lilypond, but some snippets
often find them in Ponds of Lilies) and new feature implementors.
Technical requirements: development environment (such as
-@ref{Lilydev}), ability to read+write scheme and/or C++ code.
+@ref{LilyDev}), ability to read+write scheme and/or C++ code.
@end itemize
@item
anything which stops contributors from helping out (e.g.
lily-git.tcl not working, source tree(s) not being available,
-lilydev being unable to compile git master, inaccurate
+LilyDev being unable to compile git master, inaccurate
instructions in the Contributor's Guide 2 Quick start).
To limit this scope of this point, we will assume that the
-contributor is using the latest lilydev and has read the relevant
+contributor is using the latest LilyDev and has read the relevant
part(s) of the Contributor's Guide. Problems in other chapters of
the CG are not sufficient to qualify as Type-Critical.
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