- Add section about reporting anomalies

git-svn-id: svn://svn.gna.org/svn/sgpemv2/trunk@233 3ecf2c5c-341e-0410-92b4-d18e462d057c

doc/sgpem2dman.texi

@@ -96,9 +96,13 @@ Free Documentation License''.
 
 @table @strong
 
+@item 2006, January 27th, @r{--- Matteo Settenvini, Djina Verbanac}
+Add section about conventions to be followed when 
+documenting anomalies.
+
 @item 2006, January 27th, @r{--- Luca Vezzaro}
-Added point on initialization lists and C-style 
+Added entry on initialization lists and C-style 
-comments.
+comments in C++ Coding Style section.
 
 @item 2006, January 26th, @r{--- Matteo Settenvini}
 Added reference subsection about documenting code. Added
@@ -182,6 +186,20 @@ The source files of SGPEM.
 @chapter Writing documentation
 @cindex  documentation
 
+@menu 
+
+* Formal documents and draft proposals:: How a good document is formed
+
+* Documenting code:: Style and norms to automagically generate 
+                     documentation from code
+
+* Reporting anomalies:: When something goes wrong
+
+@end menu
+
+@c % ---- new section
+
+@node    Formal documents and draft proposals, Documenting code, Writing documentation, Writing documentation
 @section Formal documents and draft proposals
 
 @subsection Introduction
@@ -269,15 +287,15 @@ there's an OpenOffice.org @b{template} with some already defined
 styles you should inherit from. Its name is @file{templatedocument.ott}.
 
 @item
-At the end of every document there must be a @b{Glossary}. The Glossary 
+At the end of every document there should be a @b{Glossary}. The Glossary 
-is a file on its own (usually the @file{docs/externals/Glossary.odt} 
+is a file on its own (usually, @file{docs/externals/Glossary.odt} 
-document in the repository), so new entries must be inserted in it.
+off the repository), so new entries must be inserted into it.
 
-Every technical document should include the aforementioned file. 
+Every technical document should ``include'' the afore mentioned file. 
-Please refer to the OpenOffice.org manual about @emph{Sections} to know
+Please refer to the @emph{OpenOffice.org} manual about @emph{Sections} to know
-how to do so. The Glossary will then be bound to the document dinamically,
+how to do so. The Glossary will then be linked to the current document 
-and every change on the Glossary will reflect in a change in all
+dinamically, and every change done on the Glossary will reflect 
-the documents that are linked to it.
+in an automatical update in every linker.
 
 In this way all the technical documents will automatically contain the 
 latest up-to-date version of the Glossary.
@@ -314,13 +332,14 @@ includes all Fonts and Styles established. It also has a foundation for all
 the pages mentioned above.
 
 
-@c % ---- new subsection 
+@c % ---- new section 
 
-@subsection Documenting code
+@node    Documenting code, Reporting anomalies, Formal documents and draft proposals, Writing documentation
+@section Documenting code
 
 In order to generate documentation straight from the source code:
 
-@subsubsection C++ code
+@subsection C++ code
 
 Please refer to Doxygen manual 
 (@uref{http://www.stack.nl/~dimitri/doxygen/manual.html}) 
@@ -335,15 +354,185 @@ In particular, for functions and methods, you should use
 @code{\param} and @code{\return} to describe respectively
 parameters and return value of it.
 
-@subsubsection Python code
+@subsection Python code
 
 It is usually possible to document Python classes so that
 calling the @code{__doc__} method of an object returns
 its documentation string. 
-
 Please refer to the Python manual at @uref{http://www.python.org/}
 to learn more of it.
 
+However, if we want to generate good documentation straight
+from code with Doxygen, we should use the @samp{#} documenting
+style. Please look at the end of 
+@uref{http://www.stack.nl/~dimitri/doxygen/docblocks.html} for an example.
+
+@c % ----- new subsection
+
+@node    Reporting anomalies, (none), Documenting code, Writing documentation
+@section Reporting anomalies
+
+@emph{Note}: sometimes we will refer to an anomaly with the less-formal
+term ``@emph{bug}''.
+
+Anomaly documentation is divided in two parts. The first part concerns the 
+@b{Anomaly Investigation} record and the second one the @b{Anomaly Resolution} record. 
+All informations about Anomalies are held in the Appendix section of 
+the document named @file{AnomalyRecords.odt}. If you find an anomaly you should start 
+a new page and create a header as follows:
+
+@table @strong
+
+@item ID
+Identification number of the anomaly, a unique integer
+
+@item Summary
+A one-liner with a summary of the contents of the anomaly
+
+@item Severity
+This field describes the impact of a bug.
+     
+     @table @samp
+     @item Blocker 	
+     Blocks development and/or testing work
+     @item Critical 	
+     crashes, loss of data, severe memory leak
+     @item Major 	
+     major loss of function
+     @item Minor 	
+     minor loss of function, or other problem where easy workaround is present
+     @item Trivial 	
+     cosmetic problem like misspelled words or misaligned text
+     @item Enhancement 	
+     Request for enhancement
+     @end table
+
+@item Reporter
+Name and email of the person who discovered the Anomaly
+
+@item Date of Identification
+GMT time at witch the anomaly was identified
+
+@item Product type and version
+Product (with version number) affected by the anomaly (e.g., architecture, 
+design, code, documentation, @dots{}).
+
+@item Status
+Please choose one and only one of the following states.
+
+These are used @strong{before} a resolution:
+
+      @table @samp
+
+      @item UNCONFIRMED
+      This bug has recently been added to the database. Nobody has validated that 
+      this bug is true. Users who have the "canconfirm" permission set may confirm 
+      this bug, changing its state to @samp{NEW}. Or, it may be directly resolved 
+      and marked @samp{RESOLVED}. 
+      
+      @item NEW
+      This bug has recently been added to the assignee's list of bugs and must be 
+      processed. Bugs in this state may be accepted, and become @samp{ASSIGNED}, 
+      passed on to someone else, and remain @samp{NEW}, or resolved and marked 
+      @samp{RESOLVED}. 
+
+      @item ASSIGNED
+      This bug is not yet resolved, but is assigned to the proper person. From here 
+      bugs can be given to another person and become @samp{NEW}, or resolved and 
+      become @samp{RESOLVED}. 
+      
+      @item REOPENED
+      This bug was once resolved, but the resolution was deemed incorrect. For example, 
+      a bug is @samp{REOPENED} when more information shows up and the bug is now 
+      reproducible. From here bugs are either marked @samp{ASSIGNED} or 
+      @samp{RESOLVED}.
+
+      @end table
+
+Instead, @strong{after} a resolution, the state should change to:
+      
+      @table @samp
+      
+      @item RESOLVED
+      A resolution has been taken, and it is awaiting verification by @acronym{QA}. 
+      From here bugs are either re-opened and become @samp{REOPENED}, are marked 
+      @samp{VERIFIED}, or are closed for good and marked @samp{CLOSED}.
+      
+      @item VERIFIED
+      @acronym{QA} has looked at the bug and the resolution and agrees that the 
+      appropriate resolution has been taken. Bugs remain in this state until the product 
+      they were reported against actually ships, at which point they become @samp{CLOSED}.
+
+      @item CLOSED
+      The bug is considered dead, the resolution is correct. Any zombie bugs who choose 
+      to walk the earth again must do so by becoming @samp{REOPENED}.
+
+      @end table
+
+@item Assigned to
+Who's working to resolve this anomaly, name and email. Usually, it's initially left empty.
+
+@item Description and comments
+Latin creativity at work -- text describing the reasons for assuming 
+the presence of an anomaly. Please be as clear as possible. Unfortunately, giving guidelines in this
+sense is quite difficult @enddots{}
+
+As for follow-ups, always start with the name of the editor, email and the timestamp
+of the comment, assigning a numerical ID to it.
+An example of a comment would be:
+@example
+  --- Comment #1, Slartibartfast <slarti@@email.com>, 2006 Jan 27th - 16:13 ----
+  Okay, I'll fix the timespace continuum yesterday. Just give me the time to 
+  repair my spaceship, will you?
+@end example
+
+@strong{Important}: please report clearly in a comment if you change any 
+field of the anomaly header.
+
+@end table
+
+When the anomaly is resolved, a footer to it is added, with:
+
+@table @strong
+@item Date
+Timestamp of the resolution date
+
+@item Resolution
+Choose one and only one of these tags. Please remember to change bug state 
+accordingly and to report you've done so in a comment.
+
+    @table @samp
+
+    @item FIXED
+    A fix for this bug is checked into the tree and tested. 
+
+    @item INVALID
+    The problem described is not a bug. 
+    
+    @item WONTFIX
+    The problem described is a bug which will never be fixed. 
+
+    @item DUPLICATE
+    The problem is a duplicate of an existing bug. Marking a bug duplicate requires 
+    the bug# of the duplicating bug and will at least put that bug number in the 
+    description field. 
+
+    @item WORKSFORME
+    All attempts at reproducing this bug were futile, and reading the code produces 
+    no clues as to why the described behavior would occur. If more information appears 
+    later, the bug can be reopened. 
+
+    @item MOVED
+    The problem was specific to a related product whose bugs are tracked in another 
+    bug database. The bug has been moved to that database.
+
+    @end table
+
+
+@item Fixed by
+Usually it's the same person as the assignee.
+
+@end table
 
 @c % --------------------------------------------------
 
@@ -1137,7 +1326,7 @@ as possible) abide to it.
 
 Exceptions or revisions to guidelines due to a rework done by some other
 process pertain to the @acronym{KA,Knowledge Area} of 
-Process Improvement (see @acronym{SWEBOK} §9).
+Process Improvement (see @acronym{SWEBOK} §9).
 
 The committer could ask for some particular modalities in carrying out
 this procedure, although unlikely (usually, it's an internal task).