1 @c -*- coding: us-ascii; mode: texinfo; -*-
5 This chapter deals with defects, feature requests, and
6 miscellaneous development tasks.
9 * Introduction to issues::
10 * Issue classification::
11 * Adding issues to the tracker::
12 * Checking and verifying issues::
13 * Summary of project status::
14 * Finding the cause of a regression::
18 @node Introduction to issues
19 @section Introduction to issues
21 First, @qq{issue} isn't just a politically-correct term for
22 @qq{bug}. We use the same tracker for feature requests and code
23 TODOs, so the term @qq{bug} wouldn't be accurate.
25 Second, the classification of what counts as a bug vs. feature
26 request, and the priorities assigned to bugs, are a matter of
27 concern @strong{for developers only}. If you are curious about
28 the classification, read on, but don't complain that your
29 particular issue is higher priority or counts as a bug rather than
33 @node Issue classification
34 @section Issue classification
44 New: the item was added by a non-member, despite numerous warnings
45 not to do this. Should be reviewed by the Bug Meister.
48 Accepted: the Bug Meister added it, or reviewed the item.
51 Started: a contributor is working on a fix. Owner should change
52 to be this contributor.
62 Invalid: issue should not have been added in the current state.
65 Duplicate: issue already exists in the tracker.
68 Fixed: a contributor claims to have fixed the bug. The Bug
69 Meister should check the fix with the next official binary release
70 (not by compiling the source from git). Owner should be set to
74 Verified: Bug Meister has confirmed that the issue is closed.
81 Newly-added issues should have @emph{no owner}. When a
82 contributor indicates that he has Started or Fixed an item, he
83 should become the owner.
89 The issue's Type should be the first relevant item in this list.
94 Type-Collision: overlapping notation.
97 Type-Defect: a problem in the core program. (the @code{lilypond}
98 binary, scm files, fonts, etc).
101 Type-Documentation: inaccurate, missing, confusing, or desired
102 additional info. Must be fixable by editing a texinfo, ly, or scm
106 Type-Build: problem or desired features in the build system. This
107 includes the makefiles, stepmake, python scripts, and GUB.
110 Type-Scripts: problem or desired feature in the non-build-system
111 scripts. Mostly used for convert-ly, lilypond-book, etc.
114 Type-Enhancement: a feature request for the core program. The
115 distinction between enhancement and defect isn't extremely clear;
116 when in doubt, mark it as enhancement.
119 Type-Other: anything else.
126 Currently, only Critical items will block a stable release.
131 Priority-Critical: lilypond segfaults, or a regression occurred
132 within the last two stable versions. (i.e. when developing 2.13,
133 any regression against 2.12 or 2.10 counts)
136 Priority-High: highly embarrassing items, and any regression
137 against a version earlier than two stable versions. (i.e. when
138 developing 2.13, any regression against 2.8 or earlier)
141 Priority-Medium: normal priority.
144 Priority-Low: less important than normal.
147 Priority-Postponed: no fix planned. Generally used for things
148 like Ancient notation, which nobody wants to touch.
155 Issues that only affect specific operating systems.
158 @subheading Other items
165 Regression: it used to @strong{deliberately} work in an earlier
166 stable release. If the earlier output was accidental (i.e. we
167 didn't try to stop a collision, but it just so happened that two
168 grobs didn't collide), then breaking it does not count as a
172 Patch: a patch to fix an issue is attached.
175 Frog: the fix is believed to be suitable for a new contributor
176 (does not require a great deal of knowledge about LilyPond). The
177 issue should also have an estimated time in a comment.
180 Maintainability: hinders developent of LilyPond. For example,
181 improvements to the build system, or @qq{helper} python scripts.
184 Bounty: somebody is willing to pay for the fix.
187 Warning: graphical output is fine, but lilypond prints a
188 false/misleading warning message. Alternately, a warning should
189 be printed (such as a bar line error), but was not. Also applies
190 to warnings when compiling the source code or generating
194 Security: might potentially be used.
197 Performance: might potentially be used.
202 @node Adding issues to the tracker
203 @section Adding issues to the tracker
205 This should only be done by the Bug Meister(s), or experienced
206 developers. Normal users should not do this; instead, they should
207 follow the guidelines for @rweb{Bug reports}.
210 @node Checking and verifying issues
211 @section Checking and verifying issues
213 After each release (both stable and unstable):
218 Regression test comparison: check the relevant version in
219 @uref{http://lilypond.org/test/}.
223 @uref{http://code.google.com/p/lilypond/issues/list?can=7}.
227 Once every year or so:
232 Checking all regtests: although we have a system for checking the
233 regtests between two versions, occasionally a bug will slip
234 through the cracks. It is therefore good to manually examine all
235 the regtests (compare the images to the text description).
238 Checking all issues: we try to mark each Issue @q{fixed} when we
239 fix it, but occasionally one or two issues will slip through the
240 cracks. It is therefore good to check all Issues. If you see the
241 same (broken) output as the initial report, then simply post a
242 "Problem still exists in 2.x.y" message to the issue.
247 @node Summary of project status
248 @section Summary of project status
250 The best overview of our current status is given by the grid view:
253 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}
256 Also of interest might be the issues hindering future development:
259 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability&mode=grid&y=Priority&x=Type&cells=ids}
262 Finally, issues tagged with @code{Frog} indicates a task suitable
263 for a relatively new contributor. The time given is a quick
264 (inaccurate) estimate of the time required for somebody who is
265 familiar with material in this manual, but does not know anything
266 else about LilyPond development.
269 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog&mode=grid&y=Priority&x=Type&cells=ids}
272 @node Finding the cause of a regression
273 @section Finding the cause of a regression
275 Git has special functionality to help tracking down the exact
276 commit which causes a problem. See the git manual page for
279 This is a job that non-programmers can do; once a problematic
280 commit is identified, the programmers' job is much easier. In
281 fact, for most regression bugs, the majority of the time is spent
282 simply finding the problematic commit.