- Add section about reporting anomalies

git-svn-id: svn://svn.gna.org/svn/sgpemv2/trunk@233 3ecf2c5c-341e-0410-92b4-d18e462d057c
This commit is contained in:
tchernobog 2006-01-27 14:11:58 +00:00
parent bf61f8bebd
commit eadc075c25
1 changed files with 206 additions and 17 deletions

View File

@ -96,9 +96,13 @@ Free Documentation License''.
@table @strong @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} @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} @item 2006, January 26th, @r{--- Matteo Settenvini}
Added reference subsection about documenting code. Added Added reference subsection about documenting code. Added
@ -182,6 +186,20 @@ The source files of SGPEM.
@chapter Writing documentation @chapter Writing documentation
@cindex 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 @section Formal documents and draft proposals
@subsection Introduction @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}. styles you should inherit from. Its name is @file{templatedocument.ott}.
@item @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 In this way all the technical documents will automatically contain the
latest up-to-date version of the Glossary. 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. 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: In order to generate documentation straight from the source code:
@subsubsection C++ code @subsection C++ code
Please refer to Doxygen manual Please refer to Doxygen manual
(@uref{http://www.stack.nl/~dimitri/doxygen/manual.html}) (@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 @code{\param} and @code{\return} to describe respectively
parameters and return value of it. parameters and return value of it.
@subsubsection Python code @subsection Python code
It is usually possible to document Python classes so that It is usually possible to document Python classes so that
calling the @code{__doc__} method of an object returns calling the @code{__doc__} method of an object returns
its documentation string. its documentation string.
Please refer to the Python manual at @uref{http://www.python.org/} Please refer to the Python manual at @uref{http://www.python.org/}
to learn more of it. 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 % -------------------------------------------------- @c % --------------------------------------------------
@ -1137,7 +1326,7 @@ as possible) abide to it.
Exceptions or revisions to guidelines due to a rework done by some other Exceptions or revisions to guidelines due to a rework done by some other
process pertain to the @acronym{KA,Knowledge Area} of 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 The committer could ask for some particular modalities in carrying out
this procedure, although unlikely (usually, it's an internal task). this procedure, although unlikely (usually, it's an internal task).