Improve pure-height estimations with outside-staff-priority.

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

diff --git a/Documentation/contributor/issues.itexi b/Documentation/contributor/issues.itexi
index 4be817384d7d764df14bb5841b7a88a010acda27..13932d1c9f8ee1db2e6decb66c2f5999cce83ceb 100644 (file)
--- a/Documentation/contributor/issues.itexi
+++ b/Documentation/contributor/issues.itexi
@@ -7,6 +7,7 @@ miscellaneous development tasks.
 
 @menu
 * Introduction to issues::
 
 @menu
 * Introduction to issues::

+* Bug Squad setup::

 * Bug Squad checklists::
 * Issue classification::
 * Adding issues to the tracker::
 * Bug Squad checklists::
 * Issue classification::
 * Adding issues to the tracker::


@@ -38,34 +39,186 @@ New volunteers for the Bug Squad should contact the
 @ref{Meisters, Bug Meister}.
 
 
 @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
 
 @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
 
 @example

-@@googlecode.com
+Sunday: Valentin
+Monday: Dmytro
+Tuesday: James Bailey
+Wednesday: Ralph
+Thursday: Patrick
+Friday: Urs
+Saturday: Kieren

 @end example
 
 @end example
 

-@noindent
-into a separate folder than other 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.
+
+@itemize
+If they are asking for more information, give the additional
+information.

 
 

-@subsubheading New emails to @code{bug-lilypond}
+@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.

 
 

-Every new email to @code{bug-lilypond} should be handled within
-@strong{24 hours} in the first method which is applicable:
+@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.
+
+
+@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
 
 @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
 
 @item

-If the email is a question about how to use LilyPond, direct them
-politely to @code{lilypond-user}.
+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 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
 
 @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.
 
 @item
 If anything is unclear, ask the user for more information.


@@ -75,16 +228,32 @@ 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
 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 reponsibility to understand it.
+problem, not your responsibility to understand it.

 
 @item
 If the behavior is expected, the user should be told to read the
 
 @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
 
 @item
 If the issue already exists in the tracker, send an email to that

-effect.
+effect:
+
+@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
 
 @item
 Accept the report as described in


@@ -100,6 +269,9 @@ you cannot find a reason to reject the report, you must accept
 it.}
 
 
 it.}
 
 

+@ignore
+@c Try omitting this from Bug Squad duties
+

 @subheading Updates / discussion about issues
 
 We try to keep discussions about issues on the tracker, but
 @subheading Updates / discussion about issues
 
 We try to keep discussions about issues on the tracker, but


@@ -124,6 +296,7 @@ reports; it is @emph{perfectly acceptable} to not understand
 discussions between advanced users and/or developers.
 
 @end itemize
 discussions between advanced users and/or developers.
 
 @end itemize

+@end ignore

 
 
 @subheading Regular maintenance
 
 
 @subheading Regular maintenance


@@ -145,6 +318,7 @@ ask if it was deliberate.  The official comparison is online, at:
 More information is available from in
 @ref{Precompiled regression tests}.
 
 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
 @item
 Issues to verify: try to reproduce the bug with the latest
 version; if you cannot reproduce the bug, mark the item


@@ -154,8 +328,17 @@ version; if you cannot reproduce the bug, mark the item
 @uref{http://code.google.com/p/lilypond/issues/list?can=7}
 @end example
 
 @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
 
 @end itemize
 

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

 Once every @strong{two weeks} or so:
 
 @itemize
 Once every @strong{two weeks} or so:
 
 @itemize


@@ -177,6 +360,7 @@ more work, then remove the @code{patch} label.
 
 @end itemize
 
 
 @end itemize
 

+

 @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


@@ -198,12 +382,14 @@ 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.
 
 @end itemize
 
 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
 
 @node Issue classification
 @section Issue classification


@@ -366,7 +552,7 @@ Frog: the fix is believed to be suitable for a new contributor
 issue should also have an estimated time in a comment.
 
 @item
 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
 improvements to the build system, or @qq{helper} python scripts.
 
 @item


@@ -418,6 +604,36 @@ 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.
 
 @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
 @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