diff --git a/doc/sgpem2dman.texi b/doc/sgpem2dman.texi index 78c7f66..727659e 100644 --- a/doc/sgpem2dman.texi +++ b/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 -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 , 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).