-@c -*- coding: utf-8; mode: texinfo; -*-
@node Administrative policies
@chapter Administrative policies
@menu
* Meta-policy for this document::
+* Environment variables::
* Meisters::
-* Patchy::
+* Automated testing with Patchy::
* Administrative mailing list::
* Grand Organization Project (GOP)::
* Grand LilyPond Input Syntax Standardization (GLISS)::
@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
running smoothly, and has final say on our policy for
Documentation. Also includes LSR work.
-Currently: Graham
+Currently: None
@item
Translation Meister: trains new translators, updates the
Currently: Francisco
+@end itemize
+
+
+@node Automated testing with Patchy
+@section Automated testing with Patchy
+
+@menu
+* Overview of Patchy::
+* Patchy requirements::
+* Installing Patchy::
+* Configuring Patchy::
+* Running the scripts::
+* Automating Patchy::
+* Troubleshooting Patchy::
+@end menu
+
+@node Overview of Patchy
+@subsection Overview of Patchy
+
+Patchy is a set of Python scripts used for testing patches or testing &
+pushing new commits added to @code{remote/origin/staging} to
+@code{remote/origin/master}.
+
+No programmatic skill is required to run either of the scripts; although
+knowledge of compiling LilyPond and its documentation along with
+understanding how to configure the @var{PATH} environment of your
+computer is required. See @ref{Working with source code}.
+
+The two scripts that are used for each function are:
+
+@itemize
@item
-Frog Meister: is responsible for code patches from (relatively)
-inexperienced contributors. Keeps track of patches, does initial
-reviewing of those patches, sends them to @w{@code{-devel}} when
-they've had some initial review on the Frog list, pesters the
-@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 -- his/her job is @qq{only} to guide
-completed patches through our process.
+@code{test-patches.py}. This script tests issues labelled as
+@qq{Patch-New} on the LilyPond issue tracker. Part of the testing
+process involves running the regression tests, so this script always
+requires some human intervention in order to visually check for any
+differences that may be present after a successful test has occurred.
-Currently: Carl
+@item
+@code{lilypond-patchy-staging.py}. This script checks for any new
+commits in @code{remote/origin/staging}, makes sure that the new HEAD
+compiles along with all the LilyPond documentation. Then finally
+pushing to @code{remote/origin/master}. This script can be run and left
+unattended, requiring no human intervention.
@end itemize
-@node Patchy
-@section Patchy
+Both of the scripts can be run independently of each other and it is not
+necessary to be able to run both. So if you wanted to contribute to
+LilyPond development, for example by @emph{just} testing patches then
+this would still be a helpful contribution to LilyPond's development.
+
+Patchy can also be configured to send emails after each successful (or
+unsuccessful) operation. This is not a requirement and is turned off
+by default.
-@subheading Introduction
+@c Need to explain in more detail how to set up Patchy for email but
+@c as I don't use myself it I have no experience - JL
-Patchy is a set of Python scripts to automate two administrative
-tasks:
+
+@node Patchy requirements
+@subsection Patchy requirements
+
+@unnumberedsubsec Testing new patches
@itemize
+
+@item
+A full local copy of the source code. See
+@ref{Working with source code}.
+
+@item
+All the software needed for compiling LilyPond @emph{and} the
+documentation. Although being able to build the full set of LilyPond's
+manuals is not mandatory for testing (most) patches, part of the patch
+testing process requires that the regression tests are run and it is
+this that requires the software normally used for compiling
+documentation. See @ref{Compiling}.
+
@item
-@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}.
+Commit access is @emph{not} required to test patches, but a valid login
+to @uref{http://code.google.com/} @emph{is}.
+
+@end itemize
+
+
+@unnumberedsubsec Testing & pushing new commits
+
+@itemize
-(completely automatic)
+@item
+A full local copy of the source code. See
+@ref{Working with source code}.
@item
-@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.
+All the software needed for compiling LilyPond @emph{and} the
+documentation. Unlike testing patches, being able to build the full set
+of LilyPond's documentation is required to be able to test & push new
+commits. See @ref{Compiling}.
-(requires some human input)
+@item
+Commit access @emph{is} required to test and push new commits, but a
+valid login to @uref{http://code.google.com/} is @emph{not}. See
+@ref{Commit access}.
@end itemize
-@subheading Installing patchy
-To install patchy, you should do the following:
+@node Installing Patchy
+@subsection Installing Patchy
+
+The Patchy scripts are not part of the LilyPond code base, but can be
+downloaded from @uref{https://github.com/gperciva/lilypond-extra/}. The
+scripts and related Python libraries are all located in the
+@file{patches/} directory.
+
+Alternatively, use @code{git clone};
+
+@example
+git clone https://github.com/gperciva/lilypond-extra/
+@end example
+
+This makes it simpler to update the scripts if any changes are ever made
+to them. Finally, add the location of the @file{patches/} directory to
+your @var{PATH}.
+
+
+@node Configuring Patchy
+@subsection Configuring Patchy
+
+@warning{It is recommended to create a new user on your computer
+specifically to run the Patchy scripts as a security precaution and that
+this user should not have any administrative privileges. Also do not
+set password protection for your ssh key else you will not be able to
+run the scripts unattended.}
@enumerate
+
@item
-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.
+Make sure the environment variables @var{LILYPOND_GIT} and
+@var{LILYPOND_BUILD_DIR} are configured appropriately. See
+@ref{Environment variables}.
@item
-Get the patchy scripts from
+To save being prompted for your login and password to
+@uref{http://code.google.com/} when testing patches. create a
+@emph{plain-text} file in your Patchy user's @code{$HOME} directory
+called @code{.lilypond-project-hosting-login} containing your login and
+password, each on a separate line.
+
@example
-@uref{https://github.com/gperciva/lilypond-extra/}
+joe_smith123@@gmail.com
+mYp455w0rd!
@end example
-Patchy is in the @file{patches/} directory.
@item
-Put the scripts in a sensible place on your system
+Manually run either the @code{test-patches.py} or
+@code{lilypond-patchy-staging.py} scripts and when prompted:
+
+@smallexample
+Warning: using default config; please edit /home/joe/.lilypond-patchy-config
+Are you sure that you want to continue with the default config? (y/[n])
+@end smallexample
+
+Answer @qq{@code{n}} and press enter.
+
+The next time either of the scripts are run they will use the
+@code{.lilypond-patchy-config} settings copied to your @code{$HOME}
+directory.
+
+@item
+Manually edit the @file{.lilypond-patchy-config} file, located in your
+@code{$HOME} directory to change any of the default settings.
+
+@end enumerate
+
+These include:
+
+@itemize
@item
-Create a new git repository with
+All @code{make} operations are run with;
@example
-git clone git://git.sv.gnu.org/lilypond.git
+extra_make_options = -j3 CPU_COUNT=3
@end example
-This will create a directory called lilypond with the repo in it.
-Make sure it's where you want it and name it lilypond-git
-(assuming you want to follow the standard naming conventions).
+
+See @ref{Saving time with the -j option}
@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:
+A complete build of all the LilyPond documentation is @emph{not}
+performed;
@example
-export LILYPOND_GIT=~/lilypond-git
+patch_test_build_docs = no
@end example
-then logging out and in.
@item
-Run patchy once to set up config files. Cancel this build
-(ctrl-c).
+Each instance of either a patch test or commit test & push is logged in;
+@example
+auto_compile_results_dir = ~/lilypond-auto-compile-results/
+@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:}.
+Both scripts will perform their build operations in;
+@example
+build_dir = /tmp/lilypond-autobuild/
+@end example
+
+@end itemize
+
+Each completed patch test will also generate its own directory in
+@file{/tmp/...} labelled with the tracker issue number prefixed by
+@code{show-}.
+@example
+\tmp\show-3446
+@end example
+
+Both the scripts create clones of @code{staging} and @code{master}
+branches (prefixed with @code{test-}) with a third branch, called
+@code{test-master-lock} used as a check to protect against two or more
+instances of Patchy being run locally at the same time.
+
+
+@node Running the scripts
+@subsection Running the scripts
+
+@unnumberedsubsec Testing & pushing new commits
+
+@code{lilypond-patchy-staging.py} is run @emph{without} any arguments.
+It then checks to see if @code{remote/origin/staging} is
+@qq{further ahead} than @code{remote/origin/master}.
+
+@noindent
+If there are no new differences between the two branches since the last
+run check, the script will report something like this:
+
+@smallexample
+(UTC) Begin LilyPond compile, previous commit at 4726764cb591f622e7893407db0e7d42bcde90d9
+Success: No new commits in staging
+@end smallexample
+
+@noindent
+If there are any differences between the two branches since the last
+run check, (or if the script cannot for any reason, locate the last
+instance of a commit that it checked) it will report something like
+this:
+
+@smallexample
+(UTC) Begin LilyPond compile, previous commit at 4726764cb591f622e7893407db0e7d42bcde90d9
+Merged staging, now at: 79e98a773b6570cfa28a15775a9dea3d3e54d6b5
+ Success: ./autogen.sh --noconfigure
+ Success: /tmp/lilypond-autobuild/configure --disable-optimising
+...
+@end smallexample
+
+and proceed with running @code{make}, @code{make test} and a
+@code{make doc}. Unlike @code{test-patches.py} if all the tests pass,
+the script then pushes the changes to @code{remote/origin/master}.
+
+@smallexample
+...
+Success: nice make clean
+Success: nice make -j7 CPU_COUNT=7
+Success: nice make test -j7 CPU_COUNT=7
+Success: nice make doc -j7 CPU_COUNT=7
+To ssh://joe@@git.sv.gnu.org/srv/git/lilypond.git
+ 79e98a7..4726764 test-staging -> master
+ Success: pushed to master
+@end smallexample
+
+@warning{In the case where any of the @code{lilypond-patchy-staging.py}
+tests fail, do not try to push your own fixes but report the failures to
+the Developers List <lilypond-devel@@gnu.org> for advice.}
+
+
+@unnumberedsubsec Testing new patches
+
+When run without any argument, @code{test-patches.py} will check
+@uref{http://code.google.com/p/lilypond/issues/list} for all tracker
+issues that are marked with the label @code{Patch-new}. It then scrapes
+the issue, looking for the last Rietveld URL entered. It then downloads
+the patch file and applies it to @code{test-master}.
+
+Here is an example where two tracker issues labeled as @code{Patch-new}
+were detected:
+
+@smallexample
+...
+issues [4007, 4008]
+Trying issue 4007
+Found url: http://codereview.appspot.com/112210043
+Found patch: 4007,/home/joe/lilypond-git/issue112210043_1.diff,
+Trying issue 4008
+Found url: http://codereview.appspot.com/115770043
+Found patch: 4008,/home/joe/lilypond-git/issue115770043_1.diff,
+Fetching, cloning, compiling master.
+...
+@end smallexample
+
+If run no tracker items with the @var{Patch-New} label are found it will
+report:
+
+@example
+issues []
+@end example
+
+The script can also be run using the tracker issue number(s) as an
+argument regardless if the @var{Patch-New} label has been assigned;
+
+@example
+test-patches.py 4006
+@end example
+
+or
+
+@example
+test-patches.py 4006 3992 4020
+@end example
+
+The script then checks to see if any previously
+@code{make test-baseline}s have been generated and if the commit ID of
+@code{remote/origin/master} is different from that previously completed
+test.
+
+@noindent
+If no previous @code{make test-baseline} test is discovered or if the
+commit ID of @code{remote/origin/master} has changed, then a new
+@code{make test-baseline} will run first automatically before the patch
+is tested:
+
+This shows when the commit ID has changed:
+
+@smallexample
+...
+(UTC) Begin LilyPond compile, previous commit at 3f92dcb2c81dcd2755542b57a0a5f2039f29a211
+Merged master, now at: 4726764cb591f622e7893407db0e7d42bcde90d9
+ Success: ./autogen.sh --noconfigure
+ Success: /tmp/lilypond-autobuild/configure --disable-optimising
+ Success: nice make clean
+ Success: nice make -j3 CPU_COUNT=3
+ Success: nice make test-baseline -j3 CPU_COUNT=3
+ Success: nice make doc -j3 CPU_COUNT=3
+ Success: nice make doc-clean
+...
+@end smallexample
+
+@noindent
+If a previous regression test @emph{is} discovered @emph{and} if the
+commit ID of @code{remote/origin/master} has not changed, then the patch
+will be tested against the previous @code{make test-baseline} without
+the need to re-generate a new one:
+
+@smallexample
+...
+issues [4009]
+Trying issue 4009
+Found url: http://codereview.appspot.com/110540043
+Found patch: 4009,/home/joe/lilypond-extra/patches/issue110540043_1.diff,
+Fetching, cloning, compiling master.
+(UTC) Begin LilyPond compile, previous commit at 4726764cb591f622e7893407db0e7d42bcde90d9
+ Success: No new commits in master
+Using test baseline from previous build.
+...
+@end smallexample
+
+The patch is then applied and a @code{make} and @code{make check} are
+run. A full @code{make doc} is also run if the
+@file{.lilypond-patchy-config} file has been edited accordingly;
+
+@smallexample
+...
+Issue 4009:
+Issue 4009: Testing patch issue110540043_1.diff
+ Success: git apply --index /home/joe/lilypond-git/issue112210043_1.diff
+ Success: ./autogen.sh --noconfigure
+ Success: /tmp/lilypond-autobuild/configure --disable-optimising
+ Success: nice make clean
+ Success: nice make -j3 CPU_COUNT=3
+ Success: nice make check -j3 CPU_COUNT=3
+ Success: nice make doc -j3 CPU_COUNT=3
+...
+@end smallexample
+
+Once all the tests have run (successfully or not), the script will clean
+up from the previous patch and, if required, start testing the next
+issue;
+
+@smallexample
+...
+Issue 4007: Cleaning up
+ Success: nice make test-clean
+ Success: nice make doc-clean
+ Success: nice make clean
+ Success: git reset --hard
+Issue 4007: Done.
+Issue 4008:
+Issue 4008: Testing patch issue115770043_1_diff
+ Success: git apply --index /home/joe/lilypond-git/issue115770043_1.diff
+ Success: ./autogen.sh --noconfigure
+...
+@end smallexample
+
+and so on.
+
+@unnumberedsubsubsec Checking the regression test results
+
+Assuming the patch passed all the @code{make} tests, the regression
+differences will be located in the @file{/test-results/} directory
+within the build location for the patch issue number;
+
+@example
+/tmp/show-4007/test-results/
+@end example
+
+Open @file{index.html} in a browser of your choice to view any
+differences.
+
+@noindent
+Alternatively if the Firefox browser is installed, then the regression
+test results can be opened by calling the appropriate
+@file{show-regtests-} file located in the auto-compile log location;
+
+@example
+sh ~/lilypond-auto-compile-results/show-regtests-4007
+@end example
+
+See @ref{Regression tests}.
+
+@unnumberedsubsec Reporting test results
+
+Once a patch has been tested and the regression tests have been
+manually checked, the tracker can be updated manually by editing the
+tracker issue directly in the web browser or by using two additional
+python scripts that are included as part of the Patchy suite.
+
+@unnumberedsubsubsec For patches that have passed
+
+Use the @code{accept-patch.py} script and run it with the Google issue
+tracker number (not the Rietveld issue number) as an argument;
+
+@example
+accept-patch.py 4007
+@end example
+
+This will automatically update the tracker issue with the phrase
+@qq{Patchy the autobot says: passes tests.}.
+
+@noindent
+It is also possible to add additional information to the default
+message by adding a second argument within double-quote marks.
+
+@example
+accept-patch.py 4007 "This also includes a full documentation build."
+@end example
+
+The tracker issue's label is then changed automatically to
+@qq{Patch-review}.
+
+@unnumberedsubsubsec Patches that have failed
+
+Use the @code{reject-patch.py} script and run it with the Google issue
+tracker number (not the Rietveld issue number) as an argument but you
+@emph{must} also include a second argument, in double-quotes, stating
+the reason the patch has been rejected;
+
+@example
+reject-patch.py 4007 "Fails the 'make check' test."
+@end example
+
+Once the @code{reject-patch.py} script has been run, the tracker issue's
+label is changed automatically to @qq{Patch-Needs_work}.
+
+
+@node Automating Patchy
+@subsection Automating Patchy
+
+To run as a cron job make sure you have;
+
+@example
+[notification]
+notify_non_action = no
+@end example
+
+in @file{$HOME/.lilypond-patchy-config} to avoid any unintentional email
+flooding:
+
+Assuming that Patchy run a user @qq{patchy}, create a file called
+@file{$HOME/lilypond-patchy.cron}, adapting it as necessary (the
+@code{/2} means @qq{run this every 2 hours}):
+
+@smallexample
+02 0-23/2 * * * /home/patchy/lilypond-extra/patches/lilypond-patchy-staging.py
+@end smallexample
+
+@warning{@code{cron} will not inherit environment variables 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, apply the cron job (you may need superuser privileges for
+this):
+
+@example
+crontab -u patchy /home/patchy/lilypond-patchy.cron
+@end example
+
+
+@node Troubleshooting Patchy
+@subsection Troubleshooting Patchy
+
+The following is a list of the most common messages that the scripts
+may report with explanations.
+
+@itemize
@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
-to run patchy unattended.
+@example
+issues []
+@end example
-@end enumerate
+@itemize
+
+@item
+There are currently no tracker issues with the @code{Patch-New} status.
+
+@item
+If specific tracker issue number has been used as an argument when
+running @code{test-patches.py}, then the issue contains no URL to
+Rietveld.
+
+@end itemize
+
+@item
+@smallexample
+this Git revision has already been pushed by an operator other than this Patchy.
+@end smallexample
+
+@itemize
+
+@item
+Another, remote, machine has already tested and pushed the new commits
+in staging.
+
+@item
+You may also see this on your local machine if the auto-build files
+have been deleted and this computer has previously already pushed the
+listed commit ID to @code{master}.
+
+@end itemize
+
+
+
+@item
+@smallexample
+Git revision has not changed but checksum of test baseline has, must rebuild.
+@end smallexample
-@subheading lilypond-patchy-staging.py
+This occurs when Patchy detects that the commit ID has not changed
+since the last test but it cannot locate the last
+@code{make test-baseline} (usually because it has been deleted or moved)
+and so a new @code{test-baseline} is rebuilt.
-lilypond-patchy-staging.py is run with
+@item
@example
-python lilypond-patchy-staging.py
+Last patch for issue xxxx already tested or under testing
+by another Patchy instance, skipping.
@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
-@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
-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.
-
-@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{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}).
+
+@itemize
+
+@item
+There is another instance of Patchy running on your computer that is
+testing the same tracker issue.
+
+@item
+A previous test attempt was unsuccessful for some reason and the scripts
+were not able to tidy up after themselves (for example if you manually
+halt the testing process by killing it or closing the terminal you may
+have been running the script in).
+
+@noindent
+There is a hidden file located in the @code{$HOME} directory of the user
+running Patchy called @code{.lilypond-patchy-cache} that records the
+current patches that are being tested, have been tested and the commit
+ID of @code{remote/origin/master} since the last test. It will contain
+a line like this:
+
+@example
+[3995]
+issue105560044_120001_diff = testing
+@end example
+
+for any issue that it thinks is still in the process of being tested.
+
+@noindent
+Manually remove this entry and re-run the script.
+
+@end itemize
+
+@item
+@example
+test-master-lock and PID entry exist but previous Patchy
+run (PID xxxxx) died, resetting test-master-lock anyway.
+@end example
+
+@item
+A previous test attempt was unsuccessful for some reason and the scripts
+were not able to tidy up after themselves (for example if you manually
+halt the testing process by killing it or closing the terminal you may
+have been running the script in). The @code{test-master-lock} branch
+was therefore not able to be deleted cleanly however, nothing needs to
+be done the scripts will rebuild any tests it needs to.
+
+@item
+@example
+fatal: A branch named 'test-master-lock' already exists.
+@end example
+
+@itemize
+
+@item
+There is another instance of Patchy running on your computer that is
+testing the same tracker issue.
+
+@item
+A previous test attempt was unsuccessful for some reason and the scripts
+were not able to tidy up after themselves (for example if you manually
+halt the testing process by killing it or closing the terminal you may
+have been running the script in). The @code{test-master-lock} branch
+was therefore not able to be deleted cleanly, in this case you must
+manually delete the @code{test-master-lock} branch in your
+@code{$LILYPOND_GIT} directory.
+
+@example
+git branch -d test-master-lock
+@end example
+
+@noindent
+It may be wise to also manually delete @code{test-master} and
+@code{test-staging} too, just to be safe.
+
+@end itemize
+
+@item
+@example
+*** FAILED STEP ***
+ merge from staging
+ Another instance (PID xxxxx) is already running.
+@end example
+
+@noindent
+This occurs when trying to run @code{lilypond-patchy-staging.py} when
+another instance of either script is already running locally.
+
+@item
+@example
+Warning: something went wrong; omitting patch for issue 3976
+@end example
+
+@itemize
+
+@item
+The Rietveld URL as listed in the tracker is incorrect (e.g. missing or
+incorrect issue number
+
+@item
+The patch on Rietveld is too large to download
+
+@end itemize
+
+@end itemize
@node Administrative mailing list
code.
Having 1 more normal user answering emails on lilypond-user won't
-have a dramatic trick-up affect all by itself, 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
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
@uref{http://foundation.gnome.org/legal/} board members pledge
to keep certain matters confidential
-every security team of every linux distribution and OS
+every security team of every GNU/Linux distribution and OS
@end example
In fact, Karl Fogel's @qq{Producing Open Source Software}
@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
@item
other than that, everything is on the table. Is it a problem to
have the tagline inside \header? What should the default behavior
-of \include be? When we abolish \times, do we move to \tuplet 3:2
-or \tuplet 2/3 or what (for typical triplets in 4/4 time)?
+of \include be?
@item
we need to get standards for command names. This will help users
projects / lilypond.git / blobdiff