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 * Bug Squad checklists::
11 * Issue classification::
12 * Adding issues to the tracker::
13 * Summary of project status::
14 * Finding the cause of a regression::
18 @node Introduction to issues
19 @section Introduction to issues
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.
38 @node Bug Squad checklists
39 @section Bug Squad checklists
41 We highly recommend that you configure your email client to put
49 into a separate folder than emails to @code{bug-lilypond}.
52 @subsubheading New emails to @code{bug-lilypond}
54 Every new email to @code{bug-lilypond} should be handled within
55 @strong{24 hours} in the first method which is applicable:
60 If the email is a question about how to use LilyPond, direct them
61 politely to @code{lilypond-user}.
64 If a bug report is not in the form of a Tiny example, direct the
65 user to resubmit the report after reading @rweb{Tiny examples}.
68 If the behavior is expected, the user should be told to read the
69 documentation, or asked to clarify how he misread the docs and how
70 the docs could be improved.
73 If the issue already exists in the tracker, send an email to that
77 Ask the user for more information, such as lilypond version number
78 (if not given) and operating system (if this is a suspected cause
82 Accept the report as described in
83 @ref{Adding issues to the tracker}.
88 @subheading Updates / discussion about issues
90 We try to keep discussions about issues on the tracker, but
91 sometimes it spills over onto email. If discussion has ended with
92 no patch / resolution and at least @strong{3 days} have passed,
98 Summarize the recent discussion on the tracker, and add a link to
99 the original discussion.
102 Add the comment @qq{there was some technical discussion which I
103 could not understand}, and include a link to the original
106 We do not expect Bug Squad members to be programmers, or even to
107 be moderately-skilled users. Your job is to keep track of issue
108 reports; it is @emph{perfectly acceptable} to not understand
109 discussions between advanced users and/or developers.
114 @subheading Regular maintenance
116 After @strong{every release} (both stable and unstable):
121 Regression test comparison: if anything has changed suspiciously,
122 ask if it was deliberate. The official comparison is online, at:
125 @uref{http://lilypond.org/test/}
129 Issues to verify: try to reproduce the bug with the latest
130 version; if you cannot reproduce the bug, mark the item
131 @qq{Verified} (i.e. @qq{the fix has been verified to work}).
134 @uref{http://code.google.com/p/lilypond/issues/list?can=7}
139 Once every @strong{two weeks} or so:
144 Check for any incorrectly-classified items in the tracker. This
145 generally just means looking at the grid to see any items without
149 Check for any items with @code{label:patch}. If it's been more
150 than a week since the last action on the issue, send an email to
151 -devel to remind them about it. If the patch was withdrawn for
152 more work, then remove the @code{patch} label.
155 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch}
160 @subheading Irregular maintenance
162 @warning{These tasks are a lot of work; gathering more volunteers
163 to help is definitely recommended. However, the Bug Squad should
164 handle the organization and training of new volunteers.}
166 Once every year or two:
171 Checking all regtests: although we have a system for checking the
172 regtests between two versions, occasionally a bug will slip
173 through the cracks. It is therefore good to manually examine all
174 the regtests (compare the images to the text description).
177 Checking all issues: we try to mark each Issue @q{fixed} when we
178 fix it, but occasionally one or two issues will slip through the
179 cracks. It is therefore good to check all Issues. If you see the
180 same (broken) output as the initial report, then simply post a
181 @qq{Problem still exists in 2.x.y} message to the issue.
186 @node Issue classification
187 @section Issue classification
189 The Bug Squad should classify issues according to the guidelines
190 given by developers. Every issue should have a Status, Type, and
191 Priority; the other fields are optional.
193 @subheading Status (mandatory)
200 New: the item was added by a non-member, despite numerous warnings
201 not to do this. Should be reviewed by a member of the Bug Squad.
204 Accepted: the Bug Squad added it, or reviewed the item.
207 Started: a contributor is working on a fix. Owner should change
208 to be this contributor.
218 Invalid: issue should not have been added in the current state.
221 Duplicate: issue already exists in the tracker.
224 Fixed: a contributor claims to have fixed the bug. The Bug
225 Squad should check the fix with the next official binary release
226 (not by compiling the source from git). Owner should be set to
230 Verified: Bug Squad has confirmed that the issue is closed.
235 @subheading Owner (optional)
237 Newly-added issues should have @emph{no owner}. When a
238 contributor indicates that he has Started or Fixed an item, he
239 should become the owner.
242 @subheading Type (mandatory)
244 The issue's Type should be the first relevant item in this list.
249 Type-Collision: overlapping notation.
252 Type-Defect: a problem in the core program. (the @code{lilypond}
253 binary, scm files, fonts, etc).
256 Type-Documentation: inaccurate, missing, confusing, or desired
257 additional info. Must be fixable by editing a texinfo, ly, or scm
261 Type-Build: problem or desired features in the build system. This
262 includes the makefiles, stepmake, python scripts, and GUB.
265 Type-Scripts: problem or desired feature in the non-build-system
266 scripts. Mostly used for convert-ly, lilypond-book, etc.
268 Type-Enhancement: a feature request for the core program. The
269 distinction between enhancement and defect isn't extremely clear;
270 when in doubt, mark it as enhancement.
273 Type-Other: anything else.
278 @subheading Priority (mandatory)
280 Currently, only Critical items will block a stable release.
285 Priority-Critical: lilypond segfaults, or a regression occurred
286 within the last two stable versions. (i.e. when developing 2.13,
287 any regression against 2.12 or 2.10 counts)
290 Priority-High: highly embarrassing items, and any regression
291 against a version earlier than two stable versions (i.e. when
292 developing 2.13, any regression against 2.8 or earlier). This
293 level is also used for issues which produce no output and fail to
294 give the user a clue about what's wrong.
297 Priority-Medium: normal priority.
300 Priority-Low: less important than normal.
303 Priority-Postponed: no fix planned. Generally used for things
304 like Ancient notation, which nobody wants to touch.
308 The difference between Priority-Medium and Priority-Low is not
309 well-defined, both in this policy and in practice. The only
310 answer we can give at the moment is @qq{look at existing items in
311 of the same type, and try to guess whether the priority is closer
312 to the Medium items or Low items}. We're aware of the ambiguity,
313 and won't complain if somebody picks a @q{wrong} value for
317 @subheading Opsys (optional)
319 Issues that only affect specific operating systems.
322 @subheading Other items (optional)
329 Regression: it used to @strong{deliberately} work in an earlier
330 stable release. If the earlier output was accidental (i.e. we
331 didn't try to stop a collision, but it just so happened that two
332 grobs didn't collide), then breaking it does not count as a
336 Patch: a patch to fix an issue is attached.
339 Frog: the fix is believed to be suitable for a new contributor
340 (does not require a great deal of knowledge about LilyPond). The
341 issue should also have an estimated time in a comment.
344 Maintainability: hinders developent of LilyPond. For example,
345 improvements to the build system, or @qq{helper} python scripts.
348 Bounty: somebody is willing to pay for the fix. Only add this tag
349 if somebody has offered an exact figure in US dollars or euros.
352 Warning: graphical output is fine, but lilypond prints a
353 false/misleading warning message. Alternately, a warning should
354 be printed (such as a bar line error), but was not. Also applies
355 to warnings when compiling the source code or generating
359 Security: might potentially be used.
362 Performance: might potentially be used.
366 If you particularly want to add an label not in the list, go
367 ahead, but this is not recommended.
370 @node Adding issues to the tracker
371 @section Adding issues to the tracker
373 @warning{This should only be done by the Bug Squad or experienced
374 developers. Normal users should not do this; instead, they should
375 follow the guidelines for @rweb{Bug reports}.}
377 In order to assign labels to issues, Bug Squad members should log
378 in to their google account before adding an item.
380 @subsubheading Normal issues
385 Check if the issue falls into any previous category given on the
386 relevant checklists in @ref{Bug Squad checklists}. If in doubt,
387 add a new issue for a report. We would prefer to have some
388 incorrectly-added issues rather than lose information that should
392 Add the issue and classify it according to the guidelines in
393 @ref{Issue classification}. In particular, the item should have
394 @code{Status}, @code{Type-}, and @code{Priority-} labels.
397 After adding the issue, please send a response email to the same
398 group(s) that the initial patch was sent to. If the initial email
399 was sent to multiple mailing lists (such as both @code{user} and
400 @code{bugs}), then reply to all those mailing lists as well. The
401 email should contain a link to the issue you just added.
406 @subsubheading Patch reminders
408 @warning{This is not a Bug Squad responsibility; we have a
409 separate person handling this task.}
411 There is a special category of issues: reminders of an existing
412 patch. These should be added if a patch has been sent to a
413 lilypond mailing list (generally @code{lilypond-devel}, but they
414 sometimes appear on @code{bug-lilypond} as well) and has had no
415 discussion for at least @strong{3 days}. Do not add issues for
416 patches under active discussion.
418 Before adding a patch-reminder issue, do a quick check to see if
419 it was pushed without sending any email. This can be checked for
420 searching for relevant terms (from the patch subject or commit
421 message) on the webgit page:
424 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
427 After adding the issue, please send a response email to the same
428 group(s) that the initial patch was sent to. If the initial email
429 was sent to multiple mailing lists (such as both @code{bugs} and
430 @code{devel}), then reply to all those mailing lists as well. The
431 email should contain a link to the issue you just added.
435 @node Summary of project status
436 @section Summary of project status
438 The best overview of our current status is given by the grid view:
441 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}
444 Also of interest might be the issues hindering future development:
447 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability&mode=grid&y=Priority&x=Type&cells=ids}
450 Finally, issues tagged with @code{Frog} indicates a task suitable
451 for a relatively new contributor. The time given is a quick
452 (inaccurate) estimate of the time required for somebody who is
453 familiar with material in this manual, but does not know anything
454 else about LilyPond development.
457 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog&mode=grid&y=Priority&x=Type&cells=ids}
461 @node Finding the cause of a regression
462 @section Finding the cause of a regression
464 @warning{This is not a @qq{simple} task; it requires a fair amount
465 of technical knowledge.}
467 Git has special functionality to help tracking down the exact
468 commit which causes a problem. See the git manual page for
469 @code{git bisect}. This is a job that non-programmers can do,
470 although it requires familiarity with git, ability to compile
471 LilyPond, and generally a fair amount of technical knowledge. An
472 in-depth explanation of this process will not be given here.
474 Even if you are not familiar with git or are not able to compile
475 LilyPond you can still help to narrow down the cause of a
476 regression simply by downloading the binary releases of different
477 LilyPond versions and testing them for the regression. Knowing
478 which version of LilyPond first exhibited the regression is
479 helpful to a developer as it shortens the @code{git bisect}
480 procedure described above.
482 Once a problematic commit is identified, the programmers' job is
483 much easier. In fact, for most regression bugs, the majority of
484 the time is spent simply finding the problematic commit.