Doc: CG - Re-organize information about 'Patches'

[lilypond.git] / Documentation / contributor / issues.itexi

diff --git a/Documentation/contributor/issues.itexi b/Documentation/contributor/issues.itexi
index 54d57e62d29e3c9d4919f4dd2721fac41a3d7f5a..782d84d155056ec20e54c2a3e5dacec5fb53587f 100644 (file)
--- a/Documentation/contributor/issues.itexi
+++ b/Documentation/contributor/issues.itexi
@@ -1,4 +1,4 @@
-@c -*- coding: utf-8; mode: texinfo; -*-
+Elu@c -*- coding: utf-8; mode: texinfo; -*-

 @node Issues
 @chapter Issues
 
 @node Issues
 @chapter Issues
 


@@ -7,8 +7,7 @@ miscellaneous development tasks.
 
 @menu
 * Introduction to issues::
 
 @menu
 * Introduction to issues::

-* Bug Squad setup::
-* Bug Squad checklists::
+* The Bug Squad::

 * Issue classification::
 * Adding issues to the tracker::
 * Patch handling::
 * Issue classification::
 * Adding issues to the tracker::
 * Patch handling::


@@ -19,28 +18,56 @@ miscellaneous development tasks.
 @node Introduction to issues
 @section Introduction to issues
 
 @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:

 
 

-@qq{Issues} isn't just a politically-correct term for @qq{bug}.
-We use the same tracker for feature requests and code TODOs, 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}.
+@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.
+@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.

 
 

-New volunteers for the Bug Squad should contact the
+@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.
+
+@end itemize
+
+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.
+
+If you would like to be part of the Bug Squad, please contact the

 @ref{Meisters, Bug Meister}.
 
 
 @node Bug Squad setup
 @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
 
 We highly recommend that you configure your email to use effective
 sorting; this can reduce your workload @emph{immensely}.  The


@@ -78,8 +105,8 @@ Sign in to google code by clicking in the top-right corner of:
 @uref{http://code.google.com/p/lilypond/issues/list}
 @end example
 
 @uref{http://code.google.com/p/lilypond/issues/list}
 @end example
 

-You cannot log if you have Google Sharing
-@uref{http://www.googlesharing.net/} enabled.
+You cannot log on if you have Google Sharing enabled
+@uref{http://www.googlesharing.net/}.

 
 @item
 Go to your @qq{Profile}, and select @qq{Settings}.
 
 @item
 Go to your @qq{Profile}, and select @qq{Settings}.


@@ -134,10 +161,10 @@ should go into a separate @code{bug-current} folder.
 
 
 @node Bug Squad checklists
 
 
 @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
 
 When you do Bug Squad work, start at the top of this page and work

-your way down.  Stop when you've done 15 minutes.
+your way down.  Stop when you've done 20 minutes.

 
 Please use the email sorting described in @ref{Bug Squad setup}.
 This means that (as Bug Squad members) you will only ever respond
 
 Please use the email sorting described in @ref{Bug Squad setup}.
 This means that (as Bug Squad members) you will only ever respond


@@ -147,24 +174,22 @@ to emails sent or CC'd to the @code{bug-lilypond} mailing list.
 @subsubheading Emails to you personally
 
 You are not expected to work on Bug Squad matters outside of your
 @subsubheading Emails to you personally
 
 You are not expected to work on Bug Squad matters outside of your

-15 minutes, but sometimes a confused user will send a bug report
+20 minutes, but sometimes a confused user will send a bug report

 (or an update to a report) to you personally.  If that happens,
 please forward such emails to the @code{bug-lilypond} list so that
 the currently-active Bug Squad member(s) can handle the message.
 
 
 (or an update to a report) to you personally.  If that happens,
 please forward such emails to the @code{bug-lilypond} list so that
 the currently-active Bug Squad member(s) can handle the message.
 
 

-@subsubheading Daily schedule
-
-The Bug Meister is omitted from the daily schedule.
+@subsubheading Daily schedule as of July 2015

 
 @example
 
 @example

-Sunday: Colin
-Monday: Dmytro
-Tuesday: James Bailey
-Wednesday: Ralph
-Thursday: Patrick
-Friday: Urs
-Saturday: Kieren
+Monday: Federico Bruni
+Tuesday: Simon Albrecht
+Wednesday: Simon Albrecht
+Thursday: Colin Campbell
+Friday:
+Saturday: Colin Campbell
+Sunday:

 @end example
 
 
 @end example
 
 


@@ -314,37 +339,84 @@ After @strong{every release} (both stable and unstable):
 @itemize
 
 @item
 @itemize
 
 @item

-Regression test comparison: if anything has changed suspiciously,
-ask if it was deliberate.  The official comparison is online, at:
+Issues to verify: go to

 
 

-@c NOTE: leave this here.  In this case, it's worth duplicating
-@c       the link.  -gp

 @example
 @example

-@uref{http://lilypond.org/test/}
+@uref{http://code.google.com/p/lilypond/issues/list?can=7}

 @end example
 
 @end example
 

-More information is available from in
-@ref{Precompiled regression tests}.
+(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
+been pushed into the code base.}  The developer should have put
+information similar to @qq{Pushed as as
+d8fce1e1ea2aca1a82e25e47805aef0f70f511b9} in the tracker.  The
+long list of letters and numbers is called the @qq{committish}.
+Providing you can find this at the git tracker:

 
 

+@example
+@uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
+@end example

 
 

-@item
-Issues to verify: try to reproduce the bug with the latest
-official GUB version; if you cannot reproduce the bug, mark the
-item @qq{Verified} (i.e. @qq{the fix has been verified to work}).
+then you should mark the issue as verified.  A quick way of
+finding these is to enter the committish at the following address:

 
 @example
 
 @example

-@uref{http://code.google.com/p/lilypond/issues/list?can=7}
+@uref{http://philholmes.net/lilypond/git/}

 @end example
 
 @end example
 

-A few (approximately 10%) of these fixed issues relate to the
+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.
 
 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
+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
+from the logfile.  This may or may not be suspicious.
+
+There is one test designed to produce output every time the
+regtests are created. @code{test-output-distance.ly} creates
+randomly spaced notes and will always have different output if the
+regtest checker is working.
+
+More information is available from in
+@ref{Precompiled regression tests}.
+

 @item
 Check for any incorrectly-classified items in the tracker.  This
 generally just means looking at the grid to see any items without
 @item
 Check for any incorrectly-classified items in the tracker.  This
 generally just means looking at the grid to see any items without

-a Type or Priority.
+a Type.

 
 @end itemize
 
 
 @end itemize
 


@@ -386,8 +458,8 @@ same (broken) output as the initial report, then simply post a
 @section Issue classification
 
 The Bug Squad should classify issues according to the guidelines
 @section Issue classification
 
 The Bug Squad should classify issues according to the guidelines

-given by developers.  Every issue should have a Status, Type, and
-Priority; the other fields are optional.
+given by developers.  Every issue should have a Status and Type;
+the other fields are optional.

 
 @subheading Status (mandatory)
 
 
 @subheading Status (mandatory)
 


@@ -448,7 +520,23 @@ The issue's Type should be the first relevant item in this list.
 @itemize
 
 @item
 @itemize
 
 @item

-Type-Collision: overlapping notation.
+Type-Critical: normally a regression
+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.
+
+Currently, only Critical items will block a stable release.
+
+@item
+Type-Maintainability: hinders future development.
+
+@item
+Type-Crash: any input which produces a crash.
+
+@item
+Type-Ugly: overlapping or other ugly notation in graphical output.

 
 @item
 Type-Defect: a problem in the core program.  (the @code{lilypond}
 
 @item
 Type-Defect: a problem in the core program.  (the @code{lilypond}


@@ -472,12 +560,16 @@ Type-Enhancement: a feature request for the core program.  The
 distinction between enhancement and defect isn't extremely clear;
 when in doubt, mark it as enhancement.
 
 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.
 
 @end itemize
 
 @item
 Type-Other: anything else.
 
 @end itemize
 

-
+@ignore

 @subheading Priority (mandatory)
 
 Currently, only Critical items will block a stable release.
 @subheading Priority (mandatory)
 
 Currently, only Critical items will block a stable release.


@@ -523,14 +615,17 @@ regression against an old stable version which hasn't been
 noticed for a long time and which is unlikely to get fixed could
 be downgraded from Priority-Critical by one of the programmers.
 
 noticed for a long time and which is unlikely to get fixed could
 be downgraded from Priority-Critical by one of the programmers.
 

+@end ignore
+

 @subheading Opsys (optional)
 
 Issues that only affect specific operating systems.
 
 @subheading Opsys (optional)
 
 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
 
 
 @itemize
 


@@ -556,6 +651,12 @@ If the patch is updated, the category should be changed to
 @code{patch-new} (for normal contributors) or @code{patch-review}
 (for developers who are very confident about their patch).
 
 @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.
 @item
 Patch-abandoned: the author has not responded to review comments
 for a few months.


@@ -569,14 +670,14 @@ Other labels:
 @itemize
 
 @item
 @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, and therefore
-should be Priority-Critical, please adopt the following process:
+To help decide whether the change is a regression, please adopt
+the following process:

 
 @enumerate
 
 
 @enumerate
 


@@ -585,12 +686,12 @@ Are you certain the change is OK?  If so, do nothing.
 
 @item
 Are you certain that the change is bad?  Add it to the tracker
 
 @item
 Are you certain that the change is bad?  Add it to the tracker

-as a Critical issue, regression.
+as a regression.

 
 @item
 If you're not certain either way, add it to the tracker as a
 
 @item
 If you're not certain either way, add it to the tracker as a

-Critical issue, regression but be aware that it may be
-recategorised or marked invalid.
+regression but be aware that it may be recategorised or marked
+invalid.

 
 @end enumerate
 
 
 @end enumerate
 


@@ -602,10 +703,6 @@ Frog: the fix is believed to be suitable for a new contributor
 (does not require a great deal of knowledge about LilyPond).  The
 issue should also have an estimated time in a comment.
 
 (does not require a great deal of knowledge about LilyPond).  The
 issue should also have an estimated time in a comment.
 

-@item
-Maintainability: hinders development of LilyPond.  For example,
-improvements to the build system, or @qq{helper} python scripts.
-

 @item
 Bounty: somebody is willing to pay for the fix.  Only add this tag
 if somebody has offered an exact figure in US dollars or euros.
 @item
 Bounty: somebody is willing to pay for the fix.  Only add this tag
 if somebody has offered an exact figure in US dollars or euros.


@@ -618,15 +715,18 @@ to warnings when compiling the source code or generating
 documentation.
 
 @item
 documentation.
 
 @item

-Security: might potentially be used.
+Security: security risk.

 
 @item
 
 @item

-Performance: might potentially be used.
+Performance: performance issue.

 
 @end itemize
 
 If you particularly want to add a label not in the list, go
 
 @end itemize
 
 If you particularly want to add a label not in the list, go

-ahead, but this is not recommended.
+ahead, but this is not recommended, except when an issue is marked
+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.

 
 
 @node Adding issues to the tracker
 
 
 @node Adding issues to the tracker


@@ -651,7 +751,7 @@ have been added.
 @item
 Add the issue and classify it according to the guidelines in
 @ref{Issue classification}.  In particular, the item should have
 @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:
 
 
 Include output with the first applicable method:
 


@@ -681,6 +781,18 @@ If the issue requires one or two pages of output, then generate a
 lilypond --png bug.ly
 @end example
 
 lilypond --png bug.ly
 @end example
 

+@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
+@end example
+

 @item
 If the issue cannot be shown with less than three pages, then
 generate a @file{bug.pdf} file with:
 @item
 If the issue cannot be shown with less than three pages, then
 generate a @file{bug.pdf} file with:


@@ -689,8 +801,8 @@ generate a @file{bug.pdf} file with:
 lilypond --pdf bug.ly
 @end example
 
 lilypond --pdf bug.ly
 @end example
 

-Note that this is likely to be extremely rare; most bugs should fit
-into the first two categories above.
+Note that this is likely to be extremely rare; most bugs should
+fit into the first two categories above.

 
 
 @end itemize
 
 
 @end itemize


@@ -705,129 +817,22 @@ email should contain a link to the issue you just added.
 @end enumerate
 
 
 @end enumerate
 
 

-

 @node Patch handling
 @section Patch handling
 
 @warning{This is not a Bug Squad responsibility; we have a
 separate person handling this task.}
 
 @node Patch handling
 @section Patch handling
 
 @warning{This is not a Bug Squad responsibility; we have a
 separate person handling this task.}
 

-There is a single Patch Meister, and a number of Patch Helpers
-(rename this?).  The list of known patches awaiting review is:
-
-@example
-@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch&sort=patch}
-@end example
-
-
-@subheading Helpers: adding patches
-
-The primary duty is to add patches to the google tracker; we have
-a bad track record of losing patches in email.  Patches generally
-come to the @code{lilypond-devel} mailing list, but are sometimes
-sent to @code{bug-lilypond}, @code{lilypond-users}, or
-@code{frogs} mailing list instead.
+For contributors/developers: follow the steps in
+@ref{Patches}, and @ref{Pushing to staging}.

 
 

-@itemize
-@item
-Unless a patch is clearly in response to an existing issue, add a
-new issue with the @code{Patch-new} label and a link to the patch
-(either on the mailing list archives or the codereview url).
-
-Issue numbers are cheap; losing developers because they got fed up
-with us losing their hard work is expensive.
-
-@c if we enter patches immediately, I don't think this is relevant.

 @ignore
 @ignore

-@item
-Before adding a patch-reminder issue, do a quick check to see if
-it was pushed without sending any email.  This can be checked for
-searching for relevant terms (from the patch subject or commit
-message) on the webgit page:
-
-@example
-@uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
-@end example
+For people doing maintenance tasks: git-cl is adding issues, James
+is testing patches and managing the Patch countdown.  He also generally
+runs the scripts that merging to Staging (although other developers are
+available to do this task if required).

 @end ignore
 
 @end ignore
 

-@item
-If the patch is clearly in response to an existing issue, then
-update that issue with the @code{Patch-new} label and a link to
-the patch (either on the mailing list archives or the codereview
-url).
-
-@item
-After adding the issue, please send a response email to the same
-group(s) that the initial patch was sent to.
-
-If the initial email was sent to multiple mailing lists (such as
-both @code{bugs} and @code{devel}), then reply to all those
-mailing lists as well.  The email should contain a link to the
-issue you just added.
-
-@end itemize
-
-@subheading Helpers: @code{Patch-review} label
-
-The secondary duty is to do make sure that every issue in the
-tracker with a @code{Patch-review} label has passed these
-@qq{obvious} tests:
-
-@itemize
-@item
-Applies automatically to git master.
-
-It's ok to have offsets, but not conflicts.
-
-@item
-Regtest comparison looks ok; no unexpected changes.
-
-@item
-Descriptive subject line.
-
-Avoid subjects like @qq{fixes 123}; instead write @qq{Doc: discuss
-stacking-dir for BassFigureAlignment (fix 123)}.
-
-@item
-Compiles docs from scratch.  Only check this if you have reason to
-suspect it might not work.
-
-@item
-(maybe)
-
-Check code indentation and style.  This should be easier post-GOP
-when we have a better-defined code style.
-
-@end itemize
-
-
-@subheading Patch Meister
-
-The Patch Meister will:
-
-@itemize
-
-@item
-send @qq{countdown} emails to
-@code{lilypond-devel} when patches appear to be ready.
-
-@item
-send general requests to review patches, or even nasty requests to
-review patches.
-
-@item
-downgrade patches from @code{Patch-review} to
-@code{Patch-needs_work} as appropriate.
-
-@item
-downgrade patches from @code{Patch-needs_work} to
-@code{Patch-abandoned} if no actions have been taken in four
-weeks.
-
-@end itemize
-
-
-

 
 @node Summary of project status
 @section Summary of project status
 
 @node Summary of project status
 @section Summary of project status


@@ -836,17 +841,17 @@ weeks.
 
 Grid view provides the best overview:
 
 
 Grid view provides the best overview:
 

-@example
+@smallexample

 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}
 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}

-@end example
+@end smallexample

 
 @subsubheading Hindering development
 
 These issues stop or slow development work:
 
 
 @subsubheading Hindering development
 
 These issues stop or slow development work:
 

-@example
-@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability&mode=grid&y=Priority&x=Type&cells=ids}
-@end example
+@smallexample
+@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability}
+@end smallexample

 
 @subsubheading Easy tasks
 
 
 @subsubheading Easy tasks
 


@@ -856,9 +861,9 @@ relatively new contributor.  The time given is a quick
 familiar with material in this manual, but does not know anything
 else about LilyPond development.
 
 familiar with material in this manual, but does not know anything
 else about LilyPond development.
 

-@example
-@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog&mode=grid&y=Priority&x=Type&cells=ids}
-@end example
+@smallexample
+@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog}
+@end smallexample

 
 @subsubheading Patches to review
 
 
 @subsubheading Patches to review