Requirements.howto
The requirements document is maintained as an html page on the development web site. The current address is http://viper-toolkit.sf.net/developers/requirements/. To edit the document, log into SourceForge using your member account through SSH. Each leaf in the tree that is linked to a specific requirement should be linked to the relevant request for enhancement on SourceForge.
All changed should be noted. New requirements should include a note
with the format: <div class="note">$note$ —
$username$</div>. These comments should be repeated in the
RCS log. Minor changes can
have comments placed in the RCS log alone. Changes to a requirement
should be mostly for clarification. If a requirement has already been
instantiated in the code, and you are changing the meaning of it, you
should first consider deleting it and adding a new requirement. This is
easier to maintain with the
RFE system, where you can
mark an RFE as invalid and open a new one, and keeps the one-to-one
correspondence between RFEs and atomic requirements.
If you remove a requirement, you should change the class on its html
list element to be removed. The fault style-sheet for the
requirements document will include: li[class~="removed"]
{display: none;} Another style-sheet may display them with
strikethrough or a different background color. You should include a note
in the format above, describing why the requirement was removed.
Each requirement should have a descriptive XHTML ID on its list element. This should be related to the name of the descriptor or to the RFE ID that tracks the implementation of the requirement. This allows direct linking under changes to the tree, which are mostly organizational and should not have much of an impact on the implementation itself. If anything, such changes will be in response to the realities of the code.
Each atomic requirement should link to a SourceForge RFE. There is a
javascript that writes the links; it searches for
<a class="rfelink">number</a>
and adds the appropriate hrefs, so you don't have to copy and paste the
SourceForge bug URL.
Higher-level nodes on the requirement tree may link to RFEs that track
several features and related bugs. I might come up with a JavaScript to
semi-automate this process of aggregating bug ids. When we have a better
specifications document and a better JavaDoc process, we may link these
in as well. I would also like to link to the places in the
documentation that describe each feature. I'll see what I can do about
converting the documentation to a format amenable to hypertext
links.
Remember that the page should be valid XHTML. Before you check in
your changes to the page, make sure to click on the W3C: XHTML
link at the bottom to check the validity with the w3's validator.