1 @c -*- coding: utf-8; 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}. The Bug Squad will classify
28 issues according to the guidelines given by developers.
30 If you are curious about the classification, read on, but please
31 don't complain that your particular issue should have higher
32 priority or counts as a bug rather than a feature request.
35 @node Issue classification
36 @section Issue classification
46 New: the item was added by a non-member, despite numerous warnings
47 not to do this. Should be reviewed by a member of the Bug Squad.
50 Accepted: the Bug Squad added it, or reviewed the item.
53 Started: a contributor is working on a fix. Owner should change
54 to be this contributor.
64 Invalid: issue should not have been added in the current state.
67 Duplicate: issue already exists in the tracker.
70 Fixed: a contributor claims to have fixed the bug. The Bug
71 Squad should check the fix with the next official binary release
72 (not by compiling the source from git). Owner should be set to
76 Verified: Bug Squad has confirmed that the issue is closed.
83 Newly-added issues should have @emph{no owner}. When a
84 contributor indicates that he has Started or Fixed an item, he
85 should become the owner.
91 The issue's Type should be the first relevant item in this list.
96 Type-Collision: overlapping notation.
99 Type-Defect: a problem in the core program. (the @code{lilypond}
100 binary, scm files, fonts, etc).
103 Type-Documentation: inaccurate, missing, confusing, or desired
104 additional info. Must be fixable by editing a texinfo, ly, or scm
108 Type-Build: problem or desired features in the build system. This
109 includes the makefiles, stepmake, python scripts, and GUB.
112 Type-Scripts: problem or desired feature in the non-build-system
113 scripts. Mostly used for convert-ly, lilypond-book, etc.
116 Type-Enhancement: a feature request for the core program. The
117 distinction between enhancement and defect isn't extremely clear;
118 when in doubt, mark it as enhancement.
121 Type-Other: anything else.
128 Currently, only Critical items will block a stable release.
133 Priority-Critical: lilypond segfaults, or a regression occurred
134 within the last two stable versions. (i.e. when developing 2.13,
135 any regression against 2.12 or 2.10 counts)
138 Priority-High: highly embarrassing items, and any regression
139 against a version earlier than two stable versions (i.e. when
140 developing 2.13, any regression against 2.8 or earlier). This
141 level is also used for issues which produce no output and fail to
142 give the user a clue about what's wrong.
145 Priority-Medium: normal priority.
148 Priority-Low: less important than normal.
151 Priority-Postponed: no fix planned. Generally used for things
152 like Ancient notation, which nobody wants to touch.
156 The difference between Priority-Medium and Priority-Low is not
157 well-defined, both in this policy and in practice. The only
158 answer we can give at the moment is @qq{look at existing items in
159 of the same type, and try to guess whether the priority is closer
160 to the Medium items or Low items}. We're aware of the ambiguity,
161 and won't complain if somebody picks a @q{wrong} value for
167 Issues that only affect specific operating systems.
170 @subheading Other items
177 Regression: it used to @strong{deliberately} work in an earlier
178 stable release. If the earlier output was accidental (i.e. we
179 didn't try to stop a collision, but it just so happened that two
180 grobs didn't collide), then breaking it does not count as a
184 Patch: a patch to fix an issue is attached.
187 Frog: the fix is believed to be suitable for a new contributor
188 (does not require a great deal of knowledge about LilyPond). The
189 issue should also have an estimated time in a comment.
192 Maintainability: hinders developent of LilyPond. For example,
193 improvements to the build system, or @qq{helper} python scripts.
196 Bounty: somebody is willing to pay for the fix.
199 Warning: graphical output is fine, but lilypond prints a
200 false/misleading warning message. Alternately, a warning should
201 be printed (such as a bar line error), but was not. Also applies
202 to warnings when compiling the source code or generating
206 Security: might potentially be used.
209 Performance: might potentially be used.
214 @node Adding issues to the tracker
215 @section Adding issues to the tracker
217 This should only be done by the Bug Squad or experienced
218 developers. Normal users should not do this; instead, they should
219 follow the guidelines for @rweb{Bug reports}.
222 @node Checking and verifying issues
223 @section Checking and verifying issues
225 After each release (both stable and unstable):
230 Regression test comparison: check the relevant version in
231 @uref{http://lilypond.org/test/}.
235 @uref{http://code.google.com/p/lilypond/issues/list?can=7}.
239 Once every two weeks or so:
244 Check for any items with @code{label:patch}. If it's been more
245 than a week since the last action on the issue, send an email to
246 -devel to remind them about it. If the patch was withdrawn for
247 more work, then remove the @code{patch} label.
250 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch}
255 Once every year or so:
260 Checking all regtests: although we have a system for checking the
261 regtests between two versions, occasionally a bug will slip
262 through the cracks. It is therefore good to manually examine all
263 the regtests (compare the images to the text description).
266 Checking all issues: we try to mark each Issue @q{fixed} when we
267 fix it, but occasionally one or two issues will slip through the
268 cracks. It is therefore good to check all Issues. If you see the
269 same (broken) output as the initial report, then simply post a
270 "Problem still exists in 2.x.y" message to the issue.
275 @node Summary of project status
276 @section Summary of project status
278 The best overview of our current status is given by the grid view:
281 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}
284 Also of interest might be the issues hindering future development:
287 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability&mode=grid&y=Priority&x=Type&cells=ids}
290 Finally, issues tagged with @code{Frog} indicates a task suitable
291 for a relatively new contributor. The time given is a quick
292 (inaccurate) estimate of the time required for somebody who is
293 familiar with material in this manual, but does not know anything
294 else about LilyPond development.
297 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog&mode=grid&y=Priority&x=Type&cells=ids}
300 @node Finding the cause of a regression
301 @section Finding the cause of a regression
303 Git has special functionality to help tracking down the exact
304 commit which causes a problem. See the git manual page for
305 @code{git bisect}. This is a job that non-programmers can do,
306 although it requires familiarity with git, ability to compile
307 LilyPond, and generally a fair amount of technical knowledge.
309 Even if you are not familiar with git or are not able to compile
310 LilyPond you can still help to narrow down the cause of a regression
311 simply by downloading the binary releases of different LilyPond
312 versions and testing them for the regression. Knowing which version
313 of LilyPond first exhibited the regression is helpful to a developer
314 as it shortens the @code{git bisect} procedure described above.
316 Once a problematic commit is identified, the programmers' job is
317 much easier. In fact, for most regression bugs, the majority of
318 the time is spent simply finding the problematic commit.