4995: Remove 2016 projects from GSoC page on website

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

diff --git a/Documentation/contributor/issues.itexi b/Documentation/contributor/issues.itexi
index 86976fd3242f450e6f3da96f91e78b2551f0702c..434ead511a139e1181b417f0cfb7997e4da18ae6 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,122 +18,137 @@ 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.}
-
-@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}.
+@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 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 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.

 
 

-New volunteers for the Bug Squad should contact the
-@ref{Meisters, Bug Meister}.

 
 

+@node The Bug Squad
+@section The Bug Squad

 
 

-@node Bug Squad setup
-@section Bug Squad setup
+@menu
+* Bug Squad setup::
+* Bug Squad checklists::
+@end menu

 
 

-We highly recommend that you configure your email to use effective
-sorting; this can reduce your workload @emph{immensely}.  The
-email folders names were chosen specifically to make them work if
-you sort your folders alphabetically.
+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:

 
 

-@enumerate
+@itemize

 
 @item
 
 @item

-Read every section of this chapter, @ref{Issues}.
+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
 
 @item

-If you do not have one already, create a gmail account and send
-the email address to the @ref{Meisters, Bug Meister}.
+Adding new issues to the @emph{issue tracker} or updating existing
+issues with new information.

 
 @item
 
 @item

-Subscribe your gmail account to @code{bug-lilypond}.
+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.

 
 

-@item
-Configure your google code account:
+@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
+@subsection Bug Squad setup
+
+We highly recommend that you configure your email client to use some
+kind of sorting and filtering as this will significantly reduce and
+simplify your workload.  Suggested email folder names are mentioned
+below to work when sorted alphabetically.

 
 @enumerate
 
 @item
 
 @enumerate
 
 @item

-Wait until your gmail account is listed in:
+Read every section of the @ref{Issues} chapter in this guide.

 
 

-@example
-@uref{http://code.google.com/p/lilypond/people/list}
-@end example
+@item
+Subscribe your email account to @code{bug-lilypond}.  See
+@uref{https://lists.gnu.org/mailman/listinfo/bug-lilypond}.

 
 @item
 
 @item

-Sign in to google code by clicking in the top-right corner of:
+Send your email address to the @ref{Meisters, Bug Meister}.

 
 

-@example
-@uref{http://code.google.com/p/lilypond/issues/list}
-@end example
+@item
+Create your own Sourceforge login (required for the Allura issue
+tracker):

 
 

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

 
 @item
 
 @item

-Go to your @qq{Profile}, and select @qq{Settings}.
+Go to @uref{https://sourceforge.net/p/testlilyissues/issues/}

 
 @item
 
 @item

-Scroll down to @qq{Issue change notification}, and make sure that
-you have @emph{selected} @qq{If I starred the issue}.
+Click on 'Join' in the top-right corner.

 
 

-@end enumerate
+@item
+Fill in your details as required and click the @emph{Register} button to
+complete the registration.
+
+@end itemize
+
+@item
+Send your Sourceforge @emph{username} (not your email address) to
+@email{bug-lilypond@@gnu.org} asking to be given appropriate permissions
+to either create, edit and comment on tracker issues.

 
 @item
 Configure your email client:
 
 
 @item
 Configure your email client:
 

-@enumerate
+@itemize

 
 @item
 
 @item

-Any email sent with your gmail address in the @code{To:} or
-@code{CC:} fields should go to a @code{bug-answers} folder.
-
-When setting up your filtering rules, be aware that Google Code
-might use different versions of your email address, such as ones
-ending in @code{@@googlemail.com} or @code{@@gmail.com}.
+Any email sent with your address in the @code{To:} or @code{CC:} fields
+should be configured to go into a @code{bug-answers} folder.

 
 @item
 
 @item

-Any other email either from, or CC'd to,
+Any email either @code{From:} or @code{CC:} to,

 
 @example
 
 @example

-lilypond@@googlecode.com
+testlilyissues-auto@@lists.sourceforge.net

 @end example
 
 @noindent
 @end example
 
 @noindent

-should go into a separate @code{bug-ignore} folder.  Alternately,
-you may automatically delete these emails.
-
-You will @strong{not read} these emails as part of your Bug Squad
-duties.  If you are curious, go ahead and read them later, but it
-does @strong{not} count as Bug Squad work.
+should be configured to go into a @code{bug-ignore} folder or,
+alternately, configure your email client to delete these automatically.
+You do @emph{not} need to read mails in the @code{bug-ignore} folder.
+If you are curious (and have time) then read them, but they are not
+necessary for Bug Squad work.

 
 @item
 
 @item

-Any other email sent to (or CC'd to):
+Any email sent @code{To:} or @code{CC:} to,

 
 @example
 bug-lilypond
 @end example
 
 @noindent
 
 @example
 bug-lilypond
 @end example
 
 @noindent

-should go into a separate @code{bug-current} folder.
+should be configured to go into a @code{bug-current} folder.

 
 

-@end enumerate
+@end itemize

 
 @end enumerate
 
 
 @node Bug Squad checklists
 
 @end enumerate
 
 
 @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.
 
 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.


@@ -153,16 +167,16 @@ please forward such emails to the @code{bug-lilypond} list so that
 the currently-active Bug Squad member(s) can handle the message.
 
 
 the currently-active Bug Squad member(s) can handle the message.
 
 

-@subsubheading Daily schedule
+@subsubheading Daily schedule as of July 2015

 
 @example
 
 @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: Ralph Palmer
+Saturday: Colin Campbell
+Sunday:

 @end example
 
 
 @end example
 
 


@@ -312,19 +326,33 @@ After @strong{every release} (both stable and unstable):
 @itemize
 
 @item
 @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}).
+Issues to verify: go to
+
+@smallexample
+@uref{https://sourceforge.net/p/testlilyissues/issues/search/?q=status%3AFixed}
+@end smallexample
+
+(You can also generate this list by selecting the @qq{Open (Fixed)}
+button down the left-hand frame)

 
 

-The list of items to verify is here:
+You should see a list of Issues that have been marked as 'Fixed' by a
+developer.  If the developer has done their job properly, the
+Issue should have the @qq{Labels} field filled in with @qq{Fixed_x_y_z},
+where X is the major version, y the minor version and z the current
+release.

 
 @example
 
 @example

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

 @end example
 
 @end example
 

-You can also generate this list by selecting @qq{Issues to verify}
-from the drop-down list next to the search box.
+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
 
 Quite a few of these will be issues tracking patches.  @strong{You
 do not have to prove these patches work - simply that they have


@@ -345,13 +373,25 @@ finding these is to enter the committish at the following address:
 @uref{http://philholmes.net/lilypond/git/}
 @end example
 
 @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
 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
 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


@@ -362,14 +402,6 @@ regtests are created. @code{test-output-distance.ly} creates
 randomly spaced notes and will always have different output if the
 regtest checker is working.
 
 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}.
 
 More information is available from in
 @ref{Precompiled regression tests}.
 


@@ -481,8 +513,9 @@ The issue's Type should be the first relevant item in this list.
 
 @item
 Type-Critical: normally a regression
 
 @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.
 
 @qq{regression} occurred because a feature was removed
 deliberately - this is not a bug.
 


@@ -519,6 +552,10 @@ 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.
 
 @item
 Type-Other: anything else.
 


@@ -576,10 +613,11 @@ be downgraded from Priority-Critical by one of the programmers.
 
 Issues that only affect specific operating systems.
 
 
 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
 


@@ -605,6 +643,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.


@@ -618,11 +662,11 @@ 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, please adopt
 the following process:
 
 To help decide whether the change is a regression, please adopt
 the following process:


@@ -672,7 +716,7 @@ Performance: performance issue.
 
 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
 
 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.
 
 where mm is major version, MM minor version and ss current
 release.
 


@@ -699,7 +743,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:
 


@@ -732,7 +776,10 @@ lilypond --png bug.ly
 @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
 @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}
 @uref{https://raw.github.com/gperciva/lilypond-extra/master/bug-squad/trimtagline.sh}

+@end smallexample

 
 @example
 trimtagline.sh bug.ly
 
 @example
 trimtagline.sh bug.ly


@@ -762,7 +809,6 @@ email should contain a link to the issue you just added.
 @end enumerate
 
 
 @end enumerate
 
 

-

 @node Patch handling
 @section Patch handling
 
 @node Patch handling
 @section Patch handling
 


@@ -770,171 +816,87 @@ email should contain a link to the issue you just added.
 separate person handling this task.}
 
 For contributors/developers: follow the steps in
 separate person handling this task.}
 
 For contributors/developers: follow the steps in

-@ref{Commits and patches}, and @ref{Pushing to staging}.
-
-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.
-
-@ignore
-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.
-
-@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.
+@ref{Patches}, and @ref{Pushing to staging}.

 
 

-@end ignore
-@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

-@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.
+@node Summary of project status
+@section Summary of project status

 
 

-@end itemize
+@subsubheading Project overview

 
 

+Project activity

 
 

-@subheading Patch Meister
+@smallexample
+@uref{https://sourceforge.net/projects/testlilyissues/}
+@end smallexample

 
 

-The Patch Meister will:
+@subsubheading Hindering development

 
 

-@itemize
+These issues stop or slow development work:

 
 

-@item
-send @qq{countdown} emails to
-@code{lilypond-devel} when patches appear to be ready.
+@smallexample
+@uref{https://sourceforge.net/p/testlilyissues/issues/search/?q=status:Accepted%20AND%20_type:Maintainability}
+@end smallexample

 
 

-@item
-send general requests to review patches, or even nasty requests to
-review patches.
+@subsubheading Easy tasks

 
 

-@item
-downgrade patches from @code{Patch-review} to
-@code{Patch-needs_work} as appropriate.
+Issues tagged with @code{Frog} indicates a task suitable for a
+relatively new contributor.  The time given is a quick (and probably
+inaccurate) estimate of the time required for somebody who is familiar
+with material in this manual, but does not know anything else about
+LilyPond development.

 
 

-@item
-downgrade patches from @code{Patch-needs_work} to
-@code{Patch-abandoned} if no actions have been taken in four
-weeks.
+@smallexample
+@uref{https://sourceforge.net/p/testlilyissues/issues/search/?q=status:Accepted%20AND%20labels:Frog}
+@end smallexample

 
 

-@end itemize
+@subsubheading Patches currently in the Patch Review cycle

 
 

-@end ignore
+Overview

 
 

+@c The following URL is provided by one of the Developers giving a much
+@c easier way to see all patches at all stages of the Review cycle in a
+@c single place.

 
 

-@node Summary of project status
-@section Summary of project status
+@example
+http://philholmes.net/lilypond/allura/
+@end example

 
 

-@subsubheading Project overview

 
 

-Grid view provides the best overview:
+@noindent
+New patches

 
 @smallexample
 
 @smallexample

-@uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}
+@uref{https://sourceforge.net/p/testlilyissues/issues/search/?q=status%3AStarted+AND+_patch%3Anew}

 @end smallexample
 
 @end smallexample
 

-@subsubheading Hindering development

 
 

-These issues stop or slow development work:
+@noindent
+Patches under Review

 
 @smallexample
 
 @smallexample

-@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability}
+@uref{https://sourceforge.net/p/testlilyissues/issues/search/?q=status%3AStarted+AND+_patch%3Areview}

 @end smallexample
 
 @end smallexample
 

-@subsubheading Easy tasks

 
 

-Issues tagged with @code{Frog} indicates a task suitable for a
-relatively new contributor.  The time given is a quick
-(inaccurate) estimate of the time required for somebody who is
-familiar with material in this manual, but does not know anything
-else about LilyPond development.
+@noindent
+Patches on final Countdown

 
 @smallexample
 
 @smallexample

-@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog}
+@uref{https://sourceforge.net/p/testlilyissues/issues/search/?q=status%3AStarted+AND+_patch%3Acountdown}

 @end smallexample
 
 @end smallexample
 

-@subsubheading Patches to review
-
-Patches which have no @qq{obvious} problems:
-
-@example
-@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch-review}
-@end example
-

 
 

+@noindent
+Patches that can be pushed

 
 

+@smallexample
+@uref{https://sourceforge.net/p/testlilyissues/issues/search/?q=status%3AStarted+AND+_patch%3Apush}
+@end smallexample