From Software Standards and Policies

Policy on Trac Usage for DM Documentation

While we want to foster open source development and trac is central to this purpose, there are certain caveats on what should and shouldn't be posted to the trac twiki since all material is open to the public. All trac users should ensure the following:

Review the material you have posted on the trac twiki to be sure there is nothing that is confidential, or that could be embarrassing or used against the project. Confidential material would include (for example) partnering plans or proposals that are confidential or have not yet been realized, financial information, positioning relative to other projects, or comments about strengths or weaknesses relative to other projects.

LSST project-level documents such as the SDP, Security Design, and Fault-tolerance Design that are not yet approved by the LSST CCB, should be labeled as DRAFT and a note should appear in every page footer that indicates no trac twiki documents are approved until they have a Docushare document-ID. When the document-ID is assigned, the trac twiki version should either provide only a link to the approved document on Docushare or insert the document-ID and change the access to read-only.

The DM System Manager is responsible for oversight ensuring that trac only has appropriate material. The entire DM team is expected to help with this oversight; if you see something that is suspect, please bring it to the attention of the DM System Manager.

Rationale behind the Policy

A proposal for Twiki / Docushare management of LSST project-wide baselined documents was suggested:

• a document is created and maintained on trac twiki;
• the document is submitted for approval by the LSST CCB
• the document is twiki-output to a PDF (or similar output standard) and installed on Docushare.
• the Docushare document-ID is embedded in the twiki version, the DRAFT designation is removed, and then the twiki version is read-locked.
• further modifications to the document may be done on trac twiki only if the twiki document is relabelled: DRAFT REVISION simultaneously with resetting read/write access permissions;
• then the cycle restarts from the beginning.

Once an LSST-baselined document is frozen for review and submitted to the LSST configuration control process in Docushare for approval, it is baselined (put in a specific location and locked). At this point the requirement is to have a clear and immutable version that everyone sees that cannot be changed without prior approval. That is the essence of change control. If the corresponding twiki pages are to remain in trac twiki simultaneously, they must be locked as well.

Note that documents should be subject to very little, and only incremental change after baselining, and only after approval of a formal change request. So, the interactive twiki editing process is less useful for these documents. If the document is undergoing significant change, it isn't ready for baselining to begin with, and can continue under edit via the twiki (subject to the footer indicating it's draft status).