X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fadministration.itexi;h=90fe795a0cffa5b3617765afc330674f90225b64;hb=fcad9f183bb05f7206427bf5fc1b95fd8209d26e;hp=a9b32decab0bcbb220e902a0e8fc6f1fbe0e5622;hpb=549e872c56daec6ec4cf1b0a90fc6c8e58428417;p=lilypond.git diff --git a/Documentation/contributor/administration.itexi b/Documentation/contributor/administration.itexi index a9b32decab..90fe795a0c 100644 --- a/Documentation/contributor/administration.itexi +++ b/Documentation/contributor/administration.itexi @@ -7,6 +7,7 @@ don't fit anywhere else. @menu * Meta-policy for this document:: +* Environment variables:: * Meisters:: * Patchy:: * Administrative mailing list:: @@ -78,6 +79,32 @@ Totally disorganized; do whatever the mao you want: @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 @@ -91,7 +118,7 @@ Bug Meister: trains new Bug Squad volunteers, organizes who works 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 @@ -99,7 +126,7 @@ on which part of the job, checks to make sure that everything is 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 @@ -108,19 +135,6 @@ directions). Currently: Francisco -@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. - -Currently: Carl - @end itemize @node Patchy @@ -140,7 +154,7 @@ merging @code{staging} into @code{master}. (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. @@ -148,26 +162,29 @@ 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 @@ -179,57 +196,88 @@ Make sure it's where you want it and name it lilypond-git (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}. + +@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 +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 @@ -394,7 +442,7 @@ We often receive reports of typos and minor text updates to the 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 @@ -411,7 +459,7 @@ chapters 1 and 2 (or be willing to read the docs to find out). 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 @@ -874,7 +922,7 @@ open-source software. For example, @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} @@ -958,11 +1006,11 @@ area}, reason to move this to a different type. @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. @@ -1063,9 +1111,10 @@ all output will still be written to log files; the console output 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 @@ -1205,8 +1254,7 @@ convert-ly updates. @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