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::
15 * Summary of project status::
19 @node Introduction to issues
20 @section Introduction to issues
22 @warning{Unless otherwise specified, all the tasks in this chapter
23 are @qq{simple} tasks: they can be done by a normal user with
24 nothing more than a web browser, email, and lilypond.}
26 @qq{Issues} isn't just a politically-correct term for @qq{bug}.
27 We use the same tracker for feature requests and code TODOs, so
28 the term @qq{bug} wouldn't be accurate. Despite the difference
29 between @qq{issue} and @qq{bug}, we call our team of contributors
30 who organize issues the @emph{Bug Squad}.
32 The Bug Squad is mainly composed of non-programmers -- their job
33 is to @emph{organize} issues, not solve them. Their duties
34 include removing false bug reports, ensuring that any real bug
35 report contains enough information for developers, and checking
36 that a developer's fix actually resolves the problem.
38 New volunteers for the Bug Squad should contact the
39 @ref{Meisters, Bug Meister}.
43 @section Bug Squad setup
45 We highly recommend that you configure your email to use effective
46 sorting; this can reduce your workload @emph{immensely}. The
47 email folders names were chosen specifically to make them work if
48 you sort your folders alphabetically.
53 Read every section of this chapter, @ref{Issues}.
56 If you do not have one already, create a gmail account and send
57 the email address to the @ref{Meisters, Bug Meister}.
60 Subscribe your gmail account to @code{bug-lilypond}.
63 Configure your google code account:
68 Wait until your gmail account is listed in:
71 @uref{http://code.google.com/p/lilypond/people/list}
75 Sign in to google code by clicking in the top-right corner of:
78 @uref{http://code.google.com/p/lilypond/issues/list}
81 You cannot log if you have Google Sharing
82 @uref{http://www.googlesharing.net/} enabled.
85 Go to your @qq{Profile}, and select @qq{Settings}.
88 Scroll down to @qq{Issue change notification}, and make sure that
89 you have @emph{selected} @qq{If I starred the issue}.
94 Configure your email client:
99 Any email sent with your gmail address in the @code{To:} or
100 @code{CC:} fields should go to a @code{bug-answers} folder.
102 When setting up your filtering rules, be aware that Google Code
103 might use different versions of your email address, such as ones
104 ending in @code{@@googlemail.com} or @code{@@gmail.com}.
107 Any other email either from, or CC'd to,
110 lilypond@@googlecode.com
114 should go into a separate @code{bug-ignore} folder. Alternately,
115 you may automatically delete these emails.
117 You will @strong{not read} these emails as part of your Bug Squad
118 duties. If you are curious, go ahead and read them later, but it
119 does @strong{not} count as Bug Squad work.
122 Any other email sent to (or CC'd to):
129 should go into a separate @code{bug-current} folder.
136 @node Bug Squad checklists
137 @section Bug Squad checklists
139 When you do Bug Squad work, start at the top of this page and work
140 your way down. Stop when you've done 15 minutes.
142 Please use the email sorting described in @ref{Bug Squad setup}.
143 This means that (as Bug Squad members) you will only ever respond
144 to emails sent or CC'd to the @code{bug-lilypond} mailing list.
147 @subsubheading Emails to you personally
149 You are not expected to work on Bug Squad matters outside of your
150 15 minutes, but sometimes a confused user will send a bug report
151 (or an update to a report) to you personally. If that happens,
152 please forward such emails to the @code{bug-lilypond} list so that
153 the currently-active Bug Squad member(s) can handle the message.
156 @subsubheading Daily schedule
158 The Bug Meister is omitted from the daily schedule.
163 Tuesday: James Bailey
171 @subsubheading Emails to @code{bug-answers}
173 Some of these emails will be comments on issues that you added to
177 If they are asking for more information, give the additional
181 If the email says that the issue was classified in some other
182 manner, read the rationale given and take that into account for
183 the next issue you add.
186 Otherwise, move them to your @code{bug-ignore} folder.
190 Some of these emails will be discussions about Bug Squad work;
194 @subsubheading Emails to @code{bug-current}
196 Dealing with these emails is your main task. Your job is to get
197 rid of these emails in the first method which is applicable:
201 If the email has already been handled by a Bug Squad member (i.e.
202 check to see who else has replied to it), delete it.
205 If the email is a question about how to use LilyPond, reply with
209 For questions about how to use LilyPond, please read our
210 documentation available from:
211 @uref{http://lilypond.org/website/manuals.html}
212 or ask the lilypond-user mailing list.
216 If the email mentions @qq{the latest git}, or any version number
217 that has not yet been officially released, forward it to
218 @code{lilypond-devel}.
221 If a bug report is not in the form of a Tiny example, direct the
222 user to resubmit the report with this response:
225 I'm sorry, but due to our limited resources for handling bugs, we
226 can only accept reports in the form of Tiny examples. Please see
227 step 2 in our bug reporting guidelines:
228 @uref{http://lilypond.org/website/bug-reports.html}
232 If anything is unclear, ask the user for more information.
234 How does the graphical output differ from what the user expected?
235 What version of lilypond was used (if not given) and operating
236 system (if this is a suspected cause of the problem)? In short,
237 if you cannot understand what the problem is, ask the user to
238 explain more. It is the user's responsibility to explain the
239 problem, not your responsibility to understand it.
242 If the behavior is expected, the user should be told to read the
246 I believe that this is the expected behaviour -- please read our
247 documentation about this topic. If you think that it really is a
248 mistake, please explain in more detail. If you think that the
249 docs are unclear, please suggest an improvement as described by
250 @qq{Simple tasks -- Documentation} on:
251 @uref{http://lilypond.org/website/help-us.html}
255 If the issue already exists in the tracker, send an email to that
259 This issue has already been reported; you can follow the
260 discussion and be notified about fixes here:
264 (copy+paste the google code issue URL)
267 Accept the report as described in
268 @ref{Adding issues to the tracker}.
272 All emails should be CC'd to the @code{bug-lilypond} list so that
273 other Bug Squad members know that you have processed the email.
275 @warning{There is no option for @qq{ignore the bug report} -- if
276 you cannot find a reason to reject the report, you must accept
281 @c Try omitting this from Bug Squad duties
283 @subheading Updates / discussion about issues
285 We try to keep discussions about issues on the tracker, but
286 sometimes it spills over onto email. If discussion has ended with
287 no patch / resolution and at least @strong{3 days} have passed,
293 Summarize the recent discussion on the tracker, and add a link to
294 the original discussion.
297 Add the comment @qq{there was some technical discussion which I
298 could not understand}, and include a link to the original
301 We do not expect Bug Squad members to be programmers, or even to
302 be moderately-skilled users. Your job is to keep track of issue
303 reports; it is @emph{perfectly acceptable} to not understand
304 discussions between advanced users and/or developers.
310 @subheading Regular maintenance
312 After @strong{every release} (both stable and unstable):
317 Regression test comparison: if anything has changed suspiciously,
318 ask if it was deliberate. The official comparison is online, at:
320 @c NOTE: leave this here. In this case, it's worth duplicating
323 @uref{http://lilypond.org/test/}
326 More information is available from in
327 @ref{Precompiled regression tests}.
331 Issues to verify: try to reproduce the bug with the latest
332 official GUB version; if you cannot reproduce the bug, mark the
333 item @qq{Verified} (i.e. @qq{the fix has been verified to work}).
336 @uref{http://code.google.com/p/lilypond/issues/list?can=7}
339 A few (approximately 10%) of these fixed issues relate to the
340 build system or fundamental architecture changes; there is no way
341 for you to verify these. Leave those issues alone; somebody else
345 Check for any incorrectly-classified items in the tracker. This
346 generally just means looking at the grid to see any items without
353 @c try omitting from daily tasks for now. -gp
355 @subheading Irregular maintenance
357 @warning{These tasks are a lot of work; gathering more volunteers
358 to help is definitely recommended. However, the Bug Squad should
359 handle the organization and training of new volunteers.}
361 Once every year or two:
366 Checking all regtests: although we have a system for checking the
367 regtests between two versions, occasionally a bug will slip
368 through the cracks. It is therefore good to manually examine all
369 the regtests (compare the images to the text description). More
370 information is available from in @ref{Regression tests}.
374 Checking all issues: we try to mark each Issue @q{fixed} when we
375 fix it, but occasionally one or two issues will slip through the
376 cracks. It is therefore good to check all Issues. If you see the
377 same (broken) output as the initial report, then simply post a
378 @qq{Problem still exists in 2.x.y} message to the issue.
385 @node Issue classification
386 @section Issue classification
388 The Bug Squad should classify issues according to the guidelines
389 given by developers. Every issue should have a Status, Type, and
390 Priority; the other fields are optional.
392 @subheading Status (mandatory)
399 New: the item was added by a non-member, despite numerous warnings
400 not to do this. Should be reviewed by a member of the Bug Squad.
403 Accepted: the Bug Squad added it, or reviewed the item.
406 Started: a contributor is working on a fix. Owner should change
407 to be this contributor.
417 Invalid: issue should not have been added in the current state.
420 Duplicate: issue already exists in the tracker.
423 Fixed: a contributor claims to have fixed the bug. The Bug
424 Squad should check the fix with the next official binary release
425 (not by compiling the source from git). Owner should be set to
429 Verified: Bug Squad has confirmed that the issue is closed. This
430 means that nobody should ever need look at the report again -- if
431 there is any information in the issue that should be kept, open a
432 new issue for that info.
437 @subheading Owner (optional)
439 Newly-added issues should have @emph{no owner}. When a
440 contributor indicates that he has Started or Fixed an item, he
441 should become the owner.
444 @subheading Type (mandatory)
446 The issue's Type should be the first relevant item in this list.
451 Type-Collision: overlapping notation.
454 Type-Defect: a problem in the core program. (the @code{lilypond}
455 binary, scm files, fonts, etc).
458 Type-Documentation: inaccurate, missing, confusing, or desired
459 additional info. Must be fixable by editing a texinfo, ly, or scm
463 Type-Build: problem or desired features in the build system. This
464 includes the makefiles, stepmake, python scripts, and GUB.
467 Type-Scripts: problem or desired feature in the non-build-system
468 scripts. Mostly used for convert-ly, lilypond-book, etc.
471 Type-Enhancement: a feature request for the core program. The
472 distinction between enhancement and defect isn't extremely clear;
473 when in doubt, mark it as enhancement.
476 Type-Other: anything else.
481 @subheading Priority (mandatory)
483 Currently, only Critical items will block a stable release.
488 Priority-Critical: LilyPond segfaults, a regression (see below)
489 against a previous stable version or a regression against a fix
490 developed for this version. This does not apply where the
491 @qq{regression} occurred because a feature was removed
492 deliberately - this is not a bug.
495 Priority-High: An issue which produces output which does not
496 accurately reflect the input (e.g. where the user would expect
497 an accidental, but none is shown) or which produces aesthetically
498 poor output in a situation which could be expected to crop up
499 frequently in real-world music. It should not be used where the
500 problem can be avoided with a simple workaround. It can also
501 be used to flag where new code in a development version is not
502 functioning as it should. This level is also used for issues
503 which produce no output and fail to give the user a clue about
507 Priority-Medium: Normal priority - use this as the default.
510 Priority-Low: A minor problem which produces slightly undesirable
511 output, or which will only occur in contrived examples, or which
512 is very easily worked around.
515 Priority-Postponed: no fix planned. Generally used for things
516 which nobody wants to touch.
520 Note that these are initial classifications and can be subject
521 to change by others in the development team. For example, a
522 regression against an old stable version which hasn't been
523 noticed for a long time and which is unlikely to get fixed could
524 be downgraded from Priority-Critical by one of the programmers.
526 @subheading Opsys (optional)
528 Issues that only affect specific operating systems.
530 @subheading Patch (optional)
532 Normal Bug Squad members should not add or modify Patch issues;
533 leave them to the Patch Meister.
538 Patch-new: the patch has not been checked for @qq{obvious}
539 mistakes. When in doubt, use this tag.
542 Patch-review: the patch has no @qq{obvious} mistakes (as checked
543 by the Patch Meister), and is ready for review from main
546 Developers with git push ability can use this category, skipping
547 over @code{patch-new}.
550 Patch-needs_work: a developer has some concerns about the patch.
551 This does not necessarily mean that the patch must be changed; in
552 some cases, the developer's concerns can be resolved simply by
553 discussion the situation or providing notation examples.
555 If the patch is updated, the category should be changed to
556 @code{patch-new} (for normal contributors) or @code{patch-new}
557 (for developers who are very confident about their patch).
560 Patch-abandoned: the author has not responded to review comments
565 @subheading Other items (optional)
572 Regression: it used to work intentionally in an earlier
573 stable release. If the earlier output was accidental (i.e. we
574 didn't try to stop a collision, but it just so happened that two
575 grobs didn't collide), then breaking it does not count as a
578 To help decide whether the change is a regression, and therefore
579 should be Priority-Critical, please adopt the following process:
584 Are you certain the change is OK? If so, do nothing.
587 Are you certain that the change is bad? Add it to the tracker
588 as a Critical issue, regression.
591 If you're not certain either way, add it to the tracker as a
592 Critical issue, regression but be aware that it may be
593 recategorised or marked invalid.
597 In particular, anything that breaks a regression test is a
601 Frog: the fix is believed to be suitable for a new contributor
602 (does not require a great deal of knowledge about LilyPond). The
603 issue should also have an estimated time in a comment.
606 Maintainability: hinders development of LilyPond. For example,
607 improvements to the build system, or @qq{helper} python scripts.
610 Bounty: somebody is willing to pay for the fix. Only add this tag
611 if somebody has offered an exact figure in US dollars or euros.
614 Warning: graphical output is fine, but lilypond prints a
615 false/misleading warning message. Alternately, a warning should
616 be printed (such as a bar line error), but was not. Also applies
617 to warnings when compiling the source code or generating
621 Security: might potentially be used.
624 Performance: might potentially be used.
628 If you particularly want to add a label not in the list, go
629 ahead, but this is not recommended.
632 @node Adding issues to the tracker
633 @section Adding issues to the tracker
635 @warning{This should only be done by the Bug Squad or experienced
636 developers. Normal users should not do this; instead, they should
637 follow the guidelines for @rweb{Bug reports}.}
639 In order to assign labels to issues, Bug Squad members should log
640 in to their google account before adding an item.
645 Check if the issue falls into any previous category given on the
646 relevant checklists in @ref{Bug Squad checklists}. If in doubt,
647 add a new issue for a report. We would prefer to have some
648 incorrectly-added issues rather than lose information that should
652 Add the issue and classify it according to the guidelines in
653 @ref{Issue classification}. In particular, the item should have
654 @code{Status}, @code{Type-}, and @code{Priority-} labels.
656 Include output with the first applicable method:
661 If the issue has a notation example which fits in one system,
662 generate a small @file{bug.preview.png} file with:
665 lilypond -dpreview bug.ly
669 If the issue has an example which requires more than one system
670 (i.e. a spacing bug), generate a @file{bug.png} file with:
673 lilypond --png bug.ly
677 If the issue requires one or two pages of output, then generate a
678 @file{bug.png} file with the normal:
681 lilypond --png bug.ly
685 If the issue cannot be shown with less than three pages, then
686 generate a @file{bug.pdf} file with:
689 lilypond --pdf bug.ly
692 Note that this is likely to be extremely rare; most bugs should fit
693 into the first two categories above.
699 After adding the issue, please send a response email to the same
700 group(s) that the initial patch was sent to. If the initial email
701 was sent to multiple mailing lists (such as both @code{user} and
702 @code{bugs}), then reply to all those mailing lists as well. The
703 email should contain a link to the issue you just added.
710 @section Patch handling
712 @warning{This is not a Bug Squad responsibility; we have a
713 separate person handling this task.}
715 There is a single Patch Meister, and a number of Patch Helpers
716 (rename this?). The list of known patches awaiting review is:
719 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch&sort=patch}
723 @subheading Helpers: adding patches
725 The primary duty is to add patches to the google tracker; we have
726 a bad track record of losing patches in email. Patches generally
727 come to the @code{lilypond-devel} mailing list, but are sometimes
728 sent to @code{bug-lilypond}, @code{lilypond-users}, or
729 @code{frogs} mailing list instead.
733 Unless a patch is clearly in response to an existing issue, add a
734 new issue with the @code{Patch-new} label and a link to the patch
735 (either on the mailing list archives or the codereview url).
737 Issue numbers are cheap; losing developers because they got fed up
738 with us losing their hard work is expensive.
740 @c if we enter patches immediately, I don't think this is relevant.
743 Before adding a patch-reminder issue, do a quick check to see if
744 it was pushed without sending any email. This can be checked for
745 searching for relevant terms (from the patch subject or commit
746 message) on the webgit page:
749 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
754 If the patch is clearly in response to an existing issue, then
755 update that issue with the @code{Patch-new} label and a link to
756 the patch (either on the mailing list archives or the codereview
760 After adding the issue, please send a response email to the same
761 group(s) that the initial patch was sent to.
763 If the initial email was sent to multiple mailing lists (such as
764 both @code{bugs} and @code{devel}), then reply to all those
765 mailing lists as well. The email should contain a link to the
766 issue you just added.
770 @subheading Helpers: @code{Patch-review} label
772 The secondary duty is to do make sure that every issue in the
773 tracker with a @code{Patch-review} label has passed these
778 Applies automatically to git master.
780 It's ok to have offsets, but not conflicts.
783 Regtest comparison looks ok; no unexpected changes.
786 Descriptive subject line.
788 Avoid subjects like @qq{fixes 123}; instead write @qq{Doc: discuss
789 stacking-dir for BassFigureAlignment (fix 123)}.
792 Compiles docs from scratch. Only check this if you have reason to
793 suspect it might not work.
798 Check code indentation and style. This should be easier post-GOP
799 when we have a better-defined code style.
804 @subheading Patch Meister
806 The Patch Meister will:
811 send @qq{countdown} emails to
812 @code{lilypond-devel} when patches appear to be ready.
815 send general requests to review patches, or even nasty requests to
819 downgrade patches from @code{Patch-review} to
820 @code{Patch-needs_work} as appropriate.
823 downgrade patches from @code{Patch-needs_work} to
824 @code{Patch-abandoned} if no actions have been taken in four
832 @node Summary of project status
833 @section Summary of project status
835 @subsubheading Project overview
837 Grid view provides the best overview:
840 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}
843 @subsubheading Hindering development
845 These issues stop or slow development work:
848 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability&mode=grid&y=Priority&x=Type&cells=ids}
851 @subsubheading Easy tasks
853 Issues tagged with @code{Frog} indicates a task suitable for a
854 relatively new contributor. The time given is a quick
855 (inaccurate) estimate of the time required for somebody who is
856 familiar with material in this manual, but does not know anything
857 else about LilyPond development.
860 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog&mode=grid&y=Priority&x=Type&cells=ids}
863 @subsubheading Patches to review
865 Patches which have no @qq{obvious} problems:
868 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch-review}