-@c -*- coding: utf-8; mode: texinfo; -*-
+Elu@c -*- coding: utf-8; mode: texinfo; -*-
@node Issues
@chapter Issues
@menu
* Introduction to issues::
-* Bug Squad setup::
-* Bug Squad checklists::
+* The Bug Squad::
* Issue classification::
* Adding issues to the tracker::
* Patch handling::
@node Introduction to issues
@section Introduction to issues
-@warning{Unless otherwise specified, all the tasks in this chapter
-are @qq{simple} tasks: they can be done by a normal user with
-nothing more than a web browser, email, and lilypond.}
+@warning{All the tasks in this chapter require no programming skills and
+can be done by anyone with a web browser, an email client and the
+ability to run LilyPond.}
+
+The term @q{issues} refers not just to software bugs but also includes
+feature requests, documentation additions and corrections as well as any
+other general code @q{TODOs} that need to be kept track of.
+
+
+@node The Bug Squad
+@section The Bug Squad
+
+@menu
+* Bug Squad setup::
+* Bug Squad checklists::
+@end menu
+
+To help keep track and organize all issues are a group of tireless
+volunteers collectively known as the @emph{Bug Squad}. Composed mainly
+of non-programmers, the Bug Squad's responsibilities include:
+
+@itemize
+
+@item
+Monitoring the LilyPond Bugs mailing list looking for any issues
+reported by other users ensuring that they are accurate and contain
+enough information for the developers to work with, preferably with
+@rweb{Tiny examples} and if applicable, screenshots.
+
+@item
+Adding new issues to the @emph{issue tracker} or updating existing
+issues with new information.
+
+@item
+Verifying issues in the @emph{issue tracker} that have been marked
+as @q{fixed}; making sure either that the fix works or (in the case of
+Documentation for example) has at least been commited to the code base.
-@qq{Issues} isn't just a politically-correct term for @qq{bug}.
-We use the same tracker for feature requests, code TODOs and
-patches, so the term @qq{bug} wouldn't be accurate. Despite the
-difference between @qq{issue} and @qq{bug}, we call our team of
-contributors who organize issues the @emph{Bug Squad}.
+@end itemize
-The Bug Squad is mainly composed of non-programmers -- their job
-is to @emph{organize} issues, not solve them. Their duties
-include removing false bug reports, ensuring that any real bug
-report contains enough information for developers, and checking
-that a developer's fix actually resolves the problem.
+The @ref{Meisters, Bug Meister} also helps check the current
+@ref{Regression tests} and highlights any significant changes (or
+problems) since the previous LilyPond release.
-New volunteers for the Bug Squad should contact the
+If you would like to be part of the Bug Squad, please contact the
@ref{Meisters, Bug Meister}.
@node Bug Squad setup
-@section Bug Squad setup
+@subsection Bug Squad setup
We highly recommend that you configure your email to use effective
sorting; this can reduce your workload @emph{immensely}. The
@node Bug Squad checklists
-@section Bug Squad checklists
+@subsection Bug Squad checklists
When you do Bug Squad work, start at the top of this page and work
your way down. Stop when you've done 20 minutes.
the currently-active Bug Squad member(s) can handle the message.
-@subsubheading Daily schedule
+@subsubheading Daily schedule as of July 2015
@example
-Monday: Ralph
-Tuesday: Eluze
-Wednesday: Brett
-Thursday: Colin Hall (disambiguation here)
-Friday: Marek
-Saturday: Brett
-Sunday: Phil
+Monday: Federico Bruni
+Tuesday: Simon Albrecht
+Wednesday: Simon Albrecht
+Thursday: Colin Campbell
+Friday:
+Saturday: Colin Campbell
+Sunday:
@end example
@itemize
@item
-Issues to verify: try to reproduce the bug with the latest
-officially released version (not one you've built yourself from
-source); if the bug is no longer there, mark the
-issue @qq{Verified} (i.e. @qq{the fix has been verified to work}).
-
-The list of items to verify is here:
+Issues to verify: go to
@example
@uref{http://code.google.com/p/lilypond/issues/list?can=7}
@end example
-You can also generate this list by selecting @qq{Issues to verify}
-from the drop-down list next to the search box.
+(You can also generate this list by selecting
+@qq{Issues to verify} from the drop-down list next to the search
+box.)
+
+You should see a list of Issues that have been claimed fixed by a
+developer. If the developer has done their job properly, the
+Issue should have a tag @qq{Fixed_mm_MM_ss}, where mm is
+the major version, MM the minor version and ss the current
+release. This will help you work out which you can verify - do
+not verify any Issues where the claimed fixed build is not yet
+released. Work your way through these as follows:
+
+If the Issue refers to a bug, try to reproduce the bug with the latest
+officially released version (not one you've built yourself from
+source); if the bug is no longer there, mark the
+issue @qq{Verified} (i.e. @qq{the fix has been verified to work}).
Quite a few of these will be issues tracking patches. @strong{You
do not have to prove these patches work - simply that they have
@uref{http://philholmes.net/lilypond/git/}
@end example
+The Issue tracker also requires that any issues labelled as
+@qq{Duplicate} are also verified. Check that the linked issue is
+a duplicate and verify the issue.
+
A few (approximately 10%) of the fixed issues relate to the
build system or fundamental architecture changes; there is no way
for you to verify these. Leave those issues alone; somebody else
will handle them.
@item
-Regression test comparison: if anything has changed suspiciously,
+The official regression test comparison is online at:
+
+@c NOTE: leave this here. In this case, it's worth duplicating
+@c the link. -gp
+@example
+@uref{http://lilypond.org/test/}
+@end example
+
+If anything has changed suspiciously,
ask if it was deliberate. If the text output from LilyPond (the
logfile) changes, the differences will be displayed with a +
before text added to the logfile and - before any text removed
randomly spaced notes and will always have different output if the
regtest checker is working.
-The official comparison is online, at:
-
-@c NOTE: leave this here. In this case, it's worth duplicating
-@c the link. -gp
-@example
-@uref{http://lilypond.org/test/}
-@end example
-
More information is available from in
@ref{Precompiled regression tests}.
@item
Type-Critical: normally a regression
-against a previous stable version or a regression against a fix
-developed for this version. This does not apply where the
+against the current stable version or the previous stable version.
+Alternatively, a regression against a fix developed for the
+current version. This does not apply where the
@qq{regression} occurred because a feature was removed
deliberately - this is not a bug.
distinction between enhancement and defect isn't extremely clear;
when in doubt, mark it as enhancement.
+@item
+Type-Patch: tracking a patch on Rietveld. Bug squad should not
+need to use this label.
+
@item
Type-Other: anything else.
Issues that only affect specific operating systems.
-@subheading Patch (optional)
+@subheading Patch label (optional)
-Normal Bug Squad members should not add or modify Patch issues;
-leave them to the Patch Meister.
+Normal Bug Squad members should not add or modify Patch issues
+except to verify them; for all other Patch work, leave them to the
+Patch Meister.
@itemize
@code{patch-new} (for normal contributors) or @code{patch-review}
(for developers who are very confident about their patch).
+@item
+Patch-countdown: final call for any patch problems
+
+@item
+Patch-push: patch has passed the countdown and should be pushed.
+
@item
Patch-abandoned: the author has not responded to review comments
for a few months.
@itemize
@item
-Regression: it used to work intentionally in an earlier
-stable release. If the earlier output was accidental (i.e. we
-didn't try to stop a collision, but it just so happened that two
-grobs didn't collide), then breaking it does not count as a
-regression.
+Regression: it used to work intentionally in the current
+stable release or the previous stable release. If the earlier
+output was accidental (i.e. we didn't try to stop a collision,
+but it just so happened that two grobs didn't collide), then
+breaking it does not count as a regression.
To help decide whether the change is a regression, please adopt
the following process:
If you particularly want to add a label not in the list, go
ahead, but this is not recommended, except when an issue is marked
-as fixed. In this case it should be labelled fixed_mm_MM_ss,
+as fixed. In this case it should be labeled Fixed_mm_MM_ss,
where mm is major version, MM minor version and ss current
release.
@item
Add the issue and classify it according to the guidelines in
@ref{Issue classification}. In particular, the item should have
-@code{Status}, @code{Type-}, and @code{Priority-} labels.
+@code{Status} and @code{Type-} labels.
Include output with the first applicable method:
@item
Images created as @file{bug.png} may be trimmed to a minimum size
by using the @code{trimtagline.sh} script, which can be found at
+
+@smallexample
@uref{https://raw.github.com/gperciva/lilypond-extra/master/bug-squad/trimtagline.sh}
+@end smallexample
@example
trimtagline.sh bug.ly
separate person handling this task.}
For contributors/developers: follow the steps in
-@ref{Commits and patches}, and @ref{Pushing to staging}.
+@ref{Commits}, @ref{Patches}, and @ref{Pushing to staging}.
+@ignore
For people doing maintenance tasks: git-cl is adding issues, James
is testing them, Colin is selecting them for countdowns, and
Patchy is merging from staging to master. In the coming weeks,
these tasks will be more and more automated.
+@end ignore
+
+@subheading Patch cycle
+
+@itemize
+
+@item
+Patches get added to the tracker and to Rietveld by the @qq{git-cl} tool, with
+a status of @qq{patch-new}.
+
+@item
+The automated tester, Patchy, verifies that the patch can be applied
+to current master. By default, it checks that the patch allows @code{make}
+and @code{make test} to complete successfully. It can also be configured to
+check that @code{make doc} is successful. If it passes, Patchy changes the
+status to @qq{patch-review} and emails the developer list. If the patch
+fails, Patchy sets it to @qq{patch-needs_work} and notifies the developer list.
+
+@item
+The Patch Meister reviews the tracker periodically, to list patches
+which have been on review for at least 24 hours. The list is found at
+
+@smallexample
+@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}
+@end smallexample
+
+@item
+For each patch, the Handler reviews any discussion on the tracker
+and on Rietveld, to determine whether the patch can go forward. If
+there is any indication that a developer thinks the patch is not
+ready, the Handler marks it @qq{patch-needs_work} and makes a comment
+regarding the reason, referring to the Rietveld item if needed.
+
+@item
+Patches with explicit approval, or at least no negative comment, can
+be updated to @qq{patch-countdown}. When saving the tracker item,
+clear the @qq{send email} box to prevent sending notification for
+each patch.
+
+@item
+The Patch Meister sends an email to the developer list, with a fixed
+subject line, to enable filtering by email clients:
+
+@example
+PATCH: Countdown to 20130113
+@end example
+
+The text of the email sets the deadline for this countdown batch. At
+present, batches are done on Tuesday, Thursday and Sunday evenings.
+
+To create the countdown announcement, use the
+@code{make-countdown-announcement.sh} script, which takes the
+deadline date, and optionally your name. Follow the instructions
+provided:
+
+@example
+cd $LILYPOND_GIT
+scripts/auxiliar/make-countdown-announcement.sh "Jan 1, 2001" James
+@end example
+
+The script produces an announcement that is easily readable in all
+email clients. Also, whenever a new contributor submits a patch,
+you will be prompted to add the new username and author name to
+the script itself, and then commit those changes to the main git
+repository.
+
+
+@item
+On the scheduled countdown day, the Patch Meister reviews the
+previous list of patches on countdown, with the same procedure and
+criteria as before. Patches with no controversy can be set to
+@qq{patch-push} with a courtesy message added to the comment block.
+
+@item
+Roughly at six month intervals, the Patch Meister can list the
+patches which have been set to @qq{patch-needs-work} and send the
+results to the developer list for review. In most cases, these
+patches should be marked @qq{patch-abandoned} but this should come
+from the developer if possible.
+
+@item
+As in most organisations of unpaid volunteers, fixed procedures are
+useful in as much as they get the job done. In our community, there
+is room for senior developers to bypass normal patch handling flows,
+particularly now that the testing of patches is largely automated.
+Similarly, the minimum age of 24 hours can reasonably be waived if
+the patch is minor and from an experienced developer.
+
+
+@end itemize
@ignore
There is a single Patch Meister, and a number of Patch Helpers
projects / lilypond.git / blobdiff