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 should
28 classify issues according to the guidelines given by developers.
30 @warning{Unless otherwise specified, all the tasks in this chapter
31 are @qq{simple} tasks: they can be done by a normal user with
32 nothing more than a web browser, email, and lilypond.}
35 @node Issue classification
36 @section Issue classification
38 Every issue should have a Status and Type; the other fields are
48 New: the item was added by a non-member, despite numerous warnings
49 not to do this. Should be reviewed by a member of the Bug Squad.
52 Accepted: the Bug Squad added it, or reviewed the item.
55 Started: a contributor is working on a fix. Owner should change
56 to be this contributor.
66 Invalid: issue should not have been added in the current state.
69 Duplicate: issue already exists in the tracker.
72 Fixed: a contributor claims to have fixed the bug. The Bug
73 Squad should check the fix with the next official binary release
74 (not by compiling the source from git). Owner should be set to
78 Verified: Bug Squad has confirmed that the issue is closed.
85 Newly-added issues should have @emph{no owner}. When a
86 contributor indicates that he has Started or Fixed an item, he
87 should become the owner.
93 The issue's Type should be the first relevant item in this list.
98 Type-Collision: overlapping notation.
101 Type-Defect: a problem in the core program. (the @code{lilypond}
102 binary, scm files, fonts, etc).
105 Type-Documentation: inaccurate, missing, confusing, or desired
106 additional info. Must be fixable by editing a texinfo, ly, or scm
110 Type-Build: problem or desired features in the build system. This
111 includes the makefiles, stepmake, python scripts, and GUB.
114 Type-Scripts: problem or desired feature in the non-build-system
115 scripts. Mostly used for convert-ly, lilypond-book, etc.
118 Type-Enhancement: a feature request for the core program. The
119 distinction between enhancement and defect isn't extremely clear;
120 when in doubt, mark it as enhancement.
123 Type-Other: anything else.
130 Currently, only Critical items will block a stable release.
135 Priority-Critical: lilypond segfaults, or a regression occurred
136 within the last two stable versions. (i.e. when developing 2.13,
137 any regression against 2.12 or 2.10 counts)
140 Priority-High: highly embarrassing items, and any regression
141 against a version earlier than two stable versions (i.e. when
142 developing 2.13, any regression against 2.8 or earlier). This
143 level is also used for issues which produce no output and fail to
144 give the user a clue about what's wrong.
147 Priority-Medium: normal priority.
150 Priority-Low: less important than normal.
153 Priority-Postponed: no fix planned. Generally used for things
154 like Ancient notation, which nobody wants to touch.
158 The difference between Priority-Medium and Priority-Low is not
159 well-defined, both in this policy and in practice. The only
160 answer we can give at the moment is @qq{look at existing items in
161 of the same type, and try to guess whether the priority is closer
162 to the Medium items or Low items}. We're aware of the ambiguity,
163 and won't complain if somebody picks a @q{wrong} value for
169 Issues that only affect specific operating systems.
172 @subheading Other items
179 Regression: it used to @strong{deliberately} work in an earlier
180 stable release. If the earlier output was accidental (i.e. we
181 didn't try to stop a collision, but it just so happened that two
182 grobs didn't collide), then breaking it does not count as a
186 Patch: a patch to fix an issue is attached.
189 Frog: the fix is believed to be suitable for a new contributor
190 (does not require a great deal of knowledge about LilyPond). The
191 issue should also have an estimated time in a comment.
194 Maintainability: hinders developent of LilyPond. For example,
195 improvements to the build system, or @qq{helper} python scripts.
198 Bounty: somebody is willing to pay for the fix.
201 Warning: graphical output is fine, but lilypond prints a
202 false/misleading warning message. Alternately, a warning should
203 be printed (such as a bar line error), but was not. Also applies
204 to warnings when compiling the source code or generating
208 Security: might potentially be used.
211 Performance: might potentially be used.
215 If you particularly want to add an label not in the list, go
216 ahead, but this is not recommended.
219 @node Adding issues to the tracker
220 @section Adding issues to the tracker
222 @warning{This should only be done by the Bug Squad or experienced
223 developers. Normal users should not do this; instead, they should
224 follow the guidelines for @rweb{Bug reports}.}
226 In order to assign labels to issues, Bug Squad members should log
227 in to their google account before adding an item.
229 @subsubheading Normal issues
234 Check if the issue already exists in the tracker.
237 If the initial bug report contains lilypond examples which do not
238 follow the guidelines in @rweb{Tiny examples}, either ask the
239 reporter to create such an example, or make one yourself.
241 If you are willing to spend the effort, we would prefer it if the
242 Bug Squad member created a tiny example themselves instead of
243 asking the user to do so.
246 Add the issue and classify it according to the guidelines in
247 @ref{Issue classification}. In particular, the item should have a
248 @code{Status}, @code{Type-}, and @code{Priority-}.
251 After adding the issue, please send a response email to the same
252 group(s) that the initial patch was sent to. If the initial email
253 was sent to multiple mailing lists (such as both @code{user} and
254 @code{bugs}), then reply to all those mailing lists as well. The
255 email should contain a link to the issue you just added.
260 @subsubheading Patch reminders
262 There is a special category of issues: reminders of an existing
263 patch. These should be added if a patch has been sent to a
264 lilypond mailing list (generally @code{lilypond-devel}, but they
265 sometimes appear on @code{bug-lilypond} as well) and has had no
266 discussion for at least @strong{3 days}. Do not add issues for
267 patches under active discussion.
269 Before adding a patch-reminder issue, do a quick check to see if
270 it was pushed without sending any email. This can be checked for
271 searching for relevant terms (from the patch subject or commit
272 message) on the webgit page:
275 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
278 After adding the issue, please send a response email to the same
279 group(s) that the initial patch was sent to. If the initial email
280 was sent to multiple mailing lists (such as both @code{bugs} and
281 @code{devel}), then reply to all those mailing lists as well. The
282 email should contain a link to the issue you just added.
285 @node Checking and verifying issues
286 @section Checking and verifying issues
288 After each release (both stable and unstable):
293 Regression test comparison: check the relevant version in
294 @uref{http://lilypond.org/test/}.
298 @uref{http://code.google.com/p/lilypond/issues/list?can=7}.
302 Once every two weeks or so:
307 Check for any incorrectly-classified items in the tracker. This
308 generally just means looking at the grid to see any items without
312 Check for any items with @code{label:patch}. If it's been more
313 than a week since the last action on the issue, send an email to
314 -devel to remind them about it. If the patch was withdrawn for
315 more work, then remove the @code{patch} label.
318 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch}
323 Once every year or two: (yes, these are large tasks; gathering
324 more volunteers to help is definitely recommended)
329 Checking all regtests: although we have a system for checking the
330 regtests between two versions, occasionally a bug will slip
331 through the cracks. It is therefore good to manually examine all
332 the regtests (compare the images to the text description).
335 Checking all issues: we try to mark each Issue @q{fixed} when we
336 fix it, but occasionally one or two issues will slip through the
337 cracks. It is therefore good to check all Issues. If you see the
338 same (broken) output as the initial report, then simply post a
339 @qq{Problem still exists in 2.x.y} message to the issue.
344 @node Summary of project status
345 @section Summary of project status
347 The best overview of our current status is given by the grid view:
350 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}
353 Also of interest might be the issues hindering future development:
356 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability&mode=grid&y=Priority&x=Type&cells=ids}
359 Finally, issues tagged with @code{Frog} indicates a task suitable
360 for a relatively new contributor. The time given is a quick
361 (inaccurate) estimate of the time required for somebody who is
362 familiar with material in this manual, but does not know anything
363 else about LilyPond development.
366 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog&mode=grid&y=Priority&x=Type&cells=ids}
370 @node Finding the cause of a regression
371 @section Finding the cause of a regression
373 @warning{This is not a @qq{simple} task; it requires a fair amount
374 of technical knowledge.}
376 Git has special functionality to help tracking down the exact
377 commit which causes a problem. See the git manual page for
378 @code{git bisect}. This is a job that non-programmers can do,
379 although it requires familiarity with git, ability to compile
380 LilyPond, and generally a fair amount of technical knowledge.
382 Even if you are not familiar with git or are not able to compile
383 LilyPond you can still help to narrow down the cause of a
384 regression simply by downloading the binary releases of different
385 LilyPond versions and testing them for the regression. Knowing
386 which version of LilyPond first exhibited the regression is
387 helpful to a developer as it shortens the @code{git bisect}
388 procedure described above.
390 Once a problematic commit is identified, the programmers' job is
391 much easier. In fact, for most regression bugs, the majority of
392 the time is spent simply finding the problematic commit.