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.
38 @subsubheading Email checklist
40 Every email to @code{bug-lilypond} should be handled within
41 @strong{24 hours} in the first method which is applicable:
46 If the email is a question about how to use LilyPond, direct them
47 politely to @code{lilypond-user}.
50 If a bug report is not in the form of a Tiny example, direct the
51 user to resubmit the report after reading @rweb{Tiny examples}.
54 If the behavior is expected, the user should be told to read the
55 documentation, or asked to clarify how he misread the docs and how
56 the docs could be improved.
59 If the issue already exists in the tracker, send an email to that
63 Ask the user for more information, such as lilypond version number
64 (if not given) and operating system (if this is a suspected cause
68 Accept the report as described in
69 @ref{Adding issues to the tracker}.
74 @node Issue classification
75 @section Issue classification
77 The Bug Squad should classify issues according to the guidelines
78 given by developers. Every issue should have a Status, Type, and
79 Priority; the other fields are optional.
81 @subheading Status (mandatory)
88 New: the item was added by a non-member, despite numerous warnings
89 not to do this. Should be reviewed by a member of the Bug Squad.
92 Accepted: the Bug Squad added it, or reviewed the item.
95 Started: a contributor is working on a fix. Owner should change
96 to be this contributor.
106 Invalid: issue should not have been added in the current state.
109 Duplicate: issue already exists in the tracker.
112 Fixed: a contributor claims to have fixed the bug. The Bug
113 Squad should check the fix with the next official binary release
114 (not by compiling the source from git). Owner should be set to
118 Verified: Bug Squad has confirmed that the issue is closed.
123 @subheading Owner (optional)
125 Newly-added issues should have @emph{no owner}. When a
126 contributor indicates that he has Started or Fixed an item, he
127 should become the owner.
130 @subheading Type (mandatory)
132 The issue's Type should be the first relevant item in this list.
137 Type-Collision: overlapping notation.
140 Type-Defect: a problem in the core program. (the @code{lilypond}
141 binary, scm files, fonts, etc).
144 Type-Documentation: inaccurate, missing, confusing, or desired
145 additional info. Must be fixable by editing a texinfo, ly, or scm
149 Type-Build: problem or desired features in the build system. This
150 includes the makefiles, stepmake, python scripts, and GUB.
153 Type-Scripts: problem or desired feature in the non-build-system
154 scripts. Mostly used for convert-ly, lilypond-book, etc.
156 Type-Enhancement: a feature request for the core program. The
157 distinction between enhancement and defect isn't extremely clear;
158 when in doubt, mark it as enhancement.
161 Type-Other: anything else.
166 @subheading Priority (mandatory)
168 Currently, only Critical items will block a stable release.
173 Priority-Critical: lilypond segfaults, or a regression occurred
174 within the last two stable versions. (i.e. when developing 2.13,
175 any regression against 2.12 or 2.10 counts)
178 Priority-High: highly embarrassing items, and any regression
179 against a version earlier than two stable versions (i.e. when
180 developing 2.13, any regression against 2.8 or earlier). This
181 level is also used for issues which produce no output and fail to
182 give the user a clue about what's wrong.
185 Priority-Medium: normal priority.
188 Priority-Low: less important than normal.
191 Priority-Postponed: no fix planned. Generally used for things
192 like Ancient notation, which nobody wants to touch.
196 The difference between Priority-Medium and Priority-Low is not
197 well-defined, both in this policy and in practice. The only
198 answer we can give at the moment is @qq{look at existing items in
199 of the same type, and try to guess whether the priority is closer
200 to the Medium items or Low items}. We're aware of the ambiguity,
201 and won't complain if somebody picks a @q{wrong} value for
205 @subheading Opsys (optional)
207 Issues that only affect specific operating systems.
210 @subheading Other items (optional)
217 Regression: it used to @strong{deliberately} work in an earlier
218 stable release. If the earlier output was accidental (i.e. we
219 didn't try to stop a collision, but it just so happened that two
220 grobs didn't collide), then breaking it does not count as a
224 Patch: a patch to fix an issue is attached.
227 Frog: the fix is believed to be suitable for a new contributor
228 (does not require a great deal of knowledge about LilyPond). The
229 issue should also have an estimated time in a comment.
232 Maintainability: hinders developent of LilyPond. For example,
233 improvements to the build system, or @qq{helper} python scripts.
236 Bounty: somebody is willing to pay for the fix. Only add this tag
237 if somebody has offered an exact figure in US dollars or euros.
240 Warning: graphical output is fine, but lilypond prints a
241 false/misleading warning message. Alternately, a warning should
242 be printed (such as a bar line error), but was not. Also applies
243 to warnings when compiling the source code or generating
247 Security: might potentially be used.
250 Performance: might potentially be used.
254 If you particularly want to add an label not in the list, go
255 ahead, but this is not recommended.
258 @node Adding issues to the tracker
259 @section Adding issues to the tracker
261 @warning{This should only be done by the Bug Squad or experienced
262 developers. Normal users should not do this; instead, they should
263 follow the guidelines for @rweb{Bug reports}.}
265 In order to assign labels to issues, Bug Squad members should log
266 in to their google account before adding an item.
268 @subsubheading Normal issues
273 Check if the issue falls into any previous category given on
274 @ref{Introduction to issues and the Bug Squad}. If in doubt, add
275 a new issue for a report. We would prefer to have some
276 incorrectly-added issues rather than lose information that should
280 Add the issue and classify it according to the guidelines in
281 @ref{Issue classification}. In particular, the item should have
282 @code{Status}, @code{Type-}, and @code{Priority-} labels.
285 After adding the issue, please send a response email to the same
286 group(s) that the initial patch was sent to. If the initial email
287 was sent to multiple mailing lists (such as both @code{user} and
288 @code{bugs}), then reply to all those mailing lists as well. The
289 email should contain a link to the issue you just added.
294 @subsubheading Patch reminders
296 There is a special category of issues: reminders of an existing
297 patch. These should be added if a patch has been sent to a
298 lilypond mailing list (generally @code{lilypond-devel}, but they
299 sometimes appear on @code{bug-lilypond} as well) and has had no
300 discussion for at least @strong{3 days}. Do not add issues for
301 patches under active discussion.
303 Before adding a patch-reminder issue, do a quick check to see if
304 it was pushed without sending any email. This can be checked for
305 searching for relevant terms (from the patch subject or commit
306 message) on the webgit page:
309 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
312 After adding the issue, please send a response email to the same
313 group(s) that the initial patch was sent to. If the initial email
314 was sent to multiple mailing lists (such as both @code{bugs} and
315 @code{devel}), then reply to all those mailing lists as well. The
316 email should contain a link to the issue you just added.
319 @node Checking and verifying issues
320 @section Checking and verifying issues
322 After each release (both stable and unstable):
327 Regression test comparison: check the relevant version in
328 @uref{http://lilypond.org/test/}.
332 @uref{http://code.google.com/p/lilypond/issues/list?can=7}.
336 Once every two weeks or so:
341 Check for any incorrectly-classified items in the tracker. This
342 generally just means looking at the grid to see any items without
346 Check for any items with @code{label:patch}. If it's been more
347 than a week since the last action on the issue, send an email to
348 -devel to remind them about it. If the patch was withdrawn for
349 more work, then remove the @code{patch} label.
352 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch}
357 Once every year or two: (yes, these are large tasks; gathering
358 more volunteers to help is definitely recommended)
363 Checking all regtests: although we have a system for checking the
364 regtests between two versions, occasionally a bug will slip
365 through the cracks. It is therefore good to manually examine all
366 the regtests (compare the images to the text description).
369 Checking all issues: we try to mark each Issue @q{fixed} when we
370 fix it, but occasionally one or two issues will slip through the
371 cracks. It is therefore good to check all Issues. If you see the
372 same (broken) output as the initial report, then simply post a
373 @qq{Problem still exists in 2.x.y} message to the issue.
378 @node Summary of project status
379 @section Summary of project status
381 The best overview of our current status is given by the grid view:
384 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}
387 Also of interest might be the issues hindering future development:
390 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability&mode=grid&y=Priority&x=Type&cells=ids}
393 Finally, issues tagged with @code{Frog} indicates a task suitable
394 for a relatively new contributor. The time given is a quick
395 (inaccurate) estimate of the time required for somebody who is
396 familiar with material in this manual, but does not know anything
397 else about LilyPond development.
400 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog&mode=grid&y=Priority&x=Type&cells=ids}
404 @node Finding the cause of a regression
405 @section Finding the cause of a regression
407 @warning{This is not a @qq{simple} task; it requires a fair amount
408 of technical knowledge.}
410 Git has special functionality to help tracking down the exact
411 commit which causes a problem. See the git manual page for
412 @code{git bisect}. This is a job that non-programmers can do,
413 although it requires familiarity with git, ability to compile
414 LilyPond, and generally a fair amount of technical knowledge. An
415 in-depth explanation of this process will not be given here.
417 Even if you are not familiar with git or are not able to compile
418 LilyPond you can still help to narrow down the cause of a
419 regression simply by downloading the binary releases of different
420 LilyPond versions and testing them for the regression. Knowing
421 which version of LilyPond first exhibited the regression is
422 helpful to a developer as it shortens the @code{git bisect}
423 procedure described above.
425 Once a problematic commit is identified, the programmers' job is
426 much easier. In fact, for most regression bugs, the majority of
427 the time is spent simply finding the problematic commit.