]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/contributor/issues.itexi
01cce81411de184e9b780b2883a34bd27e29bf61
[lilypond.git] / Documentation / contributor / issues.itexi
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @node Issues
3 @chapter Issues
4
5 This chapter deals with defects, feature requests, and
6 miscellaneous development tasks.
7
8 @menu
9 * Introduction to issues::
10 * Bug Squad overview::
11 * Bug Squad setup::
12 * Bug Squad checklists::
13 * Issue classification::
14 * Adding issues to the tracker::
15 * Patch handling::
16 * Summary of project status::
17 @end menu
18
19
20 @node Introduction to issues
21 @section Introduction to issues
22
23 @warning{Unless otherwise specified, all the tasks in this chapter
24 are @qq{simple} tasks: they can be done by a normal user with
25 nothing more than a web browser, email, and lilypond.}
26
27 @qq{Issues} isn't just a politically-correct term for @qq{bug}.
28 We use the same tracker for feature requests, code TODOs and
29 patches, so the term @qq{bug} wouldn't be accurate.  Despite the
30 difference between @qq{issue} and @qq{bug}, we call our team of
31 contributors who organize issues the @emph{Bug Squad}.
32
33 The Bug Squad is mainly composed of non-programmers -- their job
34 is to @emph{organize} issues, not solve them.  Their duties
35 include removing false bug reports, ensuring that any real bug
36 report contains enough information for developers, and checking
37 that a developer's fix actually resolves the problem.
38
39 New volunteers for the Bug Squad should contact the
40 @ref{Meisters, Bug Meister}.
41
42 @node Bug Squad overview
43 @section Bug Squad overview
44
45 The Bug Squad are volunteers who progress issue tracking using the
46 Google Issue tracker at
47
48 @example
49 @uref{http://code.google.com/p/lilypond/issues/list}
50 @end example
51
52 Bug Squad members have 2 primary responsiblities:
53
54 @enumerate
55
56 @item
57 Monitoring the LilyPond Bugs mailing list and adding to the
58 tracker any new issues reported there.
59
60 @item
61 Verifying issues that are claimed fixed by a developer, to ensure
62 that the fix works, and is actually in the code base.
63
64 @end enumerate
65
66 It's also part of the Bug Squad's responsibility to check that
67 the Regression Tests don't show up any problems in the latest
68 release.  The Bug Meister currently does this.
69
70 All of this is explained in more detail in the following sections.
71
72 @node Bug Squad setup
73 @section Bug Squad setup
74
75 We highly recommend that you configure your email to use effective
76 sorting; this can reduce your workload @emph{immensely}.  The
77 email folders names were chosen specifically to make them work if
78 you sort your folders alphabetically.
79
80 @enumerate
81
82 @item
83 Read every section of this chapter, @ref{Issues}.
84
85 @item
86 If you do not have one already, create a gmail account and send
87 the email address to the @ref{Meisters, Bug Meister}.
88
89 @item
90 Subscribe your gmail account to @code{bug-lilypond}.
91
92 @item
93 Configure your google code account:
94
95 @enumerate
96
97 @item
98 Wait until your gmail account is listed in:
99
100 @example
101 @uref{http://code.google.com/p/lilypond/people/list}
102 @end example
103
104 @item
105 Sign in to google code by clicking in the top-right corner of:
106
107 @example
108 @uref{http://code.google.com/p/lilypond/issues/list}
109 @end example
110
111 You cannot log on if you have Google Sharing enabled
112 @uref{http://www.googlesharing.net/}.
113
114 @item
115 Go to your @qq{Profile}, and select @qq{Settings}.
116
117 @item
118 Scroll down to @qq{Issue change notification}, and make sure that
119 you have @emph{selected} @qq{If I starred the issue}.
120
121 @end enumerate
122
123 @item
124 Configure your email client:
125
126 @enumerate
127
128 @item
129 Any email sent with your gmail address in the @code{To:} or
130 @code{CC:} fields should go to a @code{bug-answers} folder.
131
132 When setting up your filtering rules, be aware that Google Code
133 might use different versions of your email address, such as ones
134 ending in @code{@@googlemail.com} or @code{@@gmail.com}.
135
136 @item
137 Any other email either from, or CC'd to,
138
139 @example
140 lilypond@@googlecode.com
141 @end example
142
143 @noindent
144 should go into a separate @code{bug-ignore} folder.  Alternately,
145 you may automatically delete these emails.
146
147 You will @strong{not read} these emails as part of your Bug Squad
148 duties.  If you are curious, go ahead and read them later, but it
149 does @strong{not} count as Bug Squad work.
150
151 @item
152 Any other email sent to (or CC'd to):
153
154 @example
155 bug-lilypond
156 @end example
157
158 @noindent
159 should go into a separate @code{bug-current} folder.
160
161 @end enumerate
162
163 @end enumerate
164
165
166 @node Bug Squad checklists
167 @section Bug Squad checklists
168
169 When you do Bug Squad work, start at the top of this page and work
170 your way down.  Stop when you've done 20 minutes.
171
172 Please use the email sorting described in @ref{Bug Squad setup}.
173 This means that (as Bug Squad members) you will only ever respond
174 to emails sent or CC'd to the @code{bug-lilypond} mailing list.
175
176
177 @subsubheading Emails to you personally
178
179 You are not expected to work on Bug Squad matters outside of your
180 20 minutes, but sometimes a confused user will send a bug report
181 (or an update to a report) to you personally.  If that happens,
182 please forward such emails to the @code{bug-lilypond} list so that
183 the currently-active Bug Squad member(s) can handle the message.
184
185
186 @subsubheading Daily schedule
187
188 @example
189 Monday:    Eluze
190 Tuesday:   Ralph
191 Wednesday: Marek
192 Thursday:  Joe Wakeling (soon)
193 Friday:    Colin H
194 Saturday:  Colin H
195 Sunday:    Federico
196 @end example
197
198
199 @subsubheading Emails to @code{bug-answers}
200
201 Some of these emails will be comments on issues that you added to
202 the tracker.
203
204 @itemize
205 If they are asking for more information, give the additional
206 information.
207
208 @item
209 If the email says that the issue was classified in some other
210 manner, read the rationale given and take that into account for
211 the next issue you add.
212
213 @item
214 Otherwise, move them to your @code{bug-ignore} folder.
215
216 @end itemize
217
218 Some of these emails will be discussions about Bug Squad work;
219 read those.
220
221
222 @subsubheading Emails to @code{bug-current}
223
224 Dealing with these emails is your main task.  Your job is to get
225 rid of these emails in the first method which is applicable:
226
227 @enumerate
228 @item
229 If the email has already been handled by a Bug Squad member (i.e.
230 check to see who else has replied to it), delete it.
231
232 @item
233 If the email is a question about how to use LilyPond, reply with
234 this response:
235
236 @example
237 For questions about how to use LilyPond, please read our
238 documentation available from:
239   @uref{http://lilypond.org/website/manuals.html}
240 or ask the lilypond-user mailing list.
241 @end example
242
243 @item
244 If the email mentions @qq{the latest git}, or any version number
245 that has not yet been officially released, forward it to
246 @code{lilypond-devel}.
247
248 @item
249 If a bug report is not in the form of a Tiny example, direct the
250 user to resubmit the report with this response:
251
252 @example
253 I'm sorry, but due to our limited resources for handling bugs, we
254 can only accept reports in the form of Tiny examples.  Please see
255 step 2 in our bug reporting guidelines:
256   @uref{http://lilypond.org/website/bug-reports.html}
257 @end example
258
259 @item
260 If anything is unclear, ask the user for more information.
261
262 How does the graphical output differ from what the user expected?
263 What version of lilypond was used (if not given) and operating
264 system (if this is a suspected cause of the problem)?  In short,
265 if you cannot understand what the problem is, ask the user to
266 explain more.  It is the user's responsibility to explain the
267 problem, not your responsibility to understand it.
268
269 @item
270 If the behavior is expected, the user should be told to read the
271 documentation:
272
273 @example
274 I believe that this is the expected behaviour -- please read our
275 documentation about this topic.  If you think that it really is a
276 mistake, please explain in more detail.  If you think that the
277 docs are unclear, please suggest an improvement as described by
278 @qq{Simple tasks -- Documentation} on:
279   @uref{http://lilypond.org/website/help-us.html}
280 @end example
281
282 @item
283 If the issue already exists in the tracker, send an email to that
284 effect:
285
286 @example
287 This issue has already been reported; you can follow the
288 discussion and be notified about fixes here:
289 @end example
290
291 @noindent
292 (copy+paste the google code issue URL)
293
294 @item
295 Accept the report as described in
296 @ref{Adding issues to the tracker}.
297
298 @end enumerate
299
300 All emails should be CC'd to the @code{bug-lilypond} list so that
301 other Bug Squad members know that you have processed the email.
302
303 @warning{There is no option for @qq{ignore the bug report} -- if
304 you cannot find a reason to reject the report, you must accept
305 it.}
306
307
308 @ignore
309 @c Try omitting this from Bug Squad duties
310
311 @subheading Updates / discussion about issues
312
313 We try to keep discussions about issues on the tracker, but
314 sometimes it spills over onto email.  If discussion has ended with
315 no patch / resolution and at least @strong{3 days} have passed,
316 then either:
317
318 @itemize
319
320 @item
321 Summarize the recent discussion on the tracker, and add a link to
322 the original discussion.
323
324 @item
325 Add the comment @qq{there was some technical discussion which I
326 could not understand}, and include a link to the original
327 discussion.
328
329 We do not expect Bug Squad members to be programmers, or even to
330 be moderately-skilled users.  Your job is to keep track of issue
331 reports; it is @emph{perfectly acceptable} to not understand
332 discussions between advanced users and/or developers.
333
334 @end itemize
335 @end ignore
336
337
338 @subheading Regular maintenance
339
340 After @strong{every release} (both stable and unstable):
341
342 @itemize
343
344 @item
345 Issues to verify: go to
346
347 @example
348 @uref{http://code.google.com/p/lilypond/issues/list?can=7}
349 @end example
350
351 (You can also generate this list by selecting
352 @qq{Issues to verify} from the drop-down list next to the search
353 box.)
354
355 You should see a list of Issues that have been claimed fixed by a
356 developer.  If the developer has done their job properly, the
357 Issue should have a tag @qq{Fixed_mm_MM_ss}, where mm is
358 the major version, MM the minor version and ss the current
359 release.  This will help you work out which you can verify - do
360 not verify any Issues where the claimed fixed build is not yet
361 released.  Work your way through these as follows:
362
363 If the Issue refers to a bug, try to reproduce the bug with the latest
364 officially released version (not one you've built yourself from
365 source); if the bug is no longer there, mark the
366 issue @qq{Verified} (i.e. @qq{the fix has been verified to work}).
367
368 Quite a few of these will be issues tracking patches.  @strong{You
369 do not have to prove these patches work - simply that they have
370 been pushed into the code base.}  The developer should have put
371 information similar to @qq{Pushed as as
372 d8fce1e1ea2aca1a82e25e47805aef0f70f511b9} in the tracker.  The
373 long list of letters and numbers is called the @qq{committish}.
374 Providing you can find this at the git tracker:
375
376 @example
377 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
378 @end example
379
380 then you should mark the issue as verified.  A quick way of
381 finding these is to enter the committish at the following address:
382
383 @example
384 @uref{http://philholmes.net/lilypond/git/}
385 @end example
386
387 The Issue tracker also requires that any issues labelled as
388 @qq{Duplicate} are also verified.  Check that the linked issue is
389 a duplicate and verify the issue.
390
391 A few (approximately 10%) of the fixed issues relate to the
392 build system or fundamental architecture changes; there is no way
393 for you to verify these.  Leave those issues alone; somebody else
394 will handle them.
395
396 @item
397 The official regression test comparison is online at:
398
399 @c NOTE: leave this here.  In this case, it's worth duplicating
400 @c       the link.  -gp
401 @example
402 @uref{http://lilypond.org/test/}
403 @end example
404
405 If anything has changed suspiciously,
406 ask if it was deliberate.  If the text output from LilyPond (the
407 logfile) changes, the differences will be displayed with a +
408 before text added to the logfile and - before any text removed
409 from the logfile.  This may or may not be suspicious.
410
411 There is one test designed to produce output every time the
412 regtests are created. @code{test-output-distance.ly} creates
413 randomly spaced notes and will always have different output if the
414 regtest checker is working.
415
416 More information is available from in
417 @ref{Precompiled regression tests}.
418
419 @item
420 Check for any incorrectly-classified items in the tracker.  This
421 generally just means looking at the grid to see any items without
422 a Type.
423
424 @end itemize
425
426
427 @ignore
428 @c try omitting from daily tasks for now. -gp
429
430 @subheading Irregular maintenance
431
432 @warning{These tasks are a lot of work; gathering more volunteers
433 to help is definitely recommended.  However, the Bug Squad should
434 handle the organization and training of new volunteers.}
435
436 Once every year or two:
437
438 @itemize
439
440 @item
441 Checking all regtests: although we have a system for checking the
442 regtests between two versions, occasionally a bug will slip
443 through the cracks.  It is therefore good to manually examine all
444 the regtests (compare the images to the text description).  More
445 information is available from in @ref{Regression tests}.
446
447
448 @item
449 Checking all issues: we try to mark each Issue @q{fixed} when we
450 fix it, but occasionally one or two issues will slip through the
451 cracks.  It is therefore good to check all Issues.  If you see the
452 same (broken) output as the initial report, then simply post a
453 @qq{Problem still exists in 2.x.y} message to the issue.
454
455 @end itemize
456
457 @end ignore
458
459
460 @node Issue classification
461 @section Issue classification
462
463 The Bug Squad should classify issues according to the guidelines
464 given by developers.  Every issue should have a Status and Type;
465 the other fields are optional.
466
467 @subheading Status (mandatory)
468
469 Open issues:
470
471 @itemize
472
473 @item
474 New: the item was added by a non-member, despite numerous warnings
475 not to do this.  Should be reviewed by a member of the Bug Squad.
476
477 @item
478 Accepted: the Bug Squad added it, or reviewed the item.
479
480 @item
481 Started: a contributor is working on a fix.  Owner should change
482 to be this contributor.
483
484 @end itemize
485
486
487 Closed issues:
488
489 @itemize
490
491 @item
492 Invalid: issue should not have been added in the current state.
493
494 @item
495 Duplicate: issue already exists in the tracker.
496
497 @item
498 Fixed: a contributor claims to have fixed the bug.  The Bug
499 Squad should check the fix with the next official binary release
500 (not by compiling the source from git).  Owner should be set to
501 that contributor.
502
503 @item
504 Verified: Bug Squad has confirmed that the issue is closed.  This
505 means that nobody should ever need look at the report again -- if
506 there is any information in the issue that should be kept, open a
507 new issue for that info.
508
509 @end itemize
510
511
512 @subheading Owner (optional)
513
514 Newly-added issues should have @emph{no owner}.  When a
515 contributor indicates that he has Started or Fixed an item, he
516 should become the owner.
517
518
519 @subheading Type (mandatory)
520
521 The issue's Type should be the first relevant item in this list.
522
523 @itemize
524
525 @item
526 Type-Critical: normally a regression
527 against the current stable version or the previous stable version.
528 Alternatively, a regression against a fix developed for the
529 current version. This does not apply where the
530 @qq{regression} occurred because a feature was removed
531 deliberately - this is not a bug.
532
533 Currently, only Critical items will block a stable release.
534
535 @item
536 Type-Maintainability: hinders future development.
537
538 @item
539 Type-Crash: any input which produces a crash.
540
541 @item
542 Type-Ugly: overlapping or other ugly notation in graphical output.
543
544 @item
545 Type-Defect: a problem in the core program.  (the @code{lilypond}
546 binary, scm files, fonts, etc).
547
548 @item
549 Type-Documentation: inaccurate, missing, confusing, or desired
550 additional info.  Must be fixable by editing a texinfo, ly, or scm
551 file.
552
553 @item
554 Type-Build: problem or desired features in the build system.  This
555 includes the makefiles, stepmake, python scripts, and GUB.
556
557 @item
558 Type-Scripts: problem or desired feature in the non-build-system
559 scripts.  Mostly used for convert-ly, lilypond-book, etc.
560
561 @item
562 Type-Enhancement: a feature request for the core program.  The
563 distinction between enhancement and defect isn't extremely clear;
564 when in doubt, mark it as enhancement.
565
566 @item
567 Type-Patch: tracking a patch on Rietveld.  Bug squad should not
568 need to use this label.
569
570 @item
571 Type-Other: anything else.
572
573 @end itemize
574
575 @ignore
576 @subheading Priority (mandatory)
577
578 Currently, only Critical items will block a stable release.
579
580 @itemize
581
582 @item
583 Priority-Critical: LilyPond segfaults, a regression (see below)
584 against a previous stable version or a regression against a fix
585 developed for this version. This does not apply where the
586 @qq{regression} occurred because a feature was removed
587 deliberately - this is not a bug.
588
589 @item
590 Priority-High: An issue which produces output which does not
591 accurately reflect the input (e.g. where the user would expect
592 an accidental, but none is shown) or which produces aesthetically
593 poor output in a situation which could be expected to crop up
594 frequently in real-world music.  It should not be used where the
595 problem can be avoided with a simple workaround.  It can also
596 be used to flag where new code in a development version is not
597 functioning as it should.  This level is also used for issues
598 which produce no output and fail to give the user a clue about
599 what's wrong.
600
601 @item
602 Priority-Medium: Normal priority - use this as the default.
603
604 @item
605 Priority-Low: A minor problem which produces slightly undesirable
606 output, or which will only occur in contrived examples, or which
607 is very easily worked around.
608
609 @item
610 Priority-Postponed: no fix planned.  Generally used for things
611 which nobody wants to touch.
612
613 @end itemize
614
615 Note that these are initial classifications and can be subject
616 to change by others in the development team.  For example, a
617 regression against an old stable version which hasn't been
618 noticed for a long time and which is unlikely to get fixed could
619 be downgraded from Priority-Critical by one of the programmers.
620
621 @end ignore
622
623 @subheading Opsys (optional)
624
625 Issues that only affect specific operating systems.
626
627 @subheading Patch label (optional)
628
629 Normal Bug Squad members should not add or modify Patch issues
630 except to verify them; for all other Patch work, leave them to the
631 Patch Meister.
632
633 @itemize
634
635 @item
636 Patch-new: the patch has not been checked for @qq{obvious}
637 mistakes.  When in doubt, use this tag.
638
639 @item
640 Patch-review: the patch has no @qq{obvious} mistakes (as checked
641 by the Patch Meister), and is ready for review from main
642 developers.
643
644 Developers with git push ability can use this category, skipping
645 over @code{patch-new}.
646
647 @item
648 Patch-needs_work: a developer has some concerns about the patch.
649 This does not necessarily mean that the patch must be changed; in
650 some cases, the developer's concerns can be resolved simply by
651 discussion the situation or providing notation examples.
652
653 If the patch is updated, the category should be changed to
654 @code{patch-new} (for normal contributors) or @code{patch-review}
655 (for developers who are very confident about their patch).
656
657 @item
658 Patch-countdown: final call for any patch problems
659
660 @item
661 Patch-push: patch has passed the countdown and should be pushed.
662
663 @item
664 Patch-abandoned: the author has not responded to review comments
665 for a few months.
666
667 @end itemize
668
669 @subheading Other items (optional)
670
671 Other labels:
672
673 @itemize
674
675 @item
676 Regression: it used to work intentionally in the current
677 stable release or the previous stable release.  If the earlier
678 output was accidental (i.e. we didn't try to stop a collision,
679 but it just so happened that two grobs didn't collide), then
680 breaking it does not count as a regression.
681
682 To help decide whether the change is a regression, please adopt
683 the following process:
684
685 @enumerate
686
687 @item
688 Are you certain the change is OK?  If so, do nothing.
689
690 @item
691 Are you certain that the change is bad?  Add it to the tracker
692 as a regression.
693
694 @item
695 If you're not certain either way, add it to the tracker as a
696 regression but be aware that it may be recategorised or marked
697 invalid.
698
699 @end enumerate
700
701 In particular, anything that breaks a regression test is a
702 regression.
703
704 @item
705 Frog: the fix is believed to be suitable for a new contributor
706 (does not require a great deal of knowledge about LilyPond).  The
707 issue should also have an estimated time in a comment.
708
709 @item
710 Bounty: somebody is willing to pay for the fix.  Only add this tag
711 if somebody has offered an exact figure in US dollars or euros.
712
713 @item
714 Warning: graphical output is fine, but lilypond prints a
715 false/misleading warning message.  Alternately, a warning should
716 be printed (such as a bar line error), but was not.  Also applies
717 to warnings when compiling the source code or generating
718 documentation.
719
720 @item
721 Security: security risk.
722
723 @item
724 Performance: performance issue.
725
726 @end itemize
727
728 If you particularly want to add a label not in the list, go
729 ahead, but this is not recommended, except when an issue is marked
730 as fixed.  In this case it should be labeled Fixed_mm_MM_ss,
731 where mm is major version, MM minor version and ss current
732 release.
733
734
735 @node Adding issues to the tracker
736 @section Adding issues to the tracker
737
738 @warning{This should only be done by the Bug Squad or experienced
739 developers.  Normal users should not do this; instead, they should
740 follow the guidelines for @rweb{Bug reports}.}
741
742 In order to assign labels to issues, Bug Squad members should log
743 in to their google account before adding an item.
744
745 @enumerate
746
747 @item
748 Check if the issue falls into any previous category given on the
749 relevant checklists in @ref{Bug Squad checklists}.  If in doubt,
750 add a new issue for a report.  We would prefer to have some
751 incorrectly-added issues rather than lose information that should
752 have been added.
753
754 @item
755 Add the issue and classify it according to the guidelines in
756 @ref{Issue classification}.  In particular, the item should have
757 @code{Status} and @code{Type-} labels.
758
759 Include output with the first applicable method:
760
761 @itemize
762
763 @item
764 If the issue has a notation example which fits in one system,
765 generate a small @file{bug.preview.png} file with:
766
767 @example
768 lilypond -dpreview bug.ly
769 @end example
770
771 @item
772 If the issue has an example which requires more than one system
773 (i.e. a spacing bug), generate a @file{bug.png} file with:
774
775 @example
776 lilypond --png bug.ly
777 @end example
778
779 @item
780 If the issue requires one or two pages of output, then generate a
781 @file{bug.png} file with the normal:
782
783 @example
784 lilypond --png bug.ly
785 @end example
786
787 @item
788 Images created as @file{bug.png} may be trimmed to a minimum size
789 by using the @code{trimtagline.sh} script, which can be found at
790
791 @smallexample
792 @uref{https://raw.github.com/gperciva/lilypond-extra/master/bug-squad/trimtagline.sh}
793 @end smallexample
794
795 @example
796 trimtagline.sh bug.ly
797 @end example
798
799 @item
800 If the issue cannot be shown with less than three pages, then
801 generate a @file{bug.pdf} file with:
802
803 @example
804 lilypond --pdf bug.ly
805 @end example
806
807 Note that this is likely to be extremely rare; most bugs should
808 fit into the first two categories above.
809
810
811 @end itemize
812
813 @item
814 After adding the issue, please send a response email to the same
815 group(s) that the initial patch was sent to.  If the initial email
816 was sent to multiple mailing lists (such as both @code{user} and
817 @code{bugs}), then reply to all those mailing lists as well.  The
818 email should contain a link to the issue you just added.
819
820 @end enumerate
821
822
823
824 @node Patch handling
825 @section Patch handling
826
827 @warning{This is not a Bug Squad responsibility; we have a
828 separate person handling this task.}
829
830 For contributors/developers: follow the steps in
831 @ref{Commits and patches}, and @ref{Pushing to staging}.
832
833 @ignore
834 For people doing maintenance tasks: git-cl is adding issues, James
835 is testing them, Colin is selecting them for countdowns, and
836 Patchy is merging from staging to master.  In the coming weeks,
837 these tasks will be more and more automated.
838 @end ignore
839
840 @subheading Patch cycle
841
842 @itemize
843
844 @item
845 Patches get added to the tracker and to Rietveld by the @qq{git-cl} tool, with
846 a status of @qq{patch-new}.
847
848 @item
849 The automated tester, Patchy, verifies that the patch can be applied
850 to current master.  By default, it checks that the patch allows @code{make}
851 and @code{make test} to complete successfully.  It can also be configured to
852 check that @code{make doc} is successful. If it passes, Patchy changes the
853 status to @qq{patch-review} and emails the developer list.  If the patch
854 fails, Patchy sets it to @qq{patch-needs_work} and notifies the developer list.
855
856 @item
857 The Patch Meister reviews the tracker periodically, to list patches
858 which have been on review for at least 24 hours. The list is found at
859
860 @smallexample
861 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch%20patch=review&sort=modified+patch&colspec=ID%20Type%20Status%20Priority%20Owner%20Patch%20Summary%20Modified}
862 @end smallexample
863
864 @item
865 For each patch, the Handler reviews any discussion on the tracker
866 and on Rietveld, to determine whether the patch can go forward.  If
867 there is any indication that a developer thinks the patch is not
868 ready, the Handler marks it @qq{patch-needs_work} and makes a comment
869 regarding the reason, referring to the Rietveld item if needed.
870
871 @item
872 Patches with explicit approval, or at least no negative comment, can
873 be updated to @qq{patch-countdown}.  When saving the tracker item,
874 clear the @qq{send email} box to prevent sending notification for
875 each patch.
876
877 @item
878 The Patch Meister sends an email to the developer list, with a fixed
879 subject line, to enable filtering by email clients:
880
881 @example
882 PATCH: Countdown to 20130113
883 @end example
884
885 The text of the email sets the deadline for this countdown batch.  At
886 present, batches are done on Tuesday, Thursday and Sunday evenings.
887
888 The body of the email lists the patches grouped by patch type, and for
889 each patch, shows the tracker issue number and title, with a link to
890 the Rietveld item.  Copying the information from the website and pasting
891 into the email gives a hyperlinked version of the information.
892
893 @smallexample
894
895 For 20:00 MST Tuesday January 8:
896
897 Crash:
898     Issue 2990: \RemoveEmptyStaves in StaffGroup context crashes - R 7069044
899
900 Defect:
901     Issue 677: \score markup confuses paper settings - R 7028045
902     Issue 3050: displayLilyMusic produced erroneous code for rightHandFinger arguments - R 7032045
903
904 Documentation:
905     Issue 2952: Upgrade documentation of \once - R 7031053
906     Issue 3044: Dual license the files under mf/ using OFL. - R 6970046
907     Issue 3084: [DOC]Add "Known issue" in NR 1.2.1 about Scaling durations with rational numbers - R 7071044
908
909 Enhancement:
910     Issue 3061: make \articulate handle colon-type tremolos - R 7033045
911     Issue 3082: Patch: Let ChordNameVoice use the same performers as Voice - R 7054043
912     Issue 3083: Patch: Chord change detection in fretboards should depend on placements, not notes - R 7062043
913     Issue 2983: assertion failed with \glissando - R 6625078
914
915
916 Cheers,
917 Colin
918
919 @end smallexample
920
921 @item
922 On the scheduled countdown day, the Patch Meister reviews the
923 previous list of patches on countdown, with the same procedure and
924 criteria as before.  Patches with no controversy can be set to
925 @qq{patch-push} with a courtesy message added to the comment block.
926
927 @item
928 Roughly at six month intervals, the Patch Meister can list the
929 patches which have been set to @qq{patch-needs-work} and send the
930 results to the developer list for review.  In most cases, these
931 patches should be marked @qq{patch-abandoned} but this should come
932 from the developer if possible.
933
934 @item
935 As in most organisations of unpaid volunteers, fixed procedures are
936 useful in as much as they get the job done.  In our community, there
937 is room for senior developers to bypass normal patch handling flows,
938 particularly now that the testing of patches is largely automated.
939 Similarly, the minimum age of 24 hours can reasonably be waived if
940 the patch is minor and from an experienced developer.
941
942
943 @end itemize
944
945 @ignore
946 There is a single Patch Meister, and a number of Patch Helpers
947 (rename this?).  The list of known patches awaiting review is:
948
949 @example
950 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch&sort=patch}
951 @end example
952
953
954 @subheading Helpers: adding patches
955
956 The primary duty is to add patches to the google tracker; we have
957 a bad track record of losing patches in email.  Patches generally
958 come to the @code{lilypond-devel} mailing list, but are sometimes
959 sent to @code{bug-lilypond}, @code{lilypond-users}, or
960 @code{frogs} mailing list instead.
961
962 @itemize
963 @item
964 Unless a patch is clearly in response to an existing issue, add a
965 new issue with the @code{Patch-new} label and a link to the patch
966 (either on the mailing list archives or the codereview url).
967
968 Issue numbers are cheap; losing developers because they got fed up
969 with us losing their hard work is expensive.
970
971 @end ignore
972 @c if we enter patches immediately, I don't think this is relevant.
973 @ignore
974 @item
975 Before adding a patch-reminder issue, do a quick check to see if
976 it was pushed without sending any email.  This can be checked for
977 searching for relevant terms (from the patch subject or commit
978 message) on the webgit page:
979
980 @example
981 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
982 @end example
983 @end ignore
984 @ignore
985
986 @item
987 If the patch is clearly in response to an existing issue, then
988 update that issue with the @code{Patch-new} label and a link to
989 the patch (either on the mailing list archives or the codereview
990 url).
991
992 @item
993 After adding the issue, please send a response email to the same
994 group(s) that the initial patch was sent to.
995
996 If the initial email was sent to multiple mailing lists (such as
997 both @code{bugs} and @code{devel}), then reply to all those
998 mailing lists as well.  The email should contain a link to the
999 issue you just added.
1000
1001 @end itemize
1002
1003 @subheading Helpers: @code{Patch-review} label
1004
1005 The secondary duty is to do make sure that every issue in the
1006 tracker with a @code{Patch-review} label has passed these
1007 @qq{obvious} tests:
1008
1009 @itemize
1010 @item
1011 Applies automatically to git master.
1012
1013 It's ok to have offsets, but not conflicts.
1014
1015 @item
1016 Regtest comparison looks ok; no unexpected changes.
1017
1018 @item
1019 Descriptive subject line.
1020
1021 Avoid subjects like @qq{fixes 123}; instead write @qq{Doc: discuss
1022 stacking-dir for BassFigureAlignment (fix 123)}.
1023
1024 @item
1025 Compiles docs from scratch.  Only check this if you have reason to
1026 suspect it might not work.
1027
1028 @item
1029 (maybe)
1030
1031 Check code indentation and style.  This should be easier post-GOP
1032 when we have a better-defined code style.
1033
1034 @end itemize
1035
1036
1037 @subheading Patch Meister
1038
1039 The Patch Meister will:
1040
1041 @itemize
1042
1043 @item
1044 send @qq{countdown} emails to
1045 @code{lilypond-devel} when patches appear to be ready.
1046
1047 @item
1048 send general requests to review patches, or even nasty requests to
1049 review patches.
1050
1051 @item
1052 downgrade patches from @code{Patch-review} to
1053 @code{Patch-needs_work} as appropriate.
1054
1055 @item
1056 downgrade patches from @code{Patch-needs_work} to
1057 @code{Patch-abandoned} if no actions have been taken in four
1058 weeks.
1059
1060 @end itemize
1061
1062 @end ignore
1063
1064
1065 @node Summary of project status
1066 @section Summary of project status
1067
1068 @subsubheading Project overview
1069
1070 Grid view provides the best overview:
1071
1072 @smallexample
1073 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}
1074 @end smallexample
1075
1076 @subsubheading Hindering development
1077
1078 These issues stop or slow development work:
1079
1080 @smallexample
1081 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability}
1082 @end smallexample
1083
1084 @subsubheading Easy tasks
1085
1086 Issues tagged with @code{Frog} indicates a task suitable for a
1087 relatively new contributor.  The time given is a quick
1088 (inaccurate) estimate of the time required for somebody who is
1089 familiar with material in this manual, but does not know anything
1090 else about LilyPond development.
1091
1092 @smallexample
1093 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog}
1094 @end smallexample
1095
1096 @subsubheading Patches to review
1097
1098 Patches which have no @qq{obvious} problems:
1099
1100 @example
1101 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch-review}
1102 @end example
1103
1104
1105