X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fadministration.itexi;h=50f97ade9e6ef4370912c18025436f5a0ad87906;hb=c30d5621ede95d57d2259b006649d031fa4a0923;hp=415a30feb88dea10397013d48b3bc121c4422bdc;hpb=8c0b8e9a289159b37b67dfaf1075499a47785b78;p=lilypond.git diff --git a/Documentation/contributor/administration.itexi b/Documentation/contributor/administration.itexi index 415a30feb8..50f97ade9e 100644 --- a/Documentation/contributor/administration.itexi +++ b/Documentation/contributor/administration.itexi @@ -1,4 +1,3 @@ -@c -*- coding: utf-8; mode: texinfo; -*- @node Administrative policies @chapter Administrative policies @@ -7,7 +6,9 @@ don't fit anywhere else. @menu * Meta-policy for this document:: +* Environment variables:: * Meisters:: +* Automated testing with Patchy:: * Administrative mailing list:: * Grand Organization Project (GOP):: * Grand LilyPond Input Syntax Standardization (GLISS):: @@ -20,7 +21,7 @@ don't fit anywhere else. The Contributor's Guide as a whole is still a work in progress, but some chapters are much more complete than others. Chapters which are @qq{almost finished} should not have major changes -without a discussion on @code{-devel}; in other chapters, a +without a discussion on @w{@code{-devel}}; in other chapters, a disorganized @qq{wiki-style dump} of information is encouraged. Do not change (other than spelling mistakes) without discussion: @@ -77,55 +78,747 @@ 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 -We have four jobs for organizing a team of contributors: +We have four jobs for organizing a team of contributors: + +@itemize + +@item +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: Colin H + +@item +Doc Meister: trains new doc editors/writers, organizes who works +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: None + +@item +Translation Meister: trains new translators, updates the +translation priority list, and handles merging branches (in both +directions). + +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 +@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. + +@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 + +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. + +@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 + + +@node Patchy requirements +@subsection Patchy requirements + +@subsubsubheading 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 +Commit access is @emph{not} required to test patches, but a valid login +to @uref{http://code.google.com/} @emph{is}. + +@noindent +Note that a google account does not need to be a Gmail account; you can +use @emph{any} email address for your google account when you sign up. + +@warning{In order for @code{patchy} to work as expected, your Google +Account Settings must have the @q{Access for less secure apps} set to +@q{Allowed}. This is normally the default setting.} + +@end itemize + + +@subsubsubheading Testing & pushing new commits + +@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. 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}. + +@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 + + +@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 +Make sure the environment variables @var{LILYPOND_GIT} and +@var{LILYPOND_BUILD_DIR} are configured appropriately. See +@ref{Environment variables}. + +@item +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 +joe_smith123@@gmail.com +mYp455w0rd! +@end example + +@item +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 +All @code{make} operations are run with; +@example +extra_make_options = -j3 CPU_COUNT=3 +@end example + +See @ref{Saving time with the -j option} + +@item +A complete build of all the LilyPond documentation is @emph{not} +performed; +@example +patch_test_build_docs = no +@end example + +@item +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 +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 + +@subsubsubheading 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 for advice.} + + +@subsubsubheading 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. + +@subsubsubheading 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}. + +@subsubsubheading 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 +@example +issues [] +@end example + +@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 + +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. + +@item +@example +Last patch for issue xxxx already tested or under testing +by another Patchy instance, skipping. +@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). + +@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 -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. +There is another instance of Patchy running on your computer that is +testing the same tracker issue. -Currently: Phil +@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 -Doc Meister: trains new doc editors/writers, organizes who works -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. +@example +*** FAILED STEP *** + merge from staging + Another instance (PID xxxxx) is already running. +@end example -Currently: Graham +@noindent +This occurs when trying to run @code{lilypond-patchy-staging.py} when +another instance of either script is already running locally. @item -Translation Meister: trains new translators, updates the -translation priority list, and handles merging branches (in both -directions). +@example +Warning: something went wrong; omitting patch for issue 3976 +@end example -Currently: Francisco +@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 @code{-devel} when -they've had some initial review on the Frog list, pesters the -@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 -completed patches through our process. +The Rietveld URL as listed in the tracker is incorrect (e.g. missing or +incorrect issue number -Currently: Carl +@item +The patch on Rietveld is too large to download + +@end itemize @end itemize + @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 @@ -149,7 +842,7 @@ GOP has two goals: @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 @@ -215,7 +908,7 @@ work on the really hard stuff... like rewriting the grace note 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 @@ -228,7 +921,7 @@ many new helpers will provide a great moral boost! 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" / @@ -278,7 +971,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 @@ -295,7 +988,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 @@ -360,48 +1053,6 @@ away. This is not good. (prep: 2 hours. discuss: 10 hours) -@item @strong{Future release policy}: -(how) should we change any policies pertaining to releases? Should -an undocumented new feature count as release-blocking? - -(prep: 1 hour. discuss: 15 hours) - -@item @strong{lilypond-hackers mailing list}: -Should we have a private mailing list for senior developers? If -so, who should be on it? - -(prep: 2 hours+3 weeks. discuss: 10 hours) - -@item @strong{Hackers B}: - - -@item @strong{Git repository(s)}: -We currently have a web/ branch in our main repo; this seems -misleading to new developers. More generally, should we have -branches that aren't related to the master? i.e. should we -restrict a git branch to code which is an actual "branch" of -development? Also, some of our code (notably the windows and osx -lilypad) isn't in a git repository at all. -We can add new repositories very easily; should make repositories -like -@example -git://git.sv.gnu.org/lilypond/gub.git -git://git.sv.gnu.org/lilypond/lilypad.git -git://git.sv.gnu.org/lilypond/misc.git -@end example -? More information here: -@uref{http://code.google.com/p/lilypond/issues/detail?id=980} - -(prep: 2 hours. discuss: 10 hours) - -@item @strong{Roadmap of future development}: -Many projects have a roadmap of planned (or desired) future work. -Should we use one? If so, what should go on it, bearing in mind -our volunteer status? Is there any way of having a roadmap that -isn't vaporware? - -(prep: 1 hour. discuss: 5 hours) - @item @strong{Official links to other organizations?}: There's something called the "software freedom conservancy", and in general, there's a bunch of "umbrella organizations". Joining @@ -411,14 +1062,6 @@ schools, etc. (prep: 2 hours. discuss: 5 hours) -@item @strong{Mailing lists}: -We currently have a mix of official GNU mailing lists and lilynet -lists. Is there a strong rationale for having separate mailing -list servers? Why not pick one place, and put all our lists there? -(or at least, all "permanent" lists?) - -(prep: 1 hour. discuss: 5 hours) - @item @strong{Issue tracking with google code}: We use the google issue tracker, but this means that we are relying on a commercial entity for a large part of our @@ -435,23 +1078,6 @@ lilypond. Should we switch to something like gerritt? (prep: 5 hours. discuss: 15 hours) -@item @strong{Subdomains of *.lilypond.org}: -Unless Jan has a really weird DNS hosting setup, there are no -technical barriers to having names like lsr.lilypond.org, -frog.lilypond.org, or news.lilypond.org. Is this something that we -want to do? - -(prep: 1 hours+2 weeks. discuss: 5 hours) - -@item @strong{Authorship in source files}: -Our documentation currently does not attempt to track individual -authors of each file, while our source code makes a confused and -jumbled attempt to track this. A number of guidelines for F/OSS -projects explicitly recommends _not_ tracking this in individual -files, since the code repository will track that for you. - -(prep: 2 hours. discuss: 15 hours) - @item @strong{Clarity for sponsorships}: We currently do not advertize bounties and sponsorships on the webpage. How much advertising do we want, and what type? @@ -459,27 +1085,6 @@ Should we change the "structure" / "framework" for bounties? (prep: 2 hours. discuss: 10 hours) -@item @strong{Separate branches for active development}: -it might be good to have @emph{everybody} working on separate -branches. This complicates the git setup, but with sufficient -logic in lily-git.tcl, we can probably make it transparent to -newbies. However, we'd need a reliable person to handle all the -required merging and stuff. - -(prep: 2 hours. discuss: 10 hours) - -@item @strong{When do we add regtests?}: -There is a discrepancy between our stated policy on adding -regtests, and our actual practice in handling bugs and patches. -Clarify. - -There is also a wider question how to organize the regtests, such -as where to put interesting-console-output regtests, including -stuff like lilypond-book and midi2ly in a sensible manner, and -possibly including regtests for currently-broken functionality. - -(prep: 2 hours. discuss: 5 hours) - @item @strong{code readability}: "Our aim when producing source code for Lilypond in whatever language is that it should be totally comprehensible to a @@ -528,7 +1133,23 @@ can probably wrap it up with some other code-related questions. @node Policy decisions (finished) @subsection Policy decisions (finished) -@subheading GOP-PROP 1: python formatting +Here is a record the final decisions, along with links to the +discussions. + +@menu +* GOP-PROP 1 - python formatting:: +* GOP-PROP 2 - mentors and frogs:: +* GOP-PROP 3 - C++ formatting:: +* GOP-PROP 4 - lessons from 2.14:: +* GOP-PROP 5 - build system output (not accepted):: +* GOP-PROP 6 - private mailing lists:: +* GOP-PROP 7 - developers as resources:: +* GOP-PROP 8 - issue priorities:: +* GOP-PROP 9 - behavior of make doc:: +@end menu + +@node GOP-PROP 1 - python formatting +@subsubsection GOP-PROP 1 - python formatting We will follow the indentation described in PEP-8. @uref{http://www.python.org/dev/peps/pep-0008/} @@ -553,8 +1174,18 @@ There should be absolutely no tab characters for indentation in any @code{.py} file in lilypond git. All such files should be converted to use spaces only. +@subsubheading Discussions -@subheading GOP-PROP 2: mentors and frogs +@smallexample +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00060.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00084.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00310.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00574.html} +@end smallexample + + +@node GOP-PROP 2 - mentors and frogs +@subsubsection GOP-PROP 2 - mentors and frogs Nothing much was decided. The list of responsibilities was slightly altered; see the new one in @ref{Mentors}. We should @@ -567,6 +1198,546 @@ contributor-mentor pairs in: That's pretty much it. +@subsubheading Discussions + +@smallexample +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00311.html} +@uref{} +@uref{} +@end smallexample + + +@node GOP-PROP 3 - C++ formatting +@subsubsection GOP-PROP 3 - C++ formatting + +Speaking academically, C++ code style is a "solved problem". Let's +pick one of the existing solutions, and let a computer deal with +this. Humans should not waste their time, energy, and creativity +manually adding tabs or spaces to source code. + +We have modified @code{fixcc.py} to use astyle, along with extra +regex tweaks. + +@itemize +@item +the final script will be run @strong{blindly} on the lilypond +source code. We will accept whatever formatting the final version +of this script produces, with no manual tweaking. + +@item +patches which have been run through this tool will not be rejected +for style reasons. Any code formatting @qq{desires} which are not +enforced by @code{fixcc.py} will not be considered grounds for +rejecting a patch. + +@item +for now, this style will not be enforced. It is not cause for +concern if patches which do not follow the formatting done by +@code{fixcc.py} are pushed. From time to time, Graham will run +the formatter on the entire code base, and commit the resulting +changes. + +In a few months, we will tighten up this policy item (with some +sort of automatic processing), but that is outside the scope of +this policy item and is a matter for later discussion. + +@item +after the proposal is accepted, we will leave some time for +existing patches to be accepted and pushed. The script was +run on the source code on @strong{2011 August 01}. + +@end itemize + +@subheading GNU code + +LilyPond is a GNU project, so it makes sense to follow the GNU +coding standards. These standards state: + +@quotation +We don’t think of these recommendations as requirements, because +it causes no problems for users if two different programs have +different formatting styles. + +But whatever style you use, please use it consistently, since a +mixture of styles within one program tends to look ugly. If you +are contributing changes to an existing program, please follow the +style of that program. +@end quotation + +(@uref{http://www.gnu.org/prep/standards/html_node/Formatting.html}) + +With that in mind, we do not think that we must blindly follow the +formatting given by the currrent version of Emacs. + +@subheading Implementation notes + +We can avoid some of the style change pollution in git history by +ignoring whitespaces changes: + +@example +git diff -w +@end example + +@subsubheading Discussions + +@smallexample +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00526.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00796.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00200.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00525.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00751.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00751.html} +@end smallexample + + +@node GOP-PROP 4 - lessons from 2.14 +@subsubsection GOP-PROP 4 - lessons from 2.14 + +@subheading History + +A brief history of releases: + +@multitable @columnfractions .2 .2 .3 +@headitem date (YYYY-MM-DD) @tab version @tab comment +@item 2008-10-28 @tab 2.11.63 @tab nobody checking regtests +@item 2008-11-17 @tab 2.11.64 +@item 2008-11-29 @tab 2.11.65 +@item 2008-12-23 @tab 2.12.0 +@item 2009-01-01 @tab @tab somewhere around here, Graham becomes +officially release manager, but Han-Wen still builds the actual +releases +@item 2009-01-01 @tab 2.12.1 +@item 2009-01-25 @tab 2.12.2 +@item 2009-02-28 @tab 2.13.0 +@item 2009-06-01 @tab 2.13.1 @tab note jump in time! +@item 2009-06-27 @tab 2.13.2 @tab first Graham release? +@item 2009-07-03 @tab 2.13.3 +@item 2009-09-09 @tab @tab Graham arrives in Glasgow, gets a +powerful desktop computer, and begins serious work on GUB (sending +bug reports to Jan). It takes approximately 100 hours until GUB +is stable enough to make regular releases. +@item 2009-09-24 @tab 2.13.4 +@item 2009-10-02 @tab 2.13.5 +@item 2009-10-22 @tab 2.13.6 +@item 2009-11-05 @tab 2.13.7 +@item ... +@item 2010-01-13 @tab 2.12.3 +@item ... +@item 2010-03-19 @tab 2.13.16 @tab Bug squad starts doing a few +regtest comparisons, but IIRC the effort dies out after a few +weeks (BLUE) +@item ... +@item 2010-08-04 @tab 2.13.29 @tab Phil starts checking regtests (BLUE) +@item ... +@item 2011-01-12 @tab 2.13.46 @tab release candidate 1 (GREEN) +@item ... +@item 2011-05-30 @tab 2.13.63 @tab release candidate 7 (GREEN) +@item 2011-06-06 @tab 2.14.0 +@end multitable + +@c A graphical display of bugs: +@c +@c @image{bugs-2.13-visualization,png} +@c @image{zoom-2.13-visualization,png} + +@subheading Carl's analysis of the bugs + +A @file{csv} spreadsheet is available. + +@smallexample +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00852.html} +@end smallexample + +@example +@uref{lilypond-issues-analysis.csv} +@uref{lilypond-issues-analysis-trim-duplicates.csv} +@end example + +There 148 issues marked with Priority=Critical in the tracker. + +I've done an analysis, and it looks to me like there was initially +a backlog of critical issues that weren't fixed, and little work +was being done to eliminate critical issues. + +Somewhere about 2010-08-01, critical issues started to disappear, +but occasional new ones appeared. + +There were a couple of major changes that introduced unanticipated +regressions (new spacing code, beam collision avoidance). These +produced more than the expected number of regressions. + +It appears to me that we didn't really get serious about +eliminating critical bugs until about 2010-06-15 or so. After +that point, the number of critical bugs more-or-less steadily +decreased until we got to a release candidate. + +Of particular interest, the first release candidate of 2.14 was +released on 2011-01-12. Over the next 10 days, about a dozen bugs +were reported and fixed. Release candidate 2 came out on +2011-02-09. No surge of bugs occurred with this release. +Candidate 3 came out on 2011-03-13; we got 2 bugs per week. +Candidate 4 came out on 2011-03-29; 2 new bugs. Candidate 6 came +out on 2011-04-07. We got a couple of bugs per week. + +@subheading Notes, commentary, and opinions + +@example +Han-Wen: Overall, I think this cycle took too long +Mike: I agree +Graham: +1 +@end example + +@subsubheading Discussions + +@smallexample +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-06/msg00797.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00364.html} +@uref{} +@end smallexample + + +@node GOP-PROP 5 - build system output (not accepted) +@subsubsection GOP-PROP 5 - build system output (not accepted) + +This proposal was too broad; after a month of discussion, Graham +withdrew the proposal. Portions of it will be introduced in later +proposals. + +@subsubheading Discussions + +@smallexample +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00320.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00527.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00753.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg01042.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00116.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00310.html} +@end smallexample + + +@node GOP-PROP 6 - private mailing lists +@subsubsection GOP-PROP 6 - private mailing list + +Potentially sensitive or private matters will be referred to +Graham. He will then decide who should discuss the matter on an +ad-hoc basis, and forward or CC them on future emails. + +For emphasis, the project administrators are Han-Wen, Jan, and +Graham; those three will always be CC'd on any important +discussions. + +The lilypond-hackers mailing list will be removed. + +@subheading History + +There is some unhappy history about this idea in our development +community: + +@example +@uref{http://lists.gnu.org/archive/html/lilypond-devel/2010-09/msg00178.html} +@uref{http://news.lilynet.net/spip.php?article121} +@uref{http://lists.gnu.org/archive/html/lilypond-devel/2010-11/msg00076.html} +@end example + +@subheading Other projects + +The idea of private mailing lists is hardly uncommon in +open-source software. For example, + +@example +@uref{http://lwn.net/Articles/394660/} about debian-private +@uref{http://subversion.apache.org/mailing-lists.html} private@@ +@uref{http://www.freebsd.org/administration.html#t-core} +@uref{http://foundation.gnome.org/legal/} board members pledge +to keep certain matters confidential + +every security team of every GNU/Linux distribution and OS +@end example + +In fact, Karl Fogel's @qq{Producing Open Source Software} +explicitly suggests a private mailing list for some circumstances: + +@example +[on granting commit/push access to a contributor] + +But here is one of the rare instances where secrecy is +appropriate. You can't have votes about potential committers +posted to a public mailing list, because the candidate's feelings +(and reputation) could be hurt. + +@uref{http://producingoss.com/en/consensus-democracy.html#electorate} +@end example + +@subheading Board of governers, voting, etc? + +Many projects have an official board of directors, or a list of +@qq{core developers}, with set term limits and elections and +stuff. + +I don't think that we're that big. I think we're still small +enough, and there's enough trust and consensus decisions, that we +can avoid that. I would rather that we kept on going with +trust+consensus for at least the next 2-3 years, and spent more +time+energy on bug fixes and new features instead of +administrative stuff. + +Project administrators are Han-Wen, Jan, and Graham. + +@subsubheading Discussions + +@smallexample +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg00783.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg01004.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00117.html} +@end smallexample + + +@node GOP-PROP 7 - developers as resources +@subsubsection GOP-PROP 7 - developers as resources + +We shall treat developers (and contributors) as +@strong{Independent volunteers}: each person does whatever they +want, whenever they want. We have busy careers and lives; we make +no expectations of action from anybody (with the exception of the +6 people in @qq{Meister} positions). + +@subsubheading Discussions + +@smallexample +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-07/msg01092.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00087.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00497.html} +@end smallexample + + +@node GOP-PROP 8 - issue priorities +@subsubsection GOP-PROP 8 - issue priorities + +We will delete the @qq{priority} field of the issue tracker +altogether. The @qq{type} system will be tweaked. + +Type-critical: + +@itemize + +@item +a reproducible failure to build either @code{make} or @code{make +doc}, from an empty build tree, in a first run, if +@code{configure} does not report any errors. + +@item +any program behaviour which is @strong{unintentionally} worse than +the previous stable version or the current development version. +Developers may always use the @qq{this is intentional}, or even +the @qq{this is an unavoidable effect of an improvement in another +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 +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 +part(s) of the Contributor's Guide. Problems in other chapters of +the CG are not sufficient to qualify as Type-Critical. + +@end itemize + +@subsubheading More new/changed types and labels + +Unless otherwise specified, the current types and labels will +continue to be used. The new types introduced by this proposal +are: + +@itemize + +@item +Type-crash: any segfault, regardless of what the input file looks +like or which options are given. Disclaimer: this might not be +possible in some cases, for example certain guile programs (we +certainly can't predict if a piece of scheme will ever stop +running, i.e. the halting problem), or if we rely on other +programs (i.e. ghostscript). If there are any such cases that +make segfault-prevention impossible, we will document those +exceptions (and the issue will remain as a "crash" instead of +"documentation" until the warning has been pushed). + +@item +Type-maintainability: anything which makes it difficult for +serious contributors to help out (e.g. difficult to find the +relevant source tree(s), confusing policies, problems with +automatic indentation tools, etc). + +@item +Type-ugly: replaces Type-collision, and it will include things +like bad slurs in addition to actual collision. + +@end itemize + +A new label will be added: + +@itemize +@item +(label) Needs_evidence: it is not clear what the correct output +should look like. We need scans, references, examples, etc. + +@end itemize + +@subheading Reminding users about stars + +We can remind users that they can @qq{star} an issue to indicate +that they care about it. Since we resolved to treat developers as +independent volunteers, there is no expectation that anybody will +look at those stars, but if any developer want to organize their +work schedule according to the stars, they are welcome to do so. + +@subsubheading Discussions + +@smallexample +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00019.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00277.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00413.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00624.html} +@uref{} +@end smallexample + + +@node GOP-PROP 9 - behavior of make doc +@subsubsection GOP-PROP 9 - behavior of make doc + +If there are build problems, then it should be easier to find out +why it's failing. This will be achieved with log files, as well +as possibly including scripts which automatically display portions +of those log files for a failing build. + +We will also add targets for building a specific manual (for +quick+easy checking of doc work), as well as for building all +documentation in a specific language (either English or a +translated language). + +When you run @code{make doc}, + +@itemize + +@item +All output will be saved to various log files, with the exception +of output directly from @code{make(1)}. + +Note that @code{make(1)} refers to a specific executable file on +unix computers, and is not a general term for the build system. + +@item +By default, no other output will be displayed on the console, with +one exception: if a build fails, we might display some portion(s) +of log file(s) which give useful clues about the reason for the +failure. + +The user may optionally request additional output to be printed; +this is controlled with the @code{VERBOSE=x} flag. In such cases, +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{$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 +files. Log files produced from individual lilypond runs are not +under our control; apart from that, I anticipate having one or two +dozen log files. As long as it is clear which log file is +associated with which operation(s), I think this is entirely +appropriate. The precise implementation will be discussed for +specific patches as they appear. + +@item +Both stderr and stdout will be saved in @code{*.log}. The order +of lines from these streams should be preserved. + +@item +There will be no additional @qq{progress messages} during the +build process. If you run @code{make --silent}, a non-failing +build should print absolutely nothing to the screen. + +@item +Assuming that the loglevels patch is accepted, lilypond (inside +lilypond-book) will be run with --loglevel=WARN. +@uref{http://codereview.appspot.com/4822055/} + +@item +Ideally, a failing build should provide hints about the reason why +it failed, or at least hints about which log file(s) to examine. + +@end itemize + +If this proposal is accepted, none of these policies will be +assumed to apply to any other aspect of the build system. +Policies for any other aspect of the build system will be +discussed in separate proposals. + +@subheading Don't cause more build problems + +However, there is a danger in this approach, that vital error +messages can also be lost, thus preventing the cause of the +failure of a make being found. We therefore need to be +exceptionally careful to move cautiously, include plenty of tests, +and give time for people to experiment/find problems in each stage +before proceeding to the next stage. + +This will be done by starting from individual lilypond calls +within lilypond-book, and slowly moving to @qq{larger} targets of +the build system -- after the individual lilypond calls are are +producing the appropriate amount of output and this is saved in +the right place and we can automatically isolate parts of a +failing build, we will work on lilypond-book in general, and only +then will we look at the build system itself. + +@subheading Implementation notes + +There is an existing make variable QUIET_BUILD, which +alter the amount of output being displayed +(@uref{ +http://lilypond.org/doc/v2.15/Documentation/contributor/useful-make-variables} +). We are not planning on keeping this make variable. + +The standard way for GNU packages to give more output is with a +@code{V=x} option. Presumably this is done by increasing +@code{x}? If we support this option, we should still write log +files; we would simply print more of the info in those log files +to screen. + +The command @code{tee} may be useful to write to a file and +display to stdout (in the case of VERBOSE). + + +@subsubheading Discussions + +@smallexample +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00378.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00703.html} +@end smallexample + + +@ignore +@n ode GOP-PROP 10 - scheme indentation +@s ubsubsection GOP-PROP 10 - scheme indentation + +still under discussion + +@subsubheading Discussions + +@smallexample +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00625.html} +@uref{https://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg01026.html} +@c @uref{} +@end smallexample +@end ignore + + @node Grand LilyPond Input Syntax Standardization (GLISS) @section Grand LilyPond Input Syntax Standardization (GLISS) @@ -612,8 +1783,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 @@ -895,6 +2065,11 @@ and never allowing \transpose c d e1 @end verbatim +@item +What should be the officially encouraged way of writing music for +transposing instruments? Maybe it should be simplified? +See http://lists.gnu.org/archive/html/lilypond-user/2011-07/msg00130.html + @end itemize