Add notes on bug triage procedure

* CONTRIBUTE: In section on the issue tracker, point to new triage file.
* admin/notes/triage: New file explaining triage procedure.

diff --git a/CONTRIBUTE b/CONTRIBUTE
index b385d68c985ee340460d0bb20369d8980e8e13b9..0c0ef207ff3f97350b6101d8d9908c8c08a7568d 100644 (file)
--- a/CONTRIBUTE
+++ b/CONTRIBUTE
@@ -222,6 +222,17 @@ the tracker with the corresponding bugs/issues.
 GNU ELPA has a 'debbugs' package that allows accessing the tracker
 database from Emacs.
 
+Bugs needs regular attention.  A large backlog of bugs is
+disheartening to the developers, and a culture of ignoring bugs is
+harmful to users, who expect software that works.  Bugs have to be
+regularly looked at and acted upon.  Not all bugs are critical, but at
+the least, each bug needs to be regularly re-reviewed to make sure it
+is still reproducible.
+
+The process of going through old or new bugs and acting on them is
+called bug triage.  This process is described in the file
+admin/notes/triage.
+
 ** Document your changes.
 
 Any change that matters to end-users should have an entry in etc/NEWS.

diff --git a/admin/notes/triage b/admin/notes/triage
new file mode 100644 (file)
index 0000000..bc91b6c
--- /dev/null
+++ b/admin/notes/triage
@@ -0,0 +1,68 @@
+HOW TO TRIAGE EMACS BUGS  -*- outline -*-
+
+This document just describes the procedure of triaging bugs, for information on
+how to work with the bug tracker, see the bugtracker file in this same directory
+for the basics.  You can also install the debbugs ELPA package for access to M-x
+debbugs-gnu, an emacs interface to debbugs, and M-x debbugs-org, an emacs
+interface via org-mode.
+
+* Bug backlog triage procedure
+
+The goal of this triage is to prune down the list of old bugs, closing
+the ones that are not reproducible on the current release.
+
+  1. To start, enter debbugs mode (either debbugs-gnu, debbugs-org, or via the
+     web browser), and accept the default list option of bugs that have severity
+     serious, important, or normal.
+  2. This will also show closed bugs that have yet to be archived.  You can
+     filter these out in debbugs-gnu with "x" (debbugs-gnu-toggle-suppress).
+  3. For each bug, do the following:
+     - Read the mail thread for the bug.  Find out if anyone has been able to
+       reproduce this on the current release.
+     - If someone has been able to, then your work is finished for this bug.
+     - Make sure there's enough information to reproduce the bug.  It should be
+       very clear how to reproduce.  If not, please ask for specific steps to
+       reproduce.  If you don't get them, and you can't reproduce without them,
+       you can close as "doneunreproducible".
+     - If no one has mentioned being able to reproduce on the current release,
+       read the bug description and attempt to reproduce on an emacs started
+       with "emacs -Q" (the goal is to not let our personal configs interfere
+       with bug testing).
+     - If you can reproduce, then reply on the thread (either on the original
+       message, or anywhere you find appropriate) that you can reproduce this on
+       the current release. If your reproduction gives additional info (such as
+       a backtrace), then add that as well, since it will help whoever attempts
+       to fix it.
+     - If you can't reproduce, state that you can't reproduce it on the current
+       release, ask if they can try again against the current release.  Tag the
+       bug as "unreproducable".  Wait a few weeks for their reply - if they can
+       reproduce it, then that's great, otherwise close as "doneunreproducible".
+     - If the bug ends up still open, make sure the priority and other tags
+       seems reasonable.
+  4. Your changes will take some time to take effect.  After a period of minutes
+     to hours, you will get a mail telling you the control message has been
+     processed.  At this point, if there were no errors detected, you and
+     everyone else can see your changes. If there are errors, read the error
+     text - if you need help, consulting the bugtracker documentation in this
+     same directory.
+
+* New bug triage process
+
+The goal of the new bug triage process is similar to the backlog triage process,
+except that the focus is on prioritizing the bug, and making sure it is has
+necessary information for others to act on.
+
+For each new bug, ask the following questions:
+
+  1. Is the bug report written in a way to be easy to reproduce (starts from
+     emacs -Q, etc.)?  If not, ask the reporter to try and reproduce it on an
+     emacs without customization.
+  2. Is the bug report written against the lastest emacs?  If not, try to
+     reproduce on the latest version, and if it can't be reproduced, ask the
+     reporter to try again with the latest version.
+  3. Is the bug the same as another bug?  If so, merge the bugs.
+  4. What is the priority of the bug?  Add a priority: critical, grave, serious,
+     important, normal, minor, or wishlist.
+  5. Who should be the owner?  This depends on what component the bug is part
+     of.  You can look at the admin/MAINTAINERS file (then you can just search
+     emacs-devel to match the name with an email address).