1 @c -*- coding: utf-8; mode: texinfo; -*-
5 This chapter deals with defects, feature requests, and
6 miscellaneous development tasks.
9 * Introduction to issues::
11 * Bug Squad checklists::
12 * Issue classification::
13 * Adding issues to the tracker::
14 * Summary of project status::
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.
37 New volunteers for the Bug Squad should contact the
38 @ref{Meisters, Bug Meister}.
42 @section Bug Squad setup
44 We highly recommend that you configure your email to use effective
45 sorting; this can reduce your workload @emph{immensely}. The
46 email folders names were chosen specifically to make them work if
47 you sort your folders alphabetically.
52 Read every section of this chapter, @ref{Issues}.
55 If you do not have one already, create a gmail account and send
56 the email address to the @ref{Meisters, Bug Meister}.
59 Subscribe your gmail account to @code{bug-lilypond}.
62 Configure your google code account:
67 Wait until your gmail account is listed in:
70 @uref{http://code.google.com/p/lilypond/people/list}
74 Sign in to google code by clicking in the top-right corner of:
77 @uref{http://code.google.com/p/lilypond/issues/list}
80 You cannot log if you have Google Sharing
81 @uref{http://www.googlesharing.net/} enabled.
84 Go to your @qq{Profile}, and select @qq{Settings}.
87 Scroll down to @qq{Issue change notification}, and make sure that
88 you have @emph{selected} @qq{If I starred the issue}.
93 Configure your email client:
98 Any email sent with your gmail address in the @code{To:} or
99 @code{CC:} fields should go to a @code{bug-answers} folder.
101 When setting up your filtering rules, be aware that Google Code
102 might use different versions of your email address, such as ones
103 ending in @code{@@googlemail.com} or @code{@@gmail.com}.
106 Any other email either from, or CC'd to,
109 lilypond@@googlecode.com
113 should go into a separate @code{bug-ignore} folder. Alternately,
114 you may automatically delete these emails.
116 You will @strong{not read} these emails as part of your Bug Squad
117 duties. If you are curious, go ahead and read them later, but it
118 does @strong{not} count as Bug Squad work.
121 Any other email sent to (or CC'd to):
128 should go into a separate @code{bug-current} folder.
135 @node Bug Squad checklists
136 @section Bug Squad checklists
138 When you do Bug Squad work, start at the top of this page and work
139 your way down. Stop when you've done 15 minutes.
141 Please use the email sorting described in @ref{Bug Squad setup}.
142 This means that (as Bug Squad members) you will only ever respond
143 to emails sent or CC'd to the @code{bug-lilypond} mailing list.
146 @subsubheading Emails to you personally
148 You are not expected to work on Bug Squad matters outside of your
149 15 minutes, but sometimes a confused user will send a bug report
150 (or an update to a report) to you personally. If that happens,
151 please forward such emails to the @code{bug-lilypond} list so that
152 the currently-active Bug Squad member(s) can handle the message.
155 @subsubheading Daily schedule
157 The Bug Meister is omitted from the daily schedule.
162 Tuesday: James Bailey
170 @subsubheading Emails to @code{bug-answers}
172 Some of these emails will be comments on issues that you added to
176 If they are asking for more information, give the additional
180 If the email says that the issue was classified in some other
181 manner, read the rationale given and take that into account for
182 the next issue you add.
185 Otherwise, move them to your @code{bug-ignore} folder.
189 Some of these emails will be discussions about Bug Squad work;
193 @subsubheading Emails to @code{bug-current}
195 Dealing with these emails is your main task. Your job is to get
196 rid of these emails in the first method which is applicable:
200 If the email has already been handled by a Bug Squad member (i.e.
201 check to see who else has replied to it), delete it.
204 If the email is a question about how to use LilyPond, reply with
208 For questions about how to use LilyPond, please read our
209 documentation available from:
210 @uref{http://lilypond.org/website/manuals.html}
211 or ask the lilypond-user mailing list.
215 If the email mentions @qq{the latest git}, or any version number
216 that has not yet been officially released, forward it to
217 @code{lilypond-devel}.
220 If a bug report is not in the form of a Tiny example, direct the
221 user to resubmit the report with this response:
224 I'm sorry, but due to our limited resources for handling bugs, we
225 can only accept reports in the form of Tiny examples. Please see
226 step 2 in our bug reporting guidelines:
227 @uref{http://lilypond.org/website/bug-reports.html}
231 If anything is unclear, ask the user for more information.
233 How does the graphical output differ from what the user expected?
234 What version of lilypond was used (if not given) and operating
235 system (if this is a suspected cause of the problem)? In short,
236 if you cannot understand what the problem is, ask the user to
237 explain more. It is the user's responsibility to explain the
238 problem, not your responsibility to understand it.
241 If the behavior is expected, the user should be told to read the
245 I believe that this is the expected behaviour -- please read our
246 documentation about this topic. If you think that it really is a
247 mistake, please explain in more detail. If you think that the
248 docs are unclear, please suggest an improvement as described by
249 @qq{Simple tasks -- Documentation} on:
250 @uref{http://lilypond.org/website/help-us.html}
254 If the issue already exists in the tracker, send an email to that
258 This issue has already been reported; you can follow the
259 discussion and be notified about fixes here:
263 (copy+paste the google code issue URL)
266 Accept the report as described in
267 @ref{Adding issues to the tracker}.
271 All emails should be CC'd to the @code{bug-lilypond} list so that
272 other Bug Squad members know that you have processed the email.
274 @warning{There is no option for @qq{ignore the bug report} -- if
275 you cannot find a reason to reject the report, you must accept
280 @c Try omitting this from Bug Squad duties
282 @subheading Updates / discussion about issues
284 We try to keep discussions about issues on the tracker, but
285 sometimes it spills over onto email. If discussion has ended with
286 no patch / resolution and at least @strong{3 days} have passed,
292 Summarize the recent discussion on the tracker, and add a link to
293 the original discussion.
296 Add the comment @qq{there was some technical discussion which I
297 could not understand}, and include a link to the original
300 We do not expect Bug Squad members to be programmers, or even to
301 be moderately-skilled users. Your job is to keep track of issue
302 reports; it is @emph{perfectly acceptable} to not understand
303 discussions between advanced users and/or developers.
309 @subheading Regular maintenance
311 After @strong{every release} (both stable and unstable):
316 Regression test comparison: if anything has changed suspiciously,
317 ask if it was deliberate. The official comparison is online, at:
319 @c NOTE: leave this here. In this case, it's worth duplicating
322 @uref{http://lilypond.org/test/}
325 More information is available from in
326 @ref{Precompiled regression tests}.
330 Issues to verify: try to reproduce the bug with the latest
331 version; if you cannot reproduce the bug, mark the item
332 @qq{Verified} (i.e. @qq{the fix has been verified to work}).
335 @uref{http://code.google.com/p/lilypond/issues/list?can=7}
338 A few (approximately 10%) of these fixed issues relate to the
339 build system or fundamental architecture changes; there is no way
340 for you to verify these. Leave those issues alone; somebody else
347 @c try omitting from daily tasks for now. -gp
349 Once every @strong{two weeks} or so:
354 Check for any incorrectly-classified items in the tracker. This
355 generally just means looking at the grid to see any items without
359 Check for any items with @code{label:patch}. If it's been more
360 than a week since the last action on the issue, send an email to
361 -devel to remind them about it. If the patch was withdrawn for
362 more work, then remove the @code{patch} label.
365 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch}
371 @subheading Irregular maintenance
373 @warning{These tasks are a lot of work; gathering more volunteers
374 to help is definitely recommended. However, the Bug Squad should
375 handle the organization and training of new volunteers.}
377 Once every year or two:
382 Checking all regtests: although we have a system for checking the
383 regtests between two versions, occasionally a bug will slip
384 through the cracks. It is therefore good to manually examine all
385 the regtests (compare the images to the text description). More
386 information is available from in @ref{Regression tests}.
390 Checking all issues: we try to mark each Issue @q{fixed} when we
391 fix it, but occasionally one or two issues will slip through the
392 cracks. It is therefore good to check all Issues. If you see the
393 same (broken) output as the initial report, then simply post a
394 @qq{Problem still exists in 2.x.y} message to the issue.
401 @node Issue classification
402 @section Issue classification
404 The Bug Squad should classify issues according to the guidelines
405 given by developers. Every issue should have a Status, Type, and
406 Priority; the other fields are optional.
408 @subheading Status (mandatory)
415 New: the item was added by a non-member, despite numerous warnings
416 not to do this. Should be reviewed by a member of the Bug Squad.
419 Accepted: the Bug Squad added it, or reviewed the item.
422 Started: a contributor is working on a fix. Owner should change
423 to be this contributor.
433 Invalid: issue should not have been added in the current state.
436 Duplicate: issue already exists in the tracker.
439 Fixed: a contributor claims to have fixed the bug. The Bug
440 Squad should check the fix with the next official binary release
441 (not by compiling the source from git). Owner should be set to
445 Verified: Bug Squad has confirmed that the issue is closed. This
446 means that nobody should ever need look at the report again -- if
447 there is any information in the issue that should be kept, open a
448 new issue for that info.
453 @subheading Owner (optional)
455 Newly-added issues should have @emph{no owner}. When a
456 contributor indicates that he has Started or Fixed an item, he
457 should become the owner.
460 @subheading Type (mandatory)
462 The issue's Type should be the first relevant item in this list.
467 Type-Collision: overlapping notation.
470 Type-Defect: a problem in the core program. (the @code{lilypond}
471 binary, scm files, fonts, etc).
474 Type-Documentation: inaccurate, missing, confusing, or desired
475 additional info. Must be fixable by editing a texinfo, ly, or scm
479 Type-Build: problem or desired features in the build system. This
480 includes the makefiles, stepmake, python scripts, and GUB.
483 Type-Scripts: problem or desired feature in the non-build-system
484 scripts. Mostly used for convert-ly, lilypond-book, etc.
487 Type-Enhancement: a feature request for the core program. The
488 distinction between enhancement and defect isn't extremely clear;
489 when in doubt, mark it as enhancement.
492 Type-Other: anything else.
497 @subheading Priority (mandatory)
499 Currently, only Critical items will block a stable release.
504 Priority-Critical: LilyPond segfaults, a regression (see below)
505 against a previous stable version or a regression against a fix
506 developed for this version. This does not apply where the
507 @qq{regression} occurred because a feature was removed
508 deliberately - this is not a bug.
511 Priority-High: An issue which produces output which does not
512 accurately reflect the input (e.g. where the user would expect
513 an accidental, but none is shown) or which produces aesthetically
514 poor output in a situation which could be expected to crop up
515 frequently in real-world music. It should not be used where the
516 problem can be avoided with a simple workaround. It can also
517 be used to flag where new code in a development version is not
518 functioning as it should. This level is also used for issues
519 which produce no output and fail to give the user a clue about
523 Priority-Medium: Normal priority - use this as the default.
526 Priority-Low: A minor problem which produces slightly undesirable
527 output, or which will only occur in contrived examples, or which
528 is very easily worked around.
531 Priority-Postponed: no fix planned. Generally used for things
532 which nobody wants to touch.
536 Note that these are initial classifications and can be subject
537 to change by others in the development team. For example, a
538 regression against an old stable version which hasn't been
539 noticed for a long time and which is unlikely to get fixed could
540 be downgraded from Priority-Critical by one of the programmers.
542 @subheading Opsys (optional)
544 Issues that only affect specific operating systems.
546 @subheading Patch (optional)
551 Patch-new: the patch has not been checked for @qq{obvious}
552 mistakes. When in doubt, use this tag.
555 Patch-review: the patch has no @qq{obvious} mistakes (as checked
556 by the Patch Meister), and is ready for review from main
559 Developers with git push ability can use this category, skipping
560 over @code{patch-new}.
563 Patch-needs_work: a developer has some concerns about the patch.
564 This does not necessarily mean that the patch must be changed; in
565 some cases, the developer's concerns can be resolved simply by
566 discussion the situation or providing notation examples.
568 If the patch is updated, the category should be changed to
569 @code{patch-new} (for normal contributors) or @code{patch-new}
570 (for developers who are very confident about their patch).
573 Patch-abandoned: the author has not responded to review comments
578 @subheading Other items (optional)
585 Regression: it used to work intentionally in an earlier
586 stable release. If the earlier output was accidental (i.e. we
587 didn't try to stop a collision, but it just so happened that two
588 grobs didn't collide), then breaking it does not count as a
591 To help decide whether the change is a regression, and therefore
592 should be Priority-Critical, please adopt the following process:
597 Are you certain the change is OK? If so, do nothing.
600 Are you certain that the change is bad? Add it to the tracker
601 as a Critical issue, regression.
604 If you're not certain either way, add it to the tracker as a
605 Critical issue, regression but be aware that it may be
606 recategorised or marked invalid.
610 In particular, anything that breaks a regression test is a
614 Frog: the fix is believed to be suitable for a new contributor
615 (does not require a great deal of knowledge about LilyPond). The
616 issue should also have an estimated time in a comment.
619 Maintainability: hinders development of LilyPond. For example,
620 improvements to the build system, or @qq{helper} python scripts.
623 Bounty: somebody is willing to pay for the fix. Only add this tag
624 if somebody has offered an exact figure in US dollars or euros.
627 Warning: graphical output is fine, but lilypond prints a
628 false/misleading warning message. Alternately, a warning should
629 be printed (such as a bar line error), but was not. Also applies
630 to warnings when compiling the source code or generating
634 Security: might potentially be used.
637 Performance: might potentially be used.
641 If you particularly want to add a label not in the list, go
642 ahead, but this is not recommended.
645 @node Adding issues to the tracker
646 @section Adding issues to the tracker
648 @warning{This should only be done by the Bug Squad or experienced
649 developers. Normal users should not do this; instead, they should
650 follow the guidelines for @rweb{Bug reports}.}
652 In order to assign labels to issues, Bug Squad members should log
653 in to their google account before adding an item.
655 @subsubheading Normal issues
660 Check if the issue falls into any previous category given on the
661 relevant checklists in @ref{Bug Squad checklists}. If in doubt,
662 add a new issue for a report. We would prefer to have some
663 incorrectly-added issues rather than lose information that should
667 Add the issue and classify it according to the guidelines in
668 @ref{Issue classification}. In particular, the item should have
669 @code{Status}, @code{Type-}, and @code{Priority-} labels.
671 Include output with the first applicable method:
676 If the issue has a notation example which fits in one system,
677 generate a small @file{bug.preview.png} file with:
680 lilypond -dpreview bug.ly
684 If the issue has an example which requires more than one system
685 (i.e. a spacing bug), generate a @file{bug.png} file with:
688 lilypond --png bug.ly
692 If the issue requires one or two pages of output, then generate a
693 @file{bug.png} file with the normal:
696 lilypond --png bug.ly
700 If the issue cannot be shown with less than three pages, then
701 generate a @file{bug.pdf} file with:
704 lilypond --pdf bug.ly
707 Note that this is likely to be extremely rare; most bugs should fit
708 into the first two categories above.
714 After adding the issue, please send a response email to the same
715 group(s) that the initial patch was sent to. If the initial email
716 was sent to multiple mailing lists (such as both @code{user} and
717 @code{bugs}), then reply to all those mailing lists as well. The
718 email should contain a link to the issue you just added.
723 @subsubheading Patch reminders
725 @warning{This is not a Bug Squad responsibility; we have a
726 separate person handling this task.}
728 There is a special category of issues: reminders of an existing
729 patch. These should be added if a patch has been sent to a
730 lilypond mailing list (generally @code{lilypond-devel}, but they
731 sometimes appear on @code{bug-lilypond} as well) and has had no
732 discussion for at least @strong{3 days}. Do not add issues for
733 patches under active discussion.
735 Before adding a patch-reminder issue, do a quick check to see if
736 it was pushed without sending any email. This can be checked for
737 searching for relevant terms (from the patch subject or commit
738 message) on the webgit page:
741 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
744 After adding the issue, please send a response email to the same
745 group(s) that the initial patch was sent to. If the initial email
746 was sent to multiple mailing lists (such as both @code{bugs} and
747 @code{devel}), then reply to all those mailing lists as well. The
748 email should contain a link to the issue you just added.
751 @node Summary of project status
752 @section Summary of project status
754 @subsubheading Project overview
756 Grid view provides the best overview:
759 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}
762 @subsubheading Hindering development
764 These issues stop or slow development work:
767 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability&mode=grid&y=Priority&x=Type&cells=ids}
770 @subsubheading Easy tasks
772 Issues tagged with @code{Frog} indicates a task suitable for a
773 relatively new contributor. The time given is a quick
774 (inaccurate) estimate of the time required for somebody who is
775 familiar with material in this manual, but does not know anything
776 else about LilyPond development.
779 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog&mode=grid&y=Priority&x=Type&cells=ids}
782 @subsubheading Patches to review
784 Patches which have no @qq{obvious} problems:
787 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch-review}