1 @c -*- coding: utf-8; mode: texinfo; -*-
5 This chapter deals with defects, feature requests, and
6 miscellaneous development tasks.
9 * Introduction to issues and the Bug Squad::
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 and the Bug Squad
19 @section Introduction to issues and the Bug Squad
21 @warning{Unless otherwise specified, all the tasks in this chapter
22 are @qq{simple} tasks: they can be done by a normal user with
23 nothing more than a web browser, email, and lilypond.}
25 @qq{Issues} isn't just a politically-correct term for @qq{bug}.
26 We use the same tracker for feature requests and code TODOs, so
27 the term @qq{bug} wouldn't be accurate. Despite the difference
28 between @qq{issue} and @qq{bug}, we call our team of contributors
29 who organize issues the @emph{Bug Squad}.
31 The Bug Squad is mainly composed of non-programmers -- their job
32 is to @emph{organize} issues, not solve them. Their duties
33 include removing false bug reports, ensuring that any real bug
34 report contains enough information for developers, and checking
35 that a developer's fix actually resolves the problem.
37 Every email to the bug list should be handled within @strong{24
38 hours} in one of four ways:
43 If the behaviour is expected, the user should be told to read the
44 documentation, or asked to clarify how he misread the docs and how
45 the docs could be improved.
48 If the issue already exists in the tracker, send an email to that
52 Ask the user for more information, such as lilypond version number
53 (if not given) and operating system (if this is a suspected cause
57 Accept the report as described in
58 @ref{Adding issues to the tracker}.
63 @node Issue classification
64 @section Issue classification
66 The classification of what counts as a bug vs. feature request,
67 and the priorities assigned to bugs, are a matter of concern
68 @strong{for developers only}. The Bug Squad should classify
69 issues according to the guidelines given by developers.
71 Every issue should have a Status, Type, and Priority; the other
74 @subheading Status (mandatory)
81 New: the item was added by a non-member, despite numerous warnings
82 not to do this. Should be reviewed by a member of the Bug Squad.
85 Accepted: the Bug Squad added it, or reviewed the item.
88 Started: a contributor is working on a fix. Owner should change
89 to be this contributor.
99 Invalid: issue should not have been added in the current state.
102 Duplicate: issue already exists in the tracker.
105 Fixed: a contributor claims to have fixed the bug. The Bug
106 Squad should check the fix with the next official binary release
107 (not by compiling the source from git). Owner should be set to
111 Verified: Bug Squad has confirmed that the issue is closed.
116 @subheading Owner (optional)
118 Newly-added issues should have @emph{no owner}. When a
119 contributor indicates that he has Started or Fixed an item, he
120 should become the owner.
123 @subheading Type (mandatory)
125 The issue's Type should be the first relevant item in this list.
130 Type-Collision: overlapping notation.
133 Type-Defect: a problem in the core program. (the @code{lilypond}
134 binary, scm files, fonts, etc).
137 Type-Documentation: inaccurate, missing, confusing, or desired
138 additional info. Must be fixable by editing a texinfo, ly, or scm
142 Type-Build: problem or desired features in the build system. This
143 includes the makefiles, stepmake, python scripts, and GUB.
146 Type-Scripts: problem or desired feature in the non-build-system
147 scripts. Mostly used for convert-ly, lilypond-book, etc.
150 Type-Enhancement: a feature request for the core program. The
151 distinction between enhancement and defect isn't extremely clear;
152 when in doubt, mark it as enhancement.
155 Type-Other: anything else.
160 @subheading Priority (mandatory)
162 Currently, only Critical items will block a stable release.
167 Priority-Critical: lilypond segfaults, or a regression occurred
168 within the last two stable versions. (i.e. when developing 2.13,
169 any regression against 2.12 or 2.10 counts)
172 Priority-High: highly embarrassing items, and any regression
173 against a version earlier than two stable versions (i.e. when
174 developing 2.13, any regression against 2.8 or earlier). This
175 level is also used for issues which produce no output and fail to
176 give the user a clue about what's wrong.
179 Priority-Medium: normal priority.
182 Priority-Low: less important than normal.
185 Priority-Postponed: no fix planned. Generally used for things
186 like Ancient notation, which nobody wants to touch.
190 The difference between Priority-Medium and Priority-Low is not
191 well-defined, both in this policy and in practice. The only
192 answer we can give at the moment is @qq{look at existing items in
193 of the same type, and try to guess whether the priority is closer
194 to the Medium items or Low items}. We're aware of the ambiguity,
195 and won't complain if somebody picks a @q{wrong} value for
199 @subheading Opsys (optional)
201 Issues that only affect specific operating systems.
204 @subheading Other items (optional)
211 Regression: it used to @strong{deliberately} work in an earlier
212 stable release. If the earlier output was accidental (i.e. we
213 didn't try to stop a collision, but it just so happened that two
214 grobs didn't collide), then breaking it does not count as a
218 Patch: a patch to fix an issue is attached.
221 Frog: the fix is believed to be suitable for a new contributor
222 (does not require a great deal of knowledge about LilyPond). The
223 issue should also have an estimated time in a comment.
226 Maintainability: hinders developent of LilyPond. For example,
227 improvements to the build system, or @qq{helper} python scripts.
230 Bounty: somebody is willing to pay for the fix.
233 Warning: graphical output is fine, but lilypond prints a
234 false/misleading warning message. Alternately, a warning should
235 be printed (such as a bar line error), but was not. Also applies
236 to warnings when compiling the source code or generating
240 Security: might potentially be used.
243 Performance: might potentially be used.
247 If you particularly want to add an label not in the list, go
248 ahead, but this is not recommended.
251 @node Adding issues to the tracker
252 @section Adding issues to the tracker
254 @warning{This should only be done by the Bug Squad or experienced
255 developers. Normal users should not do this; instead, they should
256 follow the guidelines for @rweb{Bug reports}.}
258 In order to assign labels to issues, Bug Squad members should log
259 in to their google account before adding an item.
261 @subsubheading Normal issues
266 Check if the issue already exists in the tracker.
269 If the initial bug report contains lilypond examples which do not
270 follow the guidelines in @rweb{Tiny examples}, either ask the
271 reporter to create such an example, or make one yourself.
273 If you are willing to spend the effort, we would prefer it if the
274 Bug Squad member created a tiny example themselves instead of
275 asking the user to do so.
278 Add the issue and classify it according to the guidelines in
279 @ref{Issue classification}. In particular, the item should have
280 @code{Status}, @code{Type-}, and @code{Priority-} labels.
283 After adding the issue, please send a response email to the same
284 group(s) that the initial patch was sent to. If the initial email
285 was sent to multiple mailing lists (such as both @code{user} and
286 @code{bugs}), then reply to all those mailing lists as well. The
287 email should contain a link to the issue you just added.
292 @subsubheading Patch reminders
294 There is a special category of issues: reminders of an existing
295 patch. These should be added if a patch has been sent to a
296 lilypond mailing list (generally @code{lilypond-devel}, but they
297 sometimes appear on @code{bug-lilypond} as well) and has had no
298 discussion for at least @strong{3 days}. Do not add issues for
299 patches under active discussion.
301 Before adding a patch-reminder issue, do a quick check to see if
302 it was pushed without sending any email. This can be checked for
303 searching for relevant terms (from the patch subject or commit
304 message) on the webgit page:
307 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
310 After adding the issue, please send a response email to the same
311 group(s) that the initial patch was sent to. If the initial email
312 was sent to multiple mailing lists (such as both @code{bugs} and
313 @code{devel}), then reply to all those mailing lists as well. The
314 email should contain a link to the issue you just added.
317 @node Checking and verifying issues
318 @section Checking and verifying issues
320 After each release (both stable and unstable):
325 Regression test comparison: check the relevant version in
326 @uref{http://lilypond.org/test/}.
330 @uref{http://code.google.com/p/lilypond/issues/list?can=7}.
334 Once every two weeks or so:
339 Check for any incorrectly-classified items in the tracker. This
340 generally just means looking at the grid to see any items without
344 Check for any items with @code{label:patch}. If it's been more
345 than a week since the last action on the issue, send an email to
346 -devel to remind them about it. If the patch was withdrawn for
347 more work, then remove the @code{patch} label.
350 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch}
355 Once every year or two: (yes, these are large tasks; gathering
356 more volunteers to help is definitely recommended)
361 Checking all regtests: although we have a system for checking the
362 regtests between two versions, occasionally a bug will slip
363 through the cracks. It is therefore good to manually examine all
364 the regtests (compare the images to the text description).
367 Checking all issues: we try to mark each Issue @q{fixed} when we
368 fix it, but occasionally one or two issues will slip through the
369 cracks. It is therefore good to check all Issues. If you see the
370 same (broken) output as the initial report, then simply post a
371 @qq{Problem still exists in 2.x.y} message to the issue.
376 @node Summary of project status
377 @section Summary of project status
379 The best overview of our current status is given by the grid view:
382 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}
385 Also of interest might be the issues hindering future development:
388 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability&mode=grid&y=Priority&x=Type&cells=ids}
391 Finally, issues tagged with @code{Frog} indicates a task suitable
392 for a relatively new contributor. The time given is a quick
393 (inaccurate) estimate of the time required for somebody who is
394 familiar with material in this manual, but does not know anything
395 else about LilyPond development.
398 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog&mode=grid&y=Priority&x=Type&cells=ids}
402 @node Finding the cause of a regression
403 @section Finding the cause of a regression
405 @warning{This is not a @qq{simple} task; it requires a fair amount
406 of technical knowledge.}
408 Git has special functionality to help tracking down the exact
409 commit which causes a problem. See the git manual page for
410 @code{git bisect}. This is a job that non-programmers can do,
411 although it requires familiarity with git, ability to compile
412 LilyPond, and generally a fair amount of technical knowledge. An
413 in-depth explanation of this process will not be given here.
415 Even if you are not familiar with git or are not able to compile
416 LilyPond you can still help to narrow down the cause of a
417 regression simply by downloading the binary releases of different
418 LilyPond versions and testing them for the regression. Knowing
419 which version of LilyPond first exhibited the regression is
420 helpful to a developer as it shortens the @code{git bisect}
421 procedure described above.
423 Once a problematic commit is identified, the programmers' job is
424 much easier. In fact, for most regression bugs, the majority of
425 the time is spent simply finding the problematic commit.