Doc: CG - Tightening up of the Bug Squad intro

[lilypond.git] / Documentation / contributor / issues.itexi

diff --git a/Documentation/contributor/issues.itexi b/Documentation/contributor/issues.itexi
index b3c8404d8c0a29845ccc102224cf074acaf811cd..883328f85a2345a76760986b8e45fff1def3eda8 100644 (file)
--- a/Documentation/contributor/issues.itexi
+++ b/Documentation/contributor/issues.itexi
@@ -1,4 +1,4 @@
-@c -*- coding: utf-8; mode: texinfo; -*-
+Elu@c -*- coding: utf-8; mode: texinfo; -*-

 @node Issues
 @chapter Issues
 
 @node Issues
 @chapter Issues
 


@@ -7,40 +7,67 @@ miscellaneous development tasks.
 
 @menu
 * Introduction to issues::
 
 @menu
 * Introduction to issues::

-* Bug Squad setup::
-* Bug Squad checklists::
+* The Bug Squad::

 * Issue classification::
 * Adding issues to the tracker::
 * Issue classification::
 * Adding issues to the tracker::

+* Patch handling::

 * Summary of project status::
 * Summary of project status::

-* Finding the cause of a regression::

 @end menu
 
 
 @node Introduction to issues
 @section Introduction to issues
 
 @end menu
 
 
 @node Introduction to issues
 @section Introduction to issues
 

-@warning{Unless otherwise specified, all the tasks in this chapter
-are @qq{simple} tasks: they can be done by a normal user with
-nothing more than a web browser, email, and lilypond.}
+@warning{All the tasks in this chapter require no programming skills and
+can be done by anyone with a web browser, an email client and the
+ability to run LilyPond.}
+
+The term @q{issues} refers not just to software bugs but also includes
+feature requests, documentation additions and corrections as well as any
+other general code @q{TODOs} that need to be kept track of.
+
+
+@node The Bug Squad
+@section The Bug Squad
+
+@menu
+* Bug Squad setup::
+* Bug Squad checklists::
+@end menu
+
+To help keep track and organize all issues are a group of tireless
+volunteers collectively known as the @emph{Bug Squad}.  Composed mainly
+of non-programmers, the Bug Squad's responsibilities include:
+
+@itemize
+
+@item
+Monitoring the LilyPond Bugs mailing list looking for any issues
+reported by other users ensuring that they are accurate and contain
+enough information for the developers to work with, preferably with
+@rweb{Tiny examples} and if applicable, screenshots.
+
+@item
+Adding new issues to the @emph{issue tracker} or updating existing
+issues with new information.
+
+@item
+Verifying issues in the @emph{issue tracker} that have been marked
+as @q{fixed}; making sure either that the fix works or (in the case of
+Documentation for example) has at least been commited to the code base.

 
 

-@qq{Issues} isn't just a politically-correct term for @qq{bug}.
-We use the same tracker for feature requests and code TODOs, so
-the term @qq{bug} wouldn't be accurate.  Despite the difference
-between @qq{issue} and @qq{bug}, we call our team of contributors
-who organize issues the @emph{Bug Squad}.
+@end itemize

 
 

-The Bug Squad is mainly composed of non-programmers -- their job
-is to @emph{organize} issues, not solve them.  Their duties
-include removing false bug reports, ensuring that any real bug
-report contains enough information for developers, and checking
-that a developer's fix actually resolves the problem.
+The @ref{Meisters, Bug Meister} also helps check the current
+@ref{Regression tests} and highlights any significant changes (or
+problems) since the previous LilyPond release.

 
 

-New volunteers for the Bug Squad should contact the
+If you would like to be part of the Bug Squad, please contact the

 @ref{Meisters, Bug Meister}.
 
 
 @node Bug Squad setup
 @ref{Meisters, Bug Meister}.
 
 
 @node Bug Squad setup

-@section Bug Squad setup
+@subsection Bug Squad setup

 
 We highly recommend that you configure your email to use effective
 sorting; this can reduce your workload @emph{immensely}.  The
 
 We highly recommend that you configure your email to use effective
 sorting; this can reduce your workload @emph{immensely}.  The


@@ -50,9 +77,7 @@ you sort your folders alphabetically.
 @enumerate
 
 @item
 @enumerate
 
 @item

-Skim through every section of this chapter, @ref{Issues}.  Read in
-detail any sections called @qq{Bug Squad...}, or any page linked
-from @ref{Bug Squad checklists}.
+Read every section of this chapter, @ref{Issues}.

 
 @item
 If you do not have one already, create a gmail account and send
 
 @item
 If you do not have one already, create a gmail account and send


@@ -66,6 +91,13 @@ Configure your google code account:
 
 @enumerate
 
 
 @enumerate
 

+@item
+Wait until your gmail account is listed in:
+
+@example
+@uref{http://code.google.com/p/lilypond/people/list}
+@end example
+

 @item
 Sign in to google code by clicking in the top-right corner of:
 
 @item
 Sign in to google code by clicking in the top-right corner of:
 


@@ -73,6 +105,9 @@ Sign in to google code by clicking in the top-right corner of:
 @uref{http://code.google.com/p/lilypond/issues/list}
 @end example
 
 @uref{http://code.google.com/p/lilypond/issues/list}
 @end example
 

+You cannot log on if you have Google Sharing enabled
+@uref{http://www.googlesharing.net/}.
+

 @item
 Go to your @qq{Profile}, and select @qq{Settings}.
 
 @item
 Go to your @qq{Profile}, and select @qq{Settings}.
 


@@ -91,6 +126,10 @@ Configure your email client:
 Any email sent with your gmail address in the @code{To:} or
 @code{CC:} fields should go to a @code{bug-answers} folder.
 
 Any email sent with your gmail address in the @code{To:} or
 @code{CC:} fields should go to a @code{bug-answers} folder.
 

+When setting up your filtering rules, be aware that Google Code
+might use different versions of your email address, such as ones
+ending in @code{@@googlemail.com} or @code{@@gmail.com}.
+

 @item
 Any other email either from, or CC'd to,
 
 @item
 Any other email either from, or CC'd to,
 


@@ -122,10 +161,10 @@ should go into a separate @code{bug-current} folder.
 
 
 @node Bug Squad checklists
 
 
 @node Bug Squad checklists

-@section Bug Squad checklists
+@subsection Bug Squad checklists

 
 When you do Bug Squad work, start at the top of this page and work
 
 When you do Bug Squad work, start at the top of this page and work

-your way down.  Stop when you've done 15 minutes.
+your way down.  Stop when you've done 20 minutes.

 
 Please use the email sorting described in @ref{Bug Squad setup}.
 This means that (as Bug Squad members) you will only ever respond
 
 Please use the email sorting described in @ref{Bug Squad setup}.
 This means that (as Bug Squad members) you will only ever respond


@@ -135,22 +174,22 @@ to emails sent or CC'd to the @code{bug-lilypond} mailing list.
 @subsubheading Emails to you personally
 
 You are not expected to work on Bug Squad matters outside of your
 @subsubheading Emails to you personally
 
 You are not expected to work on Bug Squad matters outside of your

-15 minutes, but sometimes a confused user will send a bug report
+20 minutes, but sometimes a confused user will send a bug report

 (or an update to a report) to you personally.  If that happens,
 please forward such emails to the @code{bug-lilypond} list so that
 the currently-active Bug Squad member(s) can handle the message.
 
 
 (or an update to a report) to you personally.  If that happens,
 please forward such emails to the @code{bug-lilypond} list so that
 the currently-active Bug Squad member(s) can handle the message.
 
 

-@subsubheading Daily schedule
+@subsubheading Daily schedule as of July 2015

 
 @example
 
 @example

-Sunday: Valentin
-Monday: Dmytro
-Tuesday: James Bailey
-Wednesday: Ralph
-Thursday: Phil Holmes
-Friday: Urs Liska, Patrick
-Saturday: Kieren
+Monday: Federico Bruni
+Tuesday: Simon Albrecht
+Wednesday: Simon Albrecht
+Thursday: Colin Campbell
+Friday: Ralph Palmer
+Saturday: Colin Campbell
+Sunday:

 @end example
 
 
 @end example
 
 


@@ -198,6 +237,11 @@ documentation available from:
 or ask the lilypond-user mailing list.
 @end example
 
 or ask the lilypond-user mailing list.
 @end example
 

+@item
+If the email mentions @qq{the latest git}, or any version number
+that has not yet been officially released, forward it to
+@code{lilypond-devel}.
+

 @item
 If a bug report is not in the form of a Tiny example, direct the
 user to resubmit the report with this response:
 @item
 If a bug report is not in the form of a Tiny example, direct the
 user to resubmit the report with this response:


@@ -209,7 +253,6 @@ step 2 in our bug reporting guidelines:
   @uref{http://lilypond.org/website/bug-reports.html}
 @end example
 
   @uref{http://lilypond.org/website/bug-reports.html}
 @end example
 

-

 @item
 If anything is unclear, ask the user for more information.
 
 @item
 If anything is unclear, ask the user for more information.
 


@@ -296,61 +339,91 @@ After @strong{every release} (both stable and unstable):
 @itemize
 
 @item
 @itemize
 
 @item

-Regression test comparison: if anything has changed suspiciously,
-ask if it was deliberate.  The official comparison is online, at:
+Issues to verify: go to

 
 

-@c NOTE: leave this here.  In this case, it's worth duplicating
-@c       the link.  -gp

 @example
 @example

-@uref{http://lilypond.org/test/}
+@uref{http://code.google.com/p/lilypond/issues/list?can=7}

 @end example
 
 @end example
 

-More information is available from in
-@ref{Precompiled regression tests}.
+(You can also generate this list by selecting
+@qq{Issues to verify} from the drop-down list next to the search
+box.)
+
+You should see a list of Issues that have been claimed fixed by a
+developer.  If the developer has done their job properly, the
+Issue should have a tag @qq{Fixed_mm_MM_ss}, where mm is
+the major version, MM the minor version and ss the current
+release.  This will help you work out which you can verify - do
+not verify any Issues where the claimed fixed build is not yet
+released.  Work your way through these as follows:
+
+If the Issue refers to a bug, try to reproduce the bug with the latest
+officially released version (not one you've built yourself from
+source); if the bug is no longer there, mark the
+issue @qq{Verified} (i.e. @qq{the fix has been verified to work}).
+
+Quite a few of these will be issues tracking patches.  @strong{You
+do not have to prove these patches work - simply that they have
+been pushed into the code base.}  The developer should have put
+information similar to @qq{Pushed as as
+d8fce1e1ea2aca1a82e25e47805aef0f70f511b9} in the tracker.  The
+long list of letters and numbers is called the @qq{committish}.
+Providing you can find this at the git tracker:

 
 

+@example
+@uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
+@end example

 
 

-@item
-Issues to verify: try to reproduce the bug with the latest
-version; if you cannot reproduce the bug, mark the item
-@qq{Verified} (i.e. @qq{the fix has been verified to work}).
+then you should mark the issue as verified.  A quick way of
+finding these is to enter the committish at the following address:

 
 @example
 
 @example

-@uref{http://code.google.com/p/lilypond/issues/list?can=7}
+@uref{http://philholmes.net/lilypond/git/}

 @end example
 
 @end example
 

-A few (approximately 10%) of these fixed issues relate to the
+The Issue tracker also requires that any issues labelled as
+@qq{Duplicate} are also verified.  Check that the linked issue is
+a duplicate and verify the issue.
+
+A few (approximately 10%) of the fixed issues relate to the

 build system or fundamental architecture changes; there is no way
 for you to verify these.  Leave those issues alone; somebody else
 will handle them.
 
 build system or fundamental architecture changes; there is no way
 for you to verify these.  Leave those issues alone; somebody else
 will handle them.
 

-@end itemize
+@item
+The official regression test comparison is online at:

 
 

+@c NOTE: leave this here.  In this case, it's worth duplicating
+@c       the link.  -gp
+@example
+@uref{http://lilypond.org/test/}
+@end example

 
 

-@ignore
-@c try omitting from daily tasks for now. -gp
+If anything has changed suspiciously,
+ask if it was deliberate.  If the text output from LilyPond (the
+logfile) changes, the differences will be displayed with a +
+before text added to the logfile and - before any text removed
+from the logfile.  This may or may not be suspicious.

 
 

-Once every @strong{two weeks} or so:
+There is one test designed to produce output every time the
+regtests are created. @code{test-output-distance.ly} creates
+randomly spaced notes and will always have different output if the
+regtest checker is working.

 
 

-@itemize
+More information is available from in
+@ref{Precompiled regression tests}.

 
 @item
 Check for any incorrectly-classified items in the tracker.  This
 generally just means looking at the grid to see any items without
 
 @item
 Check for any incorrectly-classified items in the tracker.  This
 generally just means looking at the grid to see any items without

-a Type or Priority.
-
-@item
-Check for any items with @code{label:patch}.  If it's been more
-than a week since the last action on the issue, send an email to
--devel to remind them about it.  If the patch was withdrawn for
-more work, then remove the @code{patch} label.
-
-@example
-@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch}
-@end example
+a Type.

 
 @end itemize
 
 
 
 @end itemize
 
 

+@ignore
+@c try omitting from daily tasks for now. -gp
+

 @subheading Irregular maintenance
 
 @warning{These tasks are a lot of work; gathering more volunteers
 @subheading Irregular maintenance
 
 @warning{These tasks are a lot of work; gathering more volunteers


@@ -372,7 +445,7 @@ information is available from in @ref{Regression tests}.
 @item
 Checking all issues: we try to mark each Issue @q{fixed} when we
 fix it, but occasionally one or two issues will slip through the
 @item
 Checking all issues: we try to mark each Issue @q{fixed} when we
 fix it, but occasionally one or two issues will slip through the

-cracks.  It is therefore good to check all Issues. If you see the
+cracks.  It is therefore good to check all Issues.  If you see the

 same (broken) output as the initial report, then simply post a
 @qq{Problem still exists in 2.x.y} message to the issue.
 
 same (broken) output as the initial report, then simply post a
 @qq{Problem still exists in 2.x.y} message to the issue.
 


@@ -385,8 +458,8 @@ same (broken) output as the initial report, then simply post a
 @section Issue classification
 
 The Bug Squad should classify issues according to the guidelines
 @section Issue classification
 
 The Bug Squad should classify issues according to the guidelines

-given by developers.  Every issue should have a Status, Type, and
-Priority; the other fields are optional.
+given by developers.  Every issue should have a Status and Type;
+the other fields are optional.

 
 @subheading Status (mandatory)
 
 
 @subheading Status (mandatory)
 


@@ -447,7 +520,23 @@ The issue's Type should be the first relevant item in this list.
 @itemize
 
 @item
 @itemize
 
 @item

-Type-Collision: overlapping notation.
+Type-Critical: normally a regression
+against the current stable version or the previous stable version.
+Alternatively, a regression against a fix developed for the
+current version. This does not apply where the
+@qq{regression} occurred because a feature was removed
+deliberately - this is not a bug.
+
+Currently, only Critical items will block a stable release.
+
+@item
+Type-Maintainability: hinders future development.
+
+@item
+Type-Crash: any input which produces a crash.
+
+@item
+Type-Ugly: overlapping or other ugly notation in graphical output.

 
 @item
 Type-Defect: a problem in the core program.  (the @code{lilypond}
 
 @item
 Type-Defect: a problem in the core program.  (the @code{lilypond}


@@ -465,17 +554,22 @@ includes the makefiles, stepmake, python scripts, and GUB.
 @item
 Type-Scripts: problem or desired feature in the non-build-system
 scripts.  Mostly used for convert-ly, lilypond-book, etc.
 @item
 Type-Scripts: problem or desired feature in the non-build-system
 scripts.  Mostly used for convert-ly, lilypond-book, etc.

+

 @item
 Type-Enhancement: a feature request for the core program.  The
 distinction between enhancement and defect isn't extremely clear;
 when in doubt, mark it as enhancement.
 
 @item
 Type-Enhancement: a feature request for the core program.  The
 distinction between enhancement and defect isn't extremely clear;
 when in doubt, mark it as enhancement.
 

+@item
+Type-Patch: tracking a patch on Rietveld.  Bug squad should not
+need to use this label.
+

 @item
 Type-Other: anything else.
 
 @end itemize
 
 @item
 Type-Other: anything else.
 
 @end itemize
 

-
+@ignore

 @subheading Priority (mandatory)
 
 Currently, only Critical items will block a stable release.
 @subheading Priority (mandatory)
 
 Currently, only Critical items will block a stable release.


@@ -483,42 +577,91 @@ Currently, only Critical items will block a stable release.
 @itemize
 
 @item
 @itemize
 
 @item

-Priority-Critical: lilypond segfaults, or a regression occurred
-within the last two stable versions.  (i.e. when developing 2.13,
-any regression against 2.12 or 2.10 counts)
+Priority-Critical: LilyPond segfaults, a regression (see below)
+against a previous stable version or a regression against a fix
+developed for this version. This does not apply where the
+@qq{regression} occurred because a feature was removed
+deliberately - this is not a bug.

 
 @item
 
 @item

-Priority-High: highly embarrassing items, and any regression
-against a version earlier than two stable versions (i.e. when
-developing 2.13, any regression against 2.8 or earlier).  This
-level is also used for issues which produce no output and fail to
-give the user a clue about what's wrong.
+Priority-High: An issue which produces output which does not
+accurately reflect the input (e.g. where the user would expect
+an accidental, but none is shown) or which produces aesthetically
+poor output in a situation which could be expected to crop up
+frequently in real-world music.  It should not be used where the
+problem can be avoided with a simple workaround.  It can also
+be used to flag where new code in a development version is not
+functioning as it should.  This level is also used for issues
+which produce no output and fail to give the user a clue about
+what's wrong.

 
 @item
 
 @item

-Priority-Medium: normal priority.
+Priority-Medium: Normal priority - use this as the default.

 
 @item
 
 @item

-Priority-Low: less important than normal.
+Priority-Low: A minor problem which produces slightly undesirable
+output, or which will only occur in contrived examples, or which
+is very easily worked around.

 
 @item
 Priority-Postponed: no fix planned.  Generally used for things
 
 @item
 Priority-Postponed: no fix planned.  Generally used for things

-like Ancient notation, which nobody wants to touch.
+which nobody wants to touch.

 
 @end itemize
 
 
 @end itemize
 

-The difference between Priority-Medium and Priority-Low is not
-well-defined, both in this policy and in practice.  The only
-answer we can give at the moment is @qq{look at existing items in
-of the same type, and try to guess whether the priority is closer
-to the Medium items or Low items}.  We're aware of the ambiguity,
-and won't complain if somebody picks a @q{wrong} value for
-Medium/Low.
+Note that these are initial classifications and can be subject
+to change by others in the development team.  For example, a
+regression against an old stable version which hasn't been
+noticed for a long time and which is unlikely to get fixed could
+be downgraded from Priority-Critical by one of the programmers.

 
 

+@end ignore

 
 @subheading Opsys (optional)
 
 Issues that only affect specific operating systems.
 
 
 @subheading Opsys (optional)
 
 Issues that only affect specific operating systems.
 

+@subheading Patch label (optional)
+
+Normal Bug Squad members should not add or modify Patch issues
+except to verify them; for all other Patch work, leave them to the
+Patch Meister.
+
+@itemize
+
+@item
+Patch-new: the patch has not been checked for @qq{obvious}
+mistakes.  When in doubt, use this tag.
+
+@item
+Patch-review: the patch has no @qq{obvious} mistakes (as checked
+by the Patch Meister), and is ready for review from main
+developers.
+
+Developers with git push ability can use this category, skipping
+over @code{patch-new}.
+
+@item
+Patch-needs_work: a developer has some concerns about the patch.
+This does not necessarily mean that the patch must be changed; in
+some cases, the developer's concerns can be resolved simply by
+discussion the situation or providing notation examples.
+
+If the patch is updated, the category should be changed to
+@code{patch-new} (for normal contributors) or @code{patch-review}
+(for developers who are very confident about their patch).
+
+@item
+Patch-countdown: final call for any patch problems
+
+@item
+Patch-push: patch has passed the countdown and should be pushed.
+
+@item
+Patch-abandoned: the author has not responded to review comments
+for a few months.
+
+@end itemize

 
 @subheading Other items (optional)
 
 
 @subheading Other items (optional)
 


@@ -527,24 +670,39 @@ Other labels:
 @itemize
 
 @item
 @itemize
 
 @item

-Regression: it used to @strong{deliberately} work in an earlier
-stable release.  If the earlier output was accidental (i.e. we
-didn't try to stop a collision, but it just so happened that two
-grobs didn't collide), then breaking it does not count as a
-regression.
+Regression: it used to work intentionally in the current
+stable release or the previous stable release.  If the earlier
+output was accidental (i.e. we didn't try to stop a collision,
+but it just so happened that two grobs didn't collide), then
+breaking it does not count as a regression.
+
+To help decide whether the change is a regression, please adopt
+the following process:
+
+@enumerate

 
 @item
 
 @item

-Patch: a patch to fix an issue is attached.
+Are you certain the change is OK?  If so, do nothing.
+
+@item
+Are you certain that the change is bad?  Add it to the tracker
+as a regression.
+
+@item
+If you're not certain either way, add it to the tracker as a
+regression but be aware that it may be recategorised or marked
+invalid.
+
+@end enumerate
+
+In particular, anything that breaks a regression test is a
+regression.

 
 @item
 Frog: the fix is believed to be suitable for a new contributor
 (does not require a great deal of knowledge about LilyPond).  The
 issue should also have an estimated time in a comment.
 
 
 @item
 Frog: the fix is believed to be suitable for a new contributor
 (does not require a great deal of knowledge about LilyPond).  The
 issue should also have an estimated time in a comment.
 

-@item
-Maintainability: hinders development of LilyPond.  For example,
-improvements to the build system, or @qq{helper} python scripts.
-

 @item
 Bounty: somebody is willing to pay for the fix.  Only add this tag
 if somebody has offered an exact figure in US dollars or euros.
 @item
 Bounty: somebody is willing to pay for the fix.  Only add this tag
 if somebody has offered an exact figure in US dollars or euros.


@@ -557,15 +715,18 @@ to warnings when compiling the source code or generating
 documentation.
 
 @item
 documentation.
 
 @item

-Security: might potentially be used.
+Security: security risk.

 
 @item
 
 @item

-Performance: might potentially be used.
+Performance: performance issue.

 
 @end itemize
 
 
 @end itemize
 

-If you particularly want to add an label not in the list, go
-ahead, but this is not recommended.
+If you particularly want to add a label not in the list, go
+ahead, but this is not recommended, except when an issue is marked
+as fixed.  In this case it should be labeled Fixed_mm_MM_ss,
+where mm is major version, MM minor version and ss current
+release.

 
 
 @node Adding issues to the tracker
 
 
 @node Adding issues to the tracker


@@ -578,8 +739,6 @@ follow the guidelines for @rweb{Bug reports}.}
 In order to assign labels to issues, Bug Squad members should log
 in to their google account before adding an item.
 
 In order to assign labels to issues, Bug Squad members should log
 in to their google account before adding an item.
 

-@subsubheading Normal issues
-

 @enumerate
 
 @item
 @enumerate
 
 @item


@@ -592,7 +751,7 @@ have been added.
 @item
 Add the issue and classify it according to the guidelines in
 @ref{Issue classification}.  In particular, the item should have
 @item
 Add the issue and classify it according to the guidelines in
 @ref{Issue classification}.  In particular, the item should have

-@code{Status}, @code{Type-}, and @code{Priority-} labels.
+@code{Status} and @code{Type-} labels.

 
 Include output with the first applicable method:
 
 
 Include output with the first applicable method:
 


@@ -600,7 +759,7 @@ Include output with the first applicable method:
 
 @item
 If the issue has a notation example which fits in one system,
 
 @item
 If the issue has a notation example which fits in one system,

-generate a small @file{bug@/.preview@/.png} file with:
+generate a small @file{bug.preview.png} file with:

 
 @example
 lilypond -dpreview bug.ly
 
 @example
 lilypond -dpreview bug.ly


@@ -608,20 +767,44 @@ lilypond -dpreview bug.ly
 
 @item
 If the issue has an example which requires more than one system
 
 @item
 If the issue has an example which requires more than one system

-(i.e. a spacing bug), generate a @file{bug@/.png} file with:
+(i.e. a spacing bug), generate a @file{bug.png} file with:

 
 @example
 lilypond --png bug.ly
 @end example
 
 @item
 
 @example
 lilypond --png bug.ly
 @end example
 
 @item

-If the issue requires multi-page output, then generate a
-@file{bug@/.pdf} file with the normal:
+If the issue requires one or two pages of output, then generate a
+@file{bug.png} file with the normal:

 
 @example
 lilypond --png bug.ly
 @end example
 
 
 @example
 lilypond --png bug.ly
 @end example
 

+@item
+Images created as @file{bug.png} may be trimmed to a minimum size
+by using the @code{trimtagline.sh} script, which can be found at
+
+@smallexample
+@uref{https://raw.github.com/gperciva/lilypond-extra/master/bug-squad/trimtagline.sh}
+@end smallexample
+
+@example
+trimtagline.sh bug.ly
+@end example
+
+@item
+If the issue cannot be shown with less than three pages, then
+generate a @file{bug.pdf} file with:
+
+@example
+lilypond --pdf bug.ly
+@end example
+
+Note that this is likely to be extremely rare; most bugs should
+fit into the first two categories above.
+
+

 @end itemize
 
 @item
 @end itemize
 
 @item


@@ -634,18 +817,142 @@ email should contain a link to the issue you just added.
 @end enumerate
 
 
 @end enumerate
 
 

-@subsubheading Patch reminders
+
+@node Patch handling
+@section Patch handling

 
 @warning{This is not a Bug Squad responsibility; we have a
 separate person handling this task.}
 
 
 @warning{This is not a Bug Squad responsibility; we have a
 separate person handling this task.}
 

-There is a special category of issues: reminders of an existing
-patch.  These should be added if a patch has been sent to a
-lilypond mailing list (generally @code{lilypond-devel}, but they
-sometimes appear on @code{bug-lilypond} as well) and has had no
-discussion for at least @strong{3 days}.  Do not add issues for
-patches under active discussion.
+For contributors/developers: follow the steps in
+@ref{Commits and patches}, and @ref{Pushing to staging}.
+
+@ignore
+For people doing maintenance tasks: git-cl is adding issues, James
+is testing them, Colin is selecting them for countdowns, and
+Patchy is merging from staging to master.  In the coming weeks,
+these tasks will be more and more automated.
+@end ignore
+
+@subheading Patch cycle
+
+@itemize
+
+@item
+Patches get added to the tracker and to Rietveld by the @qq{git-cl} tool, with
+a status of @qq{patch-new}.
+
+@item
+The automated tester, Patchy, verifies that the patch can be applied
+to current master.  By default, it checks that the patch allows @code{make}
+and @code{make test} to complete successfully.  It can also be configured to
+check that @code{make doc} is successful. If it passes, Patchy changes the
+status to @qq{patch-review} and emails the developer list.  If the patch
+fails, Patchy sets it to @qq{patch-needs_work} and notifies the developer list.
+
+@item
+The Patch Meister reviews the tracker periodically, to list patches
+which have been on review for at least 24 hours. The list is found at
+
+@smallexample
+@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch%20patch=review&sort=modified+patch&colspec=ID%20Type%20Status%20Priority%20Owner%20Patch%20Summary%20Modified}
+@end smallexample
+
+@item
+For each patch, the Handler reviews any discussion on the tracker
+and on Rietveld, to determine whether the patch can go forward.  If
+there is any indication that a developer thinks the patch is not
+ready, the Handler marks it @qq{patch-needs_work} and makes a comment
+regarding the reason, referring to the Rietveld item if needed.
+
+@item
+Patches with explicit approval, or at least no negative comment, can
+be updated to @qq{patch-countdown}.  When saving the tracker item,
+clear the @qq{send email} box to prevent sending notification for
+each patch.
+
+@item
+The Patch Meister sends an email to the developer list, with a fixed
+subject line, to enable filtering by email clients:
+
+@example
+PATCH: Countdown to 20130113
+@end example
+
+The text of the email sets the deadline for this countdown batch.  At
+present, batches are done on Tuesday, Thursday and Sunday evenings.

 
 

+To create the countdown announcement, use the
+@code{make-countdown-announcement.sh} script, which takes the
+deadline date, and optionally your name.  Follow the instructions
+provided:
+
+@example
+cd $LILYPOND_GIT
+scripts/auxiliar/make-countdown-announcement.sh "Jan 1, 2001" James
+@end example
+
+The script produces an announcement that is easily readable in all
+email clients.  Also, whenever a new contributor submits a patch,
+you will be prompted to add the new username and author name to
+the script itself, and then commit those changes to the main git
+repository.
+
+
+@item
+On the scheduled countdown day, the Patch Meister reviews the
+previous list of patches on countdown, with the same procedure and
+criteria as before.  Patches with no controversy can be set to
+@qq{patch-push} with a courtesy message added to the comment block.
+
+@item
+Roughly at six month intervals, the Patch Meister can list the
+patches which have been set to @qq{patch-needs-work} and send the
+results to the developer list for review.  In most cases, these
+patches should be marked @qq{patch-abandoned} but this should come
+from the developer if possible.
+
+@item
+As in most organisations of unpaid volunteers, fixed procedures are
+useful in as much as they get the job done.  In our community, there
+is room for senior developers to bypass normal patch handling flows,
+particularly now that the testing of patches is largely automated.
+Similarly, the minimum age of 24 hours can reasonably be waived if
+the patch is minor and from an experienced developer.
+
+
+@end itemize
+
+@ignore
+There is a single Patch Meister, and a number of Patch Helpers
+(rename this?).  The list of known patches awaiting review is:
+
+@example
+@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch&sort=patch}
+@end example
+
+
+@subheading Helpers: adding patches
+
+The primary duty is to add patches to the google tracker; we have
+a bad track record of losing patches in email.  Patches generally
+come to the @code{lilypond-devel} mailing list, but are sometimes
+sent to @code{bug-lilypond}, @code{lilypond-users}, or
+@code{frogs} mailing list instead.
+
+@itemize
+@item
+Unless a patch is clearly in response to an existing issue, add a
+new issue with the @code{Patch-new} label and a link to the patch
+(either on the mailing list archives or the codereview url).
+
+Issue numbers are cheap; losing developers because they got fed up
+with us losing their hard work is expensive.
+
+@end ignore
+@c if we enter patches immediately, I don't think this is relevant.
+@ignore
+@item

 Before adding a patch-reminder issue, do a quick check to see if
 it was pushed without sending any email.  This can be checked for
 searching for relevant terms (from the patch subject or commit
 Before adding a patch-reminder issue, do a quick check to see if
 it was pushed without sending any email.  This can be checked for
 searching for relevant terms (from the patch subject or commit


@@ -654,65 +961,126 @@ message) on the webgit page:
 @example
 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
 @end example
 @example
 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
 @end example

+@end ignore
+@ignore
+
+@item
+If the patch is clearly in response to an existing issue, then
+update that issue with the @code{Patch-new} label and a link to
+the patch (either on the mailing list archives or the codereview
+url).

 
 

+@item

 After adding the issue, please send a response email to the same
 After adding the issue, please send a response email to the same

-group(s) that the initial patch was sent to.  If the initial email
-was sent to multiple mailing lists (such as both @code{bugs} and
-@code{devel}), then reply to all those mailing lists as well.  The
-email should contain a link to the issue you just added.
+group(s) that the initial patch was sent to.
+
+If the initial email was sent to multiple mailing lists (such as
+both @code{bugs} and @code{devel}), then reply to all those
+mailing lists as well.  The email should contain a link to the
+issue you just added.
+
+@end itemize
+
+@subheading Helpers: @code{Patch-review} label
+
+The secondary duty is to do make sure that every issue in the
+tracker with a @code{Patch-review} label has passed these
+@qq{obvious} tests:
+
+@itemize
+@item
+Applies automatically to git master.
+
+It's ok to have offsets, but not conflicts.
+
+@item
+Regtest comparison looks ok; no unexpected changes.
+
+@item
+Descriptive subject line.
+
+Avoid subjects like @qq{fixes 123}; instead write @qq{Doc: discuss
+stacking-dir for BassFigureAlignment (fix 123)}.
+
+@item
+Compiles docs from scratch.  Only check this if you have reason to
+suspect it might not work.
+
+@item
+(maybe)
+
+Check code indentation and style.  This should be easier post-GOP
+when we have a better-defined code style.
+
+@end itemize

 
 
 
 

+@subheading Patch Meister
+
+The Patch Meister will:
+
+@itemize
+
+@item
+send @qq{countdown} emails to
+@code{lilypond-devel} when patches appear to be ready.
+
+@item
+send general requests to review patches, or even nasty requests to
+review patches.
+
+@item
+downgrade patches from @code{Patch-review} to
+@code{Patch-needs_work} as appropriate.
+
+@item
+downgrade patches from @code{Patch-needs_work} to
+@code{Patch-abandoned} if no actions have been taken in four
+weeks.
+
+@end itemize
+
+@end ignore
+

 
 @node Summary of project status
 @section Summary of project status
 
 
 @node Summary of project status
 @section Summary of project status
 

-The best overview of our current status is given by the grid view:
+@subsubheading Project overview

 
 

-@example
+Grid view provides the best overview:
+
+@smallexample

 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}
 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}

-@end example
+@end smallexample

 
 

-Also of interest might be the issues hindering future development:
+@subsubheading Hindering development

 
 

-@example
-@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability&mode=grid&y=Priority&x=Type&cells=ids}
-@end example
+These issues stop or slow development work:
+
+@smallexample
+@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability}
+@end smallexample

 
 

-Finally, issues tagged with @code{Frog} indicates a task suitable
-for a relatively new contributor.  The time given is a quick
+@subsubheading Easy tasks
+
+Issues tagged with @code{Frog} indicates a task suitable for a
+relatively new contributor.  The time given is a quick

 (inaccurate) estimate of the time required for somebody who is
 familiar with material in this manual, but does not know anything
 else about LilyPond development.
 
 (inaccurate) estimate of the time required for somebody who is
 familiar with material in this manual, but does not know anything
 else about LilyPond development.
 

-@example
-@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog&mode=grid&y=Priority&x=Type&cells=ids}
-@end example
-
+@smallexample
+@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog}
+@end smallexample

 
 

-@node Finding the cause of a regression
-@section Finding the cause of a regression
+@subsubheading Patches to review

 
 

-@warning{This is not a @qq{simple} task; it requires a fair amount
-of technical knowledge.}
+Patches which have no @qq{obvious} problems:

 
 

-Git has special functionality to help tracking down the exact
-commit which causes a problem.  See the git manual page for
-@code{git bisect}.  This is a job that non-programmers can do,
-although it requires familiarity with git, ability to compile
-LilyPond, and generally a fair amount of technical knowledge.  An
-in-depth explanation of this process will not be given here.
-
-Even if you are not familiar with git or are not able to compile
-LilyPond you can still help to narrow down the cause of a
-regression simply by downloading the binary releases of different
-LilyPond versions and testing them for the regression.  Knowing
-which version of LilyPond first exhibited the regression is
-helpful to a developer as it shortens the @code{git bisect}
-procedure described above.
+@example
+@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch-review}
+@end example

 
 

-Once a problematic commit is identified, the programmers' job is
-much easier.  In fact, for most regression bugs, the majority of
-the time is spent simply finding the problematic commit.

 
 

-More information is in @ref{Regression tests}.