[project @ 2005-07-18 02:09:17 by cjwatson]

Document mail interface changes for version tracking.

diff --git a/html/Developer.html.in b/html/Developer.html.in
index 2c3fa4171553c8fc4490e489c8b505ac2b165269..ab4ea80fca72ff5933b53a794c4a2f70bba015c0 100644 (file)
--- a/html/Developer.html.in
+++ b/html/Developer.html.in
@@ -36,6 +36,11 @@ and then edit the <code>To</code> field to say
 included in the default <code>To</code> field, because the $gBug system
 included it in the <code>Reply-To</code>.
 
+<p>Where applicable, please supply a <code>Version</code> line in the
+<a href="Reporting.html#pseudoheader">pseudo-header</a> of your message when
+closing a bug, so that the $gBug tracking system knows which releases of the
+package contain the fix.</p>
+
 <p>`Done' messages are automatically forwarded to the <code>$gDoneList</code>
 mailing list, if the mailing list has been set up.
 
@@ -164,8 +169,9 @@ $gBadMaintHtml
 <p>It is possible to reassign $gBug reports to other packages, to reopen
 erroneously-closed ones, to modify the information saying to where, if
 anywhere, a $gBug report has been forwarded, to change the severities
-and titles of reports, to set the ownership of bugs and to merge and
-unmerge $gBug reports.  This is done by sending mail to
+and titles of reports, to set the ownership of bugs, to merge and unmerge
+$gBug reports, and to record the versions of packages in which bugs were
+found and in which they were fixed.  This is done by sending mail to
 <code>control\@$gEmailDomain</code>.
 
 <p>The <a href="server-control.html">format of these messages</a> is

diff --git a/html/Reporting.html.in b/html/Reporting.html.in
index 01a1db00f4a5985d9d9f7e3ca9920e020262be5b..62dd09af4f2c03d4475ae1ffcf9720057ce509f2 100644 (file)
--- a/html/Reporting.html.in
+++ b/html/Reporting.html.in
@@ -77,7 +77,10 @@ has the $gBug.</p>
 Version: &lt;something&gt;
 </pre>
 
-<p>Replace <code>&lt;something&gt;</code> with the version of the package.</p>
+<p>Replace <code>&lt;something&gt;</code> with the version of the package.
+Please don't include any text here other than the version itself, as the
+$gBug tracking system relies on this field to work out which releases are
+affected by the bug.</p>
 
 <p>You need to supply a correct <code>Package</code> line in the
 pseudo-header in order for the $gBug tracking system to deliver the message

diff --git a/html/server-control.html.in b/html/server-control.html.in
index bbdcd2a748d7b9cdc9b12cca738fa047abee049b..2683d8a536133a28ab9657b44081f4a67cdac750 100644 (file)
--- a/html/server-control.html.in
+++ b/html/server-control.html.in
@@ -37,6 +37,7 @@ mailservers is available via the WWW, in
 <dl>
 
 <dt><code>reassign</code> <var>bugnumber</var> <var>package</var>
+ [ <var>version</var> ]
 
   <dd>Records that $gBug #<var>${gBug}number</var> is a $gBug in <var>package</var>.
   This can be used to set the package if the user forgot the
@@ -44,6 +45,9 @@ mailservers is available via the WWW, in
   are sent to anyone (other than the usual information in the processing
   transcript).
 
+  <p>If you supply a <var>version</var>, the $gBug tracking system will note
+  that the $gBug affects that version of the newly-assigned package.
+
 <dt><code>reopen</code> <var>bugnumber</var>
  [ <var>originator-address</var> | <code>=</code> | <code>!</code> ]
 
@@ -68,6 +72,29 @@ mailservers is available via the WWW, in
   use the <code>submitter</code> command; note that this will inform the
   original submitter of the change.
 
+  <p>If the $gBug was recorded as being closed in a particular version of a
+  package but recurred in a later version, it is better to use the
+  <code>found</code> command instead.
+
+<dt><code>found</code> <var>bugnumber</var> [ <var>version</var> ]
+
+  <dd>Record that #<var>bugnumber</var> has been encountered in the given
+  <var>version</var> of the package to which it is assigned.
+
+  <p>The $gBug tracking system uses this information, in conjunction with
+  fixed versions recorded when closing $gBugs, to display lists of $gBugs
+  open in various versions of each package. It considers a $gBug to be open
+  when it has no fixed version, or when it has been found more recently than
+  it has been fixed.
+
+  <p>If no <var>version</var> is given, then the list of fixed versions for
+  the $gBug is cleared. This is identical to the behaviour of
+  <code>reopen</code>.
+
+  <p>This command was introduced in preference to <code>reopen</code>
+  because it was difficult to add a <var>version</var> to that command's
+  syntax without suffering ambiguity.
+
 <dt><code>submitter</code> <var>bugnumber</var>
 <var>originator-address</var> | <code>!</code>
 
@@ -219,7 +246,8 @@ mailservers is available via the WWW, in
   <p>For <a href="Developer.html#tags">their meanings</a> please consult the
   general developers' documentation for the $gBug system.
 
-<dt><code>close</code> <var>bugnumber</var> (deprecated)
+<dt><code>close</code> <var>bugnumber</var> [ <var>fixed-version</var> ]
+ (deprecated)
 
   <dd>Close $gBug report #<var>bugnumber</var>.
 
@@ -231,6 +259,9 @@ mailservers is available via the WWW, in
   who reported the $gBug knows why it is being closed.
   The use of this command is therefore deprecated.
 
+  <p>If you supply a <var>fixed-version</var>, the $gBug tracking system
+  will note that the $gBug was fixed in that version of the package.
+
 <dt><code>package</code> [ <var>packagename</var> ... ]
 
   <dd>Limits the following commands so that they will only apply to bugs
@@ -243,7 +274,7 @@ mailservers is available via the WWW, in
 
   <pre>
         package foo
-        reassign 123456 bar
+        reassign 123456 bar 1.0-1
 
         package bar
         retitle 123456 bar: bar sucks

diff --git a/html/server-refcard.html.in b/html/server-refcard.html.in
index b60fd0823a49559dbb2ce9b2a0298a17acd84c45..3fcd49bbc037144eabc0f9374d1ef5925d91ffbf 100644 (file)
--- a/html/server-refcard.html.in
+++ b/html/server-refcard.html.in
@@ -54,12 +54,14 @@ sending the word <code>help</code> to each mailserver.
 <h2>Synopsis of extra commands available at control mailserver</h2>
 
 <ul compact>
-  <li><code>close</code> <var>bugnumber</var>
+  <li><code>close</code> <var>bugnumber</var> [ <var>fixed-version</var> ]
       <em>(you must separately tell originator why)</em>
   <li><code>reassign</code> <var>bugnumber</var> <var>package</var>
+      [ <var>version</var> ]
   <li><code>severity</code> <var>bugnumber</var> <var>severity</var>
   <li><code>reopen</code> <var>bugnumber</var>
       [ <var>originator-address</var> | <code>=</code> | <code>!</code> ]
+  <li><code>found</code> <var>bugnumber</var> [ <var>version</var> ]
   <li><code>submitter</code> <var>bugnumber</var>
       <var>originator-address</var> | <code>!</code>
   <li><code>forwarded</code> <var>bugnumber</var> <var>address</var>