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 20 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 20 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
169 @subsubheading Emails to @code{bug-answers}
171 Some of these emails will be comments on issues that you added to
175 If they are asking for more information, give the additional
179 If the email says that the issue was classified in some other
180 manner, read the rationale given and take that into account for
181 the next issue you add.
184 Otherwise, move them to your @code{bug-ignore} folder.
188 Some of these emails will be discussions about Bug Squad work;
192 @subsubheading Emails to @code{bug-current}
194 Dealing with these emails is your main task. Your job is to get
195 rid of these emails in the first method which is applicable:
199 If the email has already been handled by a Bug Squad member (i.e.
200 check to see who else has replied to it), delete it.
203 If the email is a question about how to use LilyPond, reply with
207 For questions about how to use LilyPond, please read our
208 documentation available from:
209 @uref{http://lilypond.org/website/manuals.html}
210 or ask the lilypond-user mailing list.
214 If the email mentions @qq{the latest git}, or any version number
215 that has not yet been officially released, forward it to
216 @code{lilypond-devel}.
219 If a bug report is not in the form of a Tiny example, direct the
220 user to resubmit the report with this response:
223 I'm sorry, but due to our limited resources for handling bugs, we
224 can only accept reports in the form of Tiny examples. Please see
225 step 2 in our bug reporting guidelines:
226 @uref{http://lilypond.org/website/bug-reports.html}
230 If anything is unclear, ask the user for more information.
232 How does the graphical output differ from what the user expected?
233 What version of lilypond was used (if not given) and operating
234 system (if this is a suspected cause of the problem)? In short,
235 if you cannot understand what the problem is, ask the user to
236 explain more. It is the user's responsibility to explain the
237 problem, not your responsibility to understand it.
240 If the behavior is expected, the user should be told to read the
244 I believe that this is the expected behaviour -- please read our
245 documentation about this topic. If you think that it really is a
246 mistake, please explain in more detail. If you think that the
247 docs are unclear, please suggest an improvement as described by
248 @qq{Simple tasks -- Documentation} on:
249 @uref{http://lilypond.org/website/help-us.html}
253 If the issue already exists in the tracker, send an email to that
257 This issue has already been reported; you can follow the
258 discussion and be notified about fixes here:
262 (copy+paste the google code issue URL)
265 Accept the report as described in
266 @ref{Adding issues to the tracker}.
270 All emails should be CC'd to the @code{bug-lilypond} list so that
271 other Bug Squad members know that you have processed the email.
273 @warning{There is no option for @qq{ignore the bug report} -- if
274 you cannot find a reason to reject the report, you must accept
279 @c Try omitting this from Bug Squad duties
281 @subheading Updates / discussion about issues
283 We try to keep discussions about issues on the tracker, but
284 sometimes it spills over onto email. If discussion has ended with
285 no patch / resolution and at least @strong{3 days} have passed,
291 Summarize the recent discussion on the tracker, and add a link to
292 the original discussion.
295 Add the comment @qq{there was some technical discussion which I
296 could not understand}, and include a link to the original
299 We do not expect Bug Squad members to be programmers, or even to
300 be moderately-skilled users. Your job is to keep track of issue
301 reports; it is @emph{perfectly acceptable} to not understand
302 discussions between advanced users and/or developers.
308 @subheading Regular maintenance
310 After @strong{every release} (both stable and unstable):
315 Regression test comparison: if anything has changed suspiciously,
316 ask if it was deliberate. The official comparison is online, at:
318 @c NOTE: leave this here. In this case, it's worth duplicating
321 @uref{http://lilypond.org/test/}
324 More information is available from in
325 @ref{Precompiled regression tests}.
329 Issues to verify: try to reproduce the bug with the latest
330 official GUB version; if you cannot reproduce the bug, mark the
331 item @qq{Verified} (i.e. @qq{the fix has been verified to work}).
334 @uref{http://code.google.com/p/lilypond/issues/list?can=7}
337 A few (approximately 10%) of these fixed issues relate to the
338 build system or fundamental architecture changes; there is no way
339 for you to verify these. Leave those issues alone; somebody else
343 Check for any incorrectly-classified items in the tracker. This
344 generally just means looking at the grid to see any items without
351 @c try omitting from daily tasks for now. -gp
353 @subheading Irregular maintenance
355 @warning{These tasks are a lot of work; gathering more volunteers
356 to help is definitely recommended. However, the Bug Squad should
357 handle the organization and training of new volunteers.}
359 Once every year or two:
364 Checking all regtests: although we have a system for checking the
365 regtests between two versions, occasionally a bug will slip
366 through the cracks. It is therefore good to manually examine all
367 the regtests (compare the images to the text description). More
368 information is available from in @ref{Regression tests}.
372 Checking all issues: we try to mark each Issue @q{fixed} when we
373 fix it, but occasionally one or two issues will slip through the
374 cracks. It is therefore good to check all Issues. If you see the
375 same (broken) output as the initial report, then simply post a
376 @qq{Problem still exists in 2.x.y} message to the issue.
383 @node Issue classification
384 @section Issue classification
386 The Bug Squad should classify issues according to the guidelines
387 given by developers. Every issue should have a Status, Type, and
388 Priority; the other fields are optional.
390 @subheading Status (mandatory)
397 New: the item was added by a non-member, despite numerous warnings
398 not to do this. Should be reviewed by a member of the Bug Squad.
401 Accepted: the Bug Squad added it, or reviewed the item.
404 Started: a contributor is working on a fix. Owner should change
405 to be this contributor.
415 Invalid: issue should not have been added in the current state.
418 Duplicate: issue already exists in the tracker.
421 Fixed: a contributor claims to have fixed the bug. The Bug
422 Squad should check the fix with the next official binary release
423 (not by compiling the source from git). Owner should be set to
427 Verified: Bug Squad has confirmed that the issue is closed. This
428 means that nobody should ever need look at the report again -- if
429 there is any information in the issue that should be kept, open a
430 new issue for that info.
435 @subheading Owner (optional)
437 Newly-added issues should have @emph{no owner}. When a
438 contributor indicates that he has Started or Fixed an item, he
439 should become the owner.
442 @subheading Type (mandatory)
444 The issue's Type should be the first relevant item in this list.
449 Type-Collision: overlapping notation.
452 Type-Defect: a problem in the core program. (the @code{lilypond}
453 binary, scm files, fonts, etc).
456 Type-Documentation: inaccurate, missing, confusing, or desired
457 additional info. Must be fixable by editing a texinfo, ly, or scm
461 Type-Build: problem or desired features in the build system. This
462 includes the makefiles, stepmake, python scripts, and GUB.
465 Type-Scripts: problem or desired feature in the non-build-system
466 scripts. Mostly used for convert-ly, lilypond-book, etc.
469 Type-Enhancement: a feature request for the core program. The
470 distinction between enhancement and defect isn't extremely clear;
471 when in doubt, mark it as enhancement.
474 Type-Other: anything else.
479 @subheading Priority (mandatory)
481 Currently, only Critical items will block a stable release.
486 Priority-Critical: LilyPond segfaults, a regression (see below)
487 against a previous stable version or a regression against a fix
488 developed for this version. This does not apply where the
489 @qq{regression} occurred because a feature was removed
490 deliberately - this is not a bug.
493 Priority-High: An issue which produces output which does not
494 accurately reflect the input (e.g. where the user would expect
495 an accidental, but none is shown) or which produces aesthetically
496 poor output in a situation which could be expected to crop up
497 frequently in real-world music. It should not be used where the
498 problem can be avoided with a simple workaround. It can also
499 be used to flag where new code in a development version is not
500 functioning as it should. This level is also used for issues
501 which produce no output and fail to give the user a clue about
505 Priority-Medium: Normal priority - use this as the default.
508 Priority-Low: A minor problem which produces slightly undesirable
509 output, or which will only occur in contrived examples, or which
510 is very easily worked around.
513 Priority-Postponed: no fix planned. Generally used for things
514 which nobody wants to touch.
518 Note that these are initial classifications and can be subject
519 to change by others in the development team. For example, a
520 regression against an old stable version which hasn't been
521 noticed for a long time and which is unlikely to get fixed could
522 be downgraded from Priority-Critical by one of the programmers.
524 @subheading Opsys (optional)
526 Issues that only affect specific operating systems.
528 @subheading Patch (optional)
530 Normal Bug Squad members should not add or modify Patch issues;
531 leave them to the Patch Meister.
536 Patch-new: the patch has not been checked for @qq{obvious}
537 mistakes. When in doubt, use this tag.
540 Patch-review: the patch has no @qq{obvious} mistakes (as checked
541 by the Patch Meister), and is ready for review from main
544 Developers with git push ability can use this category, skipping
545 over @code{patch-new}.
548 Patch-needs_work: a developer has some concerns about the patch.
549 This does not necessarily mean that the patch must be changed; in
550 some cases, the developer's concerns can be resolved simply by
551 discussion the situation or providing notation examples.
553 If the patch is updated, the category should be changed to
554 @code{patch-new} (for normal contributors) or @code{patch-review}
555 (for developers who are very confident about their patch).
558 Patch-abandoned: the author has not responded to review comments
563 @subheading Other items (optional)
570 Regression: it used to work intentionally in an earlier
571 stable release. If the earlier output was accidental (i.e. we
572 didn't try to stop a collision, but it just so happened that two
573 grobs didn't collide), then breaking it does not count as a
576 To help decide whether the change is a regression, and therefore
577 should be Priority-Critical, please adopt the following process:
582 Are you certain the change is OK? If so, do nothing.
585 Are you certain that the change is bad? Add it to the tracker
586 as a Critical issue, regression.
589 If you're not certain either way, add it to the tracker as a
590 Critical issue, regression but be aware that it may be
591 recategorised or marked invalid.
595 In particular, anything that breaks a regression test is a
599 Frog: the fix is believed to be suitable for a new contributor
600 (does not require a great deal of knowledge about LilyPond). The
601 issue should also have an estimated time in a comment.
604 Maintainability: hinders development of LilyPond. For example,
605 improvements to the build system, or @qq{helper} python scripts.
608 Bounty: somebody is willing to pay for the fix. Only add this tag
609 if somebody has offered an exact figure in US dollars or euros.
612 Warning: graphical output is fine, but lilypond prints a
613 false/misleading warning message. Alternately, a warning should
614 be printed (such as a bar line error), but was not. Also applies
615 to warnings when compiling the source code or generating
619 Security: might potentially be used.
622 Performance: might potentially be used.
626 If you particularly want to add a label not in the list, go
627 ahead, but this is not recommended.
630 @node Adding issues to the tracker
631 @section Adding issues to the tracker
633 @warning{This should only be done by the Bug Squad or experienced
634 developers. Normal users should not do this; instead, they should
635 follow the guidelines for @rweb{Bug reports}.}
637 In order to assign labels to issues, Bug Squad members should log
638 in to their google account before adding an item.
643 Check if the issue falls into any previous category given on the
644 relevant checklists in @ref{Bug Squad checklists}. If in doubt,
645 add a new issue for a report. We would prefer to have some
646 incorrectly-added issues rather than lose information that should
650 Add the issue and classify it according to the guidelines in
651 @ref{Issue classification}. In particular, the item should have
652 @code{Status}, @code{Type-}, and @code{Priority-} labels.
654 Include output with the first applicable method:
659 If the issue has a notation example which fits in one system,
660 generate a small @file{bug.preview.png} file with:
663 lilypond -dpreview bug.ly
667 If the issue has an example which requires more than one system
668 (i.e. a spacing bug), generate a @file{bug.png} file with:
671 lilypond --png bug.ly
675 If the issue requires one or two pages of output, then generate a
676 @file{bug.png} file with the normal:
679 lilypond --png bug.ly
683 If the issue cannot be shown with less than three pages, then
684 generate a @file{bug.pdf} file with:
687 lilypond --pdf bug.ly
690 Note that this is likely to be extremely rare; most bugs should fit
691 into the first two categories above.
697 After adding the issue, please send a response email to the same
698 group(s) that the initial patch was sent to. If the initial email
699 was sent to multiple mailing lists (such as both @code{user} and
700 @code{bugs}), then reply to all those mailing lists as well. The
701 email should contain a link to the issue you just added.
708 @section Patch handling
710 @warning{This is not a Bug Squad responsibility; we have a
711 separate person handling this task.}
713 There is a single Patch Meister, and a number of Patch Helpers
714 (rename this?). The list of known patches awaiting review is:
717 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch&sort=patch}
721 @subheading Helpers: adding patches
723 The primary duty is to add patches to the google tracker; we have
724 a bad track record of losing patches in email. Patches generally
725 come to the @code{lilypond-devel} mailing list, but are sometimes
726 sent to @code{bug-lilypond}, @code{lilypond-users}, or
727 @code{frogs} mailing list instead.
731 Unless a patch is clearly in response to an existing issue, add a
732 new issue with the @code{Patch-new} label and a link to the patch
733 (either on the mailing list archives or the codereview url).
735 Issue numbers are cheap; losing developers because they got fed up
736 with us losing their hard work is expensive.
738 @c if we enter patches immediately, I don't think this is relevant.
741 Before adding a patch-reminder issue, do a quick check to see if
742 it was pushed without sending any email. This can be checked for
743 searching for relevant terms (from the patch subject or commit
744 message) on the webgit page:
747 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
752 If the patch is clearly in response to an existing issue, then
753 update that issue with the @code{Patch-new} label and a link to
754 the patch (either on the mailing list archives or the codereview
758 After adding the issue, please send a response email to the same
759 group(s) that the initial patch was sent to.
761 If the initial email was sent to multiple mailing lists (such as
762 both @code{bugs} and @code{devel}), then reply to all those
763 mailing lists as well. The email should contain a link to the
764 issue you just added.
768 @subheading Helpers: @code{Patch-review} label
770 The secondary duty is to do make sure that every issue in the
771 tracker with a @code{Patch-review} label has passed these
776 Applies automatically to git master.
778 It's ok to have offsets, but not conflicts.
781 Regtest comparison looks ok; no unexpected changes.
784 Descriptive subject line.
786 Avoid subjects like @qq{fixes 123}; instead write @qq{Doc: discuss
787 stacking-dir for BassFigureAlignment (fix 123)}.
790 Compiles docs from scratch. Only check this if you have reason to
791 suspect it might not work.
796 Check code indentation and style. This should be easier post-GOP
797 when we have a better-defined code style.
802 @subheading Patch Meister
804 The Patch Meister will:
809 send @qq{countdown} emails to
810 @code{lilypond-devel} when patches appear to be ready.
813 send general requests to review patches, or even nasty requests to
817 downgrade patches from @code{Patch-review} to
818 @code{Patch-needs_work} as appropriate.
821 downgrade patches from @code{Patch-needs_work} to
822 @code{Patch-abandoned} if no actions have been taken in four
830 @node Summary of project status
831 @section Summary of project status
833 @subsubheading Project overview
835 Grid view provides the best overview:
838 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}
841 @subsubheading Hindering development
843 These issues stop or slow development work:
846 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability&mode=grid&y=Priority&x=Type&cells=ids}
849 @subsubheading Easy tasks
851 Issues tagged with @code{Frog} indicates a task suitable for a
852 relatively new contributor. The time given is a quick
853 (inaccurate) estimate of the time required for somebody who is
854 familiar with material in this manual, but does not know anything
855 else about LilyPond development.
858 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog&mode=grid&y=Priority&x=Type&cells=ids}
861 @subsubheading Patches to review
863 Patches which have no @qq{obvious} problems:
866 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch-review}