- 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
parent
bf61f8bebd
commit
eadc075c25
|
|
@ -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
|
||||
comments.
|
||||
Added entry on initialization lists and C-style
|
||||
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
|
||||
is a file on its own (usually the @file{docs/externals/Glossary.odt}
|
||||
document in the repository), so new entries must be inserted in it.
|
||||
At the end of every document there should be a @b{Glossary}. The Glossary
|
||||
is a file on its own (usually, @file{docs/externals/Glossary.odt}
|
||||
off the repository), so new entries must be inserted into it.
|
||||
|
||||
Every technical document should include the aforementioned file.
|
||||
Please refer to the OpenOffice.org manual about @emph{Sections} to know
|
||||
how to do so. The Glossary will then be bound to the document dinamically,
|
||||
and every change on the Glossary will reflect in a change in all
|
||||
the documents that are linked to it.
|
||||
Every technical document should ``include'' the afore mentioned file.
|
||||
Please refer to the @emph{OpenOffice.org} manual about @emph{Sections} to know
|
||||
how to do so. The Glossary will then be linked to the current document
|
||||
dinamically, and every change done on the Glossary will reflect
|
||||
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.
|
||||
|
||||
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).
|
||||
|
|
|
|||
Loading…
Reference in New Issue