@menu
* Introduction to issues::
+* Bug Squad setup::
* Bug Squad checklists::
* Issue classification::
* Adding issues to the tracker::
report contains enough information for developers, and checking
that a developer's fix actually resolves the problem.
+New volunteers for the Bug Squad should contact the
+@ref{Meisters, Bug Meister}.
+
+
+@node Bug Squad setup
+@section Bug Squad setup
+
+We highly recommend that you configure your email to use effective
+sorting; this can reduce your workload @emph{immensely}. The
+email folders names were chosen specifically to make them work if
+you sort your folders alphabetically.
+
+@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}.
+
+@item
+If you do not have one already, create a gmail account and send
+the email address to the @ref{Meisters, Bug Meister}.
+
+@item
+Subscribe your gmail account to @code{bug-lilypond}.
+
+@item
+Configure your google code account:
+
+@enumerate
+
+@item
+Sign in to google code by clicking in the top-right corner of:
+
+@example
+@uref{http://code.google.com/p/lilypond/issues/list}
+@end example
+
+@item
+Go to your @qq{Profile}, and select @qq{Settings}.
+
+@item
+Scroll down to @qq{Issue change notification}, and make sure that
+you have @emph{selected} @qq{If I starred the issue}.
+
+@end enumerate
+
+@item
+Configure your email client:
+
+@enumerate
+
+@item
+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,
+
+@example
+lilypond@@googlecode.com
+@end example
+
+@noindent
+should go into a separate @code{bug-ignore} folder. Alternately,
+you may automatically delete these emails.
+
+You will @strong{not read} these emails as part of your Bug Squad
+duties. If you are curious, go ahead and read them later, but it
+does @strong{not} count as Bug Squad work.
+
+@item
+Any other email sent to (or CC'd to):
+
+@example
+bug-lilypond
+@end example
+
+@noindent
+should go into a separate @code{bug-current} folder.
+
+@end enumerate
+
+@end enumerate
+
@node Bug Squad checklists
@section Bug Squad checklists
-We highly recommend that you configure your email client to put
-messages from:
+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.
+
+Please use the email sorting described in @ref{Bug Squad setup}.
+This means that (as Bug Squad members) you will only ever respond
+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
+15 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.
+
+
+@subsubheading Daily schedule
+
+The Bug Meister is omitted from the daily schedule.
@example
-@@googlecode.com
+Sunday: Valentin
+Monday: Dmytro
+Tuesday: James Bailey
+Wednesday: Ralph
+Thursday: Patrick
+Friday: Urs
+Saturday: Kieren
@end example
-@noindent
-into a separate folder than emails to @code{bug-lilypond}.
+@subsubheading Emails to @code{bug-answers}
+
+Some of these emails will be comments on issues that you added to
+the tracker.
-@subsubheading New emails to @code{bug-lilypond}
+@itemize
+If they are asking for more information, give the additional
+information.
+
+@item
+If the email says that the issue was classified in some other
+manner, read the rationale given and take that into account for
+the next issue you add.
+
+@item
+Otherwise, move them to your @code{bug-ignore} folder.
+
+@end itemize
+
+Some of these emails will be discussions about Bug Squad work;
+read those.
-Every new email to @code{bug-lilypond} should be handled within
-@strong{24 hours} in the first method which is applicable:
+
+@subsubheading Emails to @code{bug-current}
+
+Dealing with these emails is your main task. Your job is to get
+rid of these emails in the first method which is applicable:
@enumerate
+@item
+If the email has already been handled by a Bug Squad member (i.e.
+check to see who else has replied to it), delete it.
+
+@item
+If the email is a question about how to use LilyPond, reply with
+this response:
+
+@example
+For questions about how to use LilyPond, please read our
+documentation available from:
+ @uref{http://lilypond.org/website/manuals.html}
+or ask the lilypond-user mailing list.
+@end example
@item
-If the email is a question about how to use LilyPond, direct them
-politely to @code{lilypond-user}.
+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 after reading @rweb{Tiny examples}.
+user to resubmit the report with this response:
+
+@example
+I'm sorry, but due to our limited resources for handling bugs, we
+can only accept reports in the form of Tiny examples. Please see
+step 2 in our bug reporting guidelines:
+ @uref{http://lilypond.org/website/bug-reports.html}
+@end example
+
+@item
+If anything is unclear, ask the user for more information.
+
+How does the graphical output differ from what the user expected?
+What version of lilypond was used (if not given) and operating
+system (if this is a suspected cause of the problem)? In short,
+if you cannot understand what the problem is, ask the user to
+explain more. It is the user's responsibility to explain the
+problem, not your responsibility to understand it.
@item
If the behavior is expected, the user should be told to read the
-documentation, or asked to clarify how he misread the docs and how
-the docs could be improved.
+documentation:
+
+@example
+I believe that this is the expected behaviour -- please read our
+documentation about this topic. If you think that it really is a
+mistake, please explain in more detail. If you think that the
+docs are unclear, please suggest an improvement as described by
+@qq{Simple tasks -- Documentation} on:
+ @uref{http://lilypond.org/website/help-us.html}
+@end example
@item
If the issue already exists in the tracker, send an email to that
-effect.
+effect:
-@item
-Ask the user for more information, such as lilypond version number
-(if not given) and operating system (if this is a suspected cause
-of the problem).
+@example
+This issue has already been reported; you can follow the
+discussion and be notified about fixes here:
+@end example
+
+@noindent
+(copy+paste the google code issue URL)
@item
Accept the report as described in
@end enumerate
+All emails should be CC'd to the @code{bug-lilypond} list so that
+other Bug Squad members know that you have processed the email.
+
+@warning{There is no option for @qq{ignore the bug report} -- if
+you cannot find a reason to reject the report, you must accept
+it.}
+
+
+@ignore
+@c Try omitting this from Bug Squad duties
@subheading Updates / discussion about issues
discussions between advanced users and/or developers.
@end itemize
+@end ignore
@subheading Regular maintenance
Regression test comparison: if anything has changed suspiciously,
ask if it was deliberate. The official 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
+More information is available from in
+@ref{Precompiled regression tests}.
+
+
@item
Issues to verify: try to reproduce the bug with the latest
version; if you cannot reproduce the bug, mark the item
@uref{http://code.google.com/p/lilypond/issues/list?can=7}
@end example
+A few (approximately 10%) of these 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.
+
@end itemize
+
+@ignore
+@c try omitting from daily tasks for now. -gp
+
Once every @strong{two weeks} or so:
@itemize
@end itemize
+
@subheading Irregular maintenance
@warning{These tasks are a lot of work; gathering more volunteers
Checking all regtests: although we have a system for checking the
regtests between two versions, occasionally a bug will slip
through the cracks. It is therefore good to manually examine all
-the regtests (compare the images to the text description).
+the regtests (compare the images to the text description). More
+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
-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.
@end itemize
+@end ignore
+
@node Issue classification
@section Issue classification
that contributor.
@item
-Verified: Bug Squad has confirmed that the issue is closed.
+Verified: Bug Squad has confirmed that the issue is closed. This
+means that nobody should ever need look at the report again -- if
+there is any information in the issue that should be kept, open a
+new issue for that info.
@end itemize
issue should also have an estimated time in a comment.
@item
-Maintainability: hinders developent of LilyPond. For example,
+Maintainability: hinders development of LilyPond. For example,
improvements to the build system, or @qq{helper} python scripts.
@item
@ref{Issue classification}. In particular, the item should have
@code{Status}, @code{Type-}, and @code{Priority-} labels.
+Include output with the first applicable method:
+
+@itemize
+
+@item
+If the issue has a notation example which fits in one system,
+generate a small @file{bug.preview.png} file with:
+
+@example
+lilypond -dpreview bug.ly
+@end example
+
+@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:
+
+@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:
+
+@example
+lilypond --png bug.ly
+@end example
+
+@end itemize
+
@item
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
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}.
+