@c -*- coding: utf-8; 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 @subheading Status Open issues: @itemize @item New: the item was added by a non-member, despite numerous warnings not to do this. Should be reviewed by the Bug Meister. @item Accepted: the Bug Meister added it, or reviewed the item. @item Started: a contributor is working on a fix. Owner should change to be this contributor. @end itemize Closed issues: @itemize @item Invalid: issue should not have been added in the current state. @item Duplicate: issue already exists in the tracker. @item Fixed: a contributor claims to have fixed the bug. The Bug Meister should check the fix with the next official binary release (not by compiling the source from git). Owner should be set to that contributor. @item Verified: Bug Meister has confirmed that the issue is closed. @end itemize @subheading Owner Newly-added issues should have @emph{no owner}. When a contributor indicates that he has Started or Fixed an item, he should become the owner. @subheading Type The issue's Type should be the first relevant item in this list. @itemize @item Type-Collision: overlapping notation. @item Type-Defect: a problem in the core program. (the @code{lilypond} binary, scm files, fonts, etc). @item Type-Documentation: inaccurate, missing, confusing, or desired additional info. Must be fixable by editing a texinfo, ly, or scm file. @item Type-Build: problem or desired features in the build system. This 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-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-Other: anything else. @end itemize @subheading Priority Currently, only Critical items will block a stable release. @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) @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) @item Priority-Medium: normal priority. @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 @subheading Opsys Issues that only affect specific operating systems. @subheading Other items Other labels: @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. @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 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 Warning: graphical output is fine, but lilypond prints a false/misleading warning message. Alternately, a warning should be printed (such as a bar line error), but was not. Also applies to warnings when compiling the source code or generating documentation. @item Security: might potentially be used. @item Performance: might potentially be used. @end itemize @node Adding issues to the tracker @section Adding issues to the tracker This should only be done by the Bug Meister(s), or experienced developers. Normal users should not do this; instead, they should follow the guidelines for @rweb{Bug reports}. @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 (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.