|
|
International Virtual Observatory Alliance |
Guidelines and Procedures for IVOA Document Standards Management
Version 1.0
IVOA Note 2004 April 25
This version:
http://www.ivoa.net/Documents/Notes/DocStd/Procedures-20040425.html
Previous versions:
none
Authors:
Bob Hanisch (STScI)
Markus Dolensky (ESO)
Marco Leoni (ESO)
Abstract
The IVOA has adopted a process for the development and promotion of documents and standards, IVOA Document Standards Version 1.0. This process was developed by the IVOA Standards and Processes Working Group and promoted to the status of Recommendation by the IVOA Executive. This Note describes some practical matters associated with the implementation of the Recommendation.
Status of This Document
This is a Note.
This is an IVOA Note expressing suggestions from and opinions of the authors. It is intended to share best practices, possible approaches, or other perspectives on interoperability with the Virtual Observatory. It should not be referenced or otherwise interpreted as a standard specification. A list of current IVOA Recommendations and other technical documents can be found at http://www.ivoa.net/Documents/.
Acknowledgements
Ray Plante suggested the version numbering scheme, which is modified slightly below.
Contents
5. Version Numbers in the IVOA Document Collection
Appendix A: Changes from Previous Versions
1. Introduction
At the meeting of the IVOA Executive Committee on 2004-01-29, it was recognized that the IVOA document collection was already growing somewhat unwieldy owing to inconsistency in version numbering and the appearance of many works-in-progress. The IVOA Executive assigned an action, FM9-3A, as follows:
FM9-3A: ML [Marco Leoni, Document Coordinator] and WG Chairs: ensure full availability of IVOA WG drafts and agreed standards on the IVOA wiki and web site.
This Note is a response to action item FM9-3A, and is intended to clarify operational procedures necessary to conform with IVOA Document Standards Version 1.0 1.
In this document “DC” refers to the IVOA Document Coordinator.
2. Document Format
Authors are strongly encouraged to start from one of the IVOA document templates, available in either HTML or Word. These help to ensure a common style and enables the DC to perform a lossless conversion to other common formats like PDF with minimum effort. This can be nontrivial despite the many available utilities which produce output of varying quality when converting to and from HTML format.
Authors may, however, choose to create documents in arbitrary formats as long as the structure contains the necessary elements and does not require proprietary software or impose additional requirements on the document server. If authors cannot use the templates but wish to publish in several formats they are responsible for converting the document. Authors are welcome to include additional copies in different formats in a package upon submission. This gives some leeway in cases where a special format is desirable. In any case it is essential that the various presentations of a document are consistent and equally easy to read.
3. How to Publish a Document
Documents are entered into the IVOA document collection by the DC in response to a request from a Working Group chair or the person primarily responsible for editing a particular document. A request is initiated by filling out an on-line form and uploading the document. It may be necessary to tar or zip the document because only a single file can be uploaded at a time. Absolute path names must be avoided when packaging it up as well as when creating internal links within the document.
Since the upload mechanism presents a security risk it cannot be guaranteed to be available at all times and will only accept files up to a certain size. In general such limitations are beyond the control of the DC and altered firewall settings may interfere unexpectedly. In such cases it is necessary to agree with the DC on different means of electronic transfer.
4. Working Drafts
IVOA official documents begin as Working Drafts. Working Drafts are the purview of a Working Group. Working Drafts may undergo numerous revisions during their development. During this volatile phase Working Drafts will not be included in the formal IVOA document collection, but rather will be maintained by the responsible working group in its area of the IVOA TWiki 2.
Such works-in-progress should carry version numbers of the form 0.#[#], according to the following numbering scheme:
0.1 // an initial
pre-production draft version
0.2
0.21 // a minor
revision on 0.2
0.22
0.4 //
perhaps 0.3 never saw the light of day
0.8
0.9
0.91 //
we're not ready for 1.0 yet
0.92
0.93 // further
refinement
0.99 // end of the line
The fields on either side of the period (.) are integers. The version may be interpreted as a floating point number, such that trailing zeroes need not be shown.
Working Drafts should be developed, and utilize the above version numbering scheme, within the standard IVOA document template.
Once a working group has reached internal agreement on a document, the chair of the working group submits the Working Draft to the Document Coordinator for publication in the IVOA Document Collection. The Document Coordinator assigns version 1.0. Subsequent revisions to the document are treated similarly; they might undergo several iterations within a working group, and then be resubmitted to the Document Coordinator for publication.
5. Version Numbers in the IVOA Document Collection
The expectation is that once documents move out of the initial Working Draft phase, they will become less volatile and are unlikely to require a huge number of revision cycles. The version numbering scheme for formal Working Drafts, Proposed Recommendations, and Recommendations follows the same pattern as shown above, beginning with version 1.0:
1.0 // first formal release of
the document at this level
1.1 //
revision on 1.0
1.11 // minor change to 1.1
1.3 // revision on 1.11 (1.2
was not released by the working group)
2.0 //
major revision over 1.x; applications may break.
Version numbers are carried over when a document is promoted: for example, PR V2.1 becomes REC V2.1. Promoted documents replace their predecessors in the list of Latest Documents. All previous versions of published documents are archived and remain visible in the lists of Notes, Working Drafts, Proposed Recommendations, and Recommendations.
6. Document Distribution
The IVOA document collection is the primary source for IVOA documents. IVOA users, especially from outside the core collaboration, should always be directed to the document collection rather than be sent private copies of documents.
7. The Document Collection
The IVOA document collection will be organized so as to lead readers most naturally to the current versions of all documents in all document classes. A document archive will also be maintained so that previous published versions of documents remain available (but not pre-published versions of Working Drafts, though working groups may opt to retain this on the TWiki). As an aid to readers, the document collection web site will have a link to the Community TWiki area, where Working Drafts in-progress may be found, but links will not be provided to individual pre-publication Working Drafts.
8. Supplementary Resources
As a convenience the Document Coordinator maintains a repository of supplementary resources, such as XML Schema. Developers and any type of validation system/service should use these in preference to copies stored elsewhere. There is, however, no requirement to use them if a different implementation yields compliance with a given standard. Such additional items are considered part of the implementation but not part of the standard itself.
Standard document authors should, however, reference them as informative appendices if applicable and seek consistency. At the same time authors of auxiliary files should include comments stating which standards and versions thereof they support.
9. Transaction Log
The Document Coordinator may log information related to the entry and revision of documents in the IVOA collection (initiator of action, responsible working group, date, document ID and version, nature of action) in order to aid in tracing the history of standard documents.
|
Date |
Document ID |
Version |
Initiator |
I/W Group |
Action |
|
2004-02-28 |
ABC-20040227.html |
1.0 |
Tony Linde |
Registry |
promote from WD to PR |
|
2004-01-23 |
ABC-20040121.html |
1.0 |
Tony Linde |
Registry |
initiate 30-day RFC period |
"Date" ……….......... date at which a certain
transaction took place; defines sort order; newest entry on top, in ISO 8601
format.
"Document ID" …… just as much as necessary to make it unique,
e.g., RM-20040126.html.
"Version"
…………. the version number, as defined above.
"Initiator"…………... usually a WG chair, but it
could be also be the Document Coordinator or the IVOA Executive.
"Working Group"......the
name of the working group that developed the document.
"Action" ....................a brief description of the nature of the
transaction.
Appendix A: Changes from Previous Versions
Not applicable.
References
[1] IVOA Executive Committee, IVOA Document Standards, http://www.ivoa.net/Documents/latest/DocStd.html
[2] Peter Thoeny, TWiki - A Web Based Collaboration Platform, http://twiki.org