@c -*- coding: us-ascii; mode: texinfo; -*-
@node Issues
@chapter Issues

This chapter deals with defects, feature requests, and
miscellaneous development tasks.

@menu
* Introduction to issues::
* Issue classification::
* Adding issues to the tracker::
* Checking and verifying issues::
* Summary of project status::
* Finding the cause of a regression::
@end menu


@node Introduction to issues
@section Introduction to issues

First, @qq{issue} 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.

Second, the classification of what counts as a bug vs. feature
request, and the priorities assigned to bugs, are a matter of
concern @strong{for developers only}.  If you are curious about
the classification, read on, but don't complain that your
particular issue is higher priority or counts as a bug rather than
a feature request.


@node Issue classification
@section Issue classification

Status values:

@itemize

@item
New: the item was added by a non-member.  Should be reviewed by
the Bug Meister.

@item
Accepted: the Bug Meister added it, or reviewed the item.

@item
Started: a programmer is working on a bugfix.  (used infrequently,
but should be used more often)

@end itemize

Closed status values:

@itemize

@item
Invalid: issue should not have been added in the current state.

@item
Duplicate: issue already exists in the tracker.

@item
Fixed: programmer claims to have fixed the bug.  The Bug Meister
should check the input code in an official binary release.

@item
Verified: Bug Meister has confirmed that the issue is closed.

@end itemize

Type labels:

@itemize

@item
Type-Defect: a problem that requires no (or very little) new code
to fix.

@item
Type-Enhancement: a problem (or new feature) that requries a
significant amount of new code.

@item
Type-Collision: overlapping notation.  (this label takes
precedence over -Defect and -Enhancement)

@item
Type-Task: not used, I think.  TODO: start using it or delete it.

@item
Type-Other: anything else.  TODO: start using it or delete it.

@end itemize

Priority labels:

@itemize

@item
Priority-High: lilypond segfaults.

@item
Priority-Regression: it used to work.

@item
Priority-Medium: normal priority; this is the highest priority a
non-crashing, non-regression bug report can receive.
(regardless of the perceived importance)

@item
Priority-Low: less important than normal.

@item
Priority-Postponed: no fix planned.  Generally used for things
like Ancient notation, which nobody wants to touch.

@end itemize

Opsys labels: pretty self-explanatory.

Other labels:

@itemize

@item
Patch: a patch to fix an issue is attached.

@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
Security: not used.  TODO: delete, unless anybody is serious about
this.

@item
Performance: not used.  TODO: delete.

@item
Usability: not used.  TODO: delete.

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

@item
Bounty: somebody is willing to pay for the fix.

@item
Engraving-nitpick: output is not beautiful, but not strictly
speaking @qq{wrong}.  For example, a slur shape which does not
collide with any notation, but looks ugly.

@item
Warning-nitpick: graphical output is fine, but lilypond prints a
false/misleading warning message.

@end itemize


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

TODO: prettify.

only done by Bug Meister, unless you're really certain you know
what you're doing.



@node Checking and verifying issues
@section Checking and verifying issues

After each release (both stable and unstable):

@itemize

@item
Regression test comparison: check the relevant version in
@uref{http://lilypond.org/test/}.

@item
Issues to verify:
@uref{http://code.google.com/p/lilypond/issues/list?can=7}.

@end itemize

Once every year or so:

@itemize

@item
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 twice a year or so (compare the images to the text
description).

@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
same (broken) output as the initial report, then simply post a
"Problem still exists in 2.x.y" message to the issue.

@end itemize


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

The best overview of our current status is given by the grid view:

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

Also of interest might be the issues hindering future 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

Finally, 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.

@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

@node Finding the cause of a regression
@section Finding the cause of a regression

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; 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.


