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 behaviour 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.
157 Type-Enhancement: a feature request for the core program. The
158 distinction between enhancement and defect isn't extremely clear;
159 when in doubt, mark it as enhancement.
162 Type-Other: anything else.
167 @subheading Priority (mandatory)
169 Currently, only Critical items will block a stable release.
174 Priority-Critical: lilypond segfaults, or a regression occurred
175 within the last two stable versions. (i.e. when developing 2.13,
176 any regression against 2.12 or 2.10 counts)
179 Priority-High: highly embarrassing items, and any regression
180 against a version earlier than two stable versions (i.e. when
181 developing 2.13, any regression against 2.8 or earlier). This
182 level is also used for issues which produce no output and fail to
183 give the user a clue about what's wrong.
186 Priority-Medium: normal priority.
189 Priority-Low: less important than normal.
192 Priority-Postponed: no fix planned. Generally used for things
193 like Ancient notation, which nobody wants to touch.
197 The difference between Priority-Medium and Priority-Low is not
198 well-defined, both in this policy and in practice. The only
199 answer we can give at the moment is @qq{look at existing items in
200 of the same type, and try to guess whether the priority is closer
201 to the Medium items or Low items}. We're aware of the ambiguity,
202 and won't complain if somebody picks a @q{wrong} value for
206 @subheading Opsys (optional)
208 Issues that only affect specific operating systems.
211 @subheading Other items (optional)
218 Regression: it used to @strong{deliberately} work in an earlier
219 stable release. If the earlier output was accidental (i.e. we
220 didn't try to stop a collision, but it just so happened that two
221 grobs didn't collide), then breaking it does not count as a
225 Patch: a patch to fix an issue is attached.
228 Frog: the fix is believed to be suitable for a new contributor
229 (does not require a great deal of knowledge about LilyPond). The
230 issue should also have an estimated time in a comment.
233 Maintainability: hinders developent of LilyPond. For example,
234 improvements to the build system, or @qq{helper} python scripts.
237 Bounty: somebody is willing to pay for the fix.
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.