Introduction

The collection of VAMDC documents and softwares is published on the VAMDC website (http://www.vamdc.org) under the supervision of the VAMDC Document/Software Coordinator (hereafter refered as VDSC).

The VAMDC Document/Software Coordinator is currently L. Nenadovic (CNRS).

Published items are of different kinds:
  • Schemas describing different data models
  • Auto-generated Documentation from schema
  • Documents describing standard procedures adopted within VAMDC
  • Softwares
  • Auto-Generated Documents from Software
  • Software Reference Guide

Software and Schemas version numbers

Version numbers of software and schemas can be independent of version numbers of the related documents describing those softwares and schemas.

Nevertheless auto-generated documentation from schema or software is directly linked to the product they document and their version number is the same as the documented product.

The version number for schemas is given by [#.#] starting at [0.1] and increasing by 0.1 for each new update of the schemas.

The various softwares depend upon several standard procedures and schemas, that are released within VAMDC at regular time. Whether softwares are updated or not at each release, the software version adopts the Release number, given by [Year.Months] (Year being the last two digits of the running year).

Between the official VAMDC releases, the software version numbering would be constructed with the previous Release number [Year.Months] and a revision number giving [Year.MonthsR#]

  1. Version and Release Numbers in the VAMDC Document Collection

Auto-generated Documentation from schemas and from Softwares have the version number of the corresponding schemas and softwares.

All other documents have a version number given by their time of release. Whether the documents are updated or not at each release, the document version adopts the Release number, given by [Year.Months] (Year being the last two digits of the running year).

Between the official VAMDC releases, the document version numbering would be constructed with the previous Release number [Year.Months] and a revision number giving [Year.MonthsR#]

Document Format

Authors are strongly encouraged to start from one of the VAMDC document templates (put a link to the place where templates can be found), available in either Word or TeX. These help to ensure a common style and enables the VDSC to perform a lossless conversion to other common formats like PDF with minimum effort.

The VAMDC WP6 working group has adopted the use of SPHINX (put a link) in order to create easily either PDF or HTML pages, and authors may want to use the same software in order to produce homogeneous documentation for VAMDC.

How to Publish a Document

Documents are entered into the VAMDC document collection by the VDSC in response to a request from the Work Packages Leader or the person primarily responsible for editing a particular document.

Documents are sent via zip directories to the VDC and publication occurs within 5 working days.

Working Drafts, Proposed Recommendation, Recommendation

VAMDC official documents begin as Working Drafts. Working Drafts are under the responsability a Work Package working group. Working Drafts may undergo numerous revisions during their development.

Working Drafts will not be included in the formal VAMDC document collection, but rather will be maintained by the responsible working group on the VAMDC Document repository (GitHub).

Such works-in-progress should carry the version number of the previous recommendation with the revision number [#.#r1], the status is set to “Working Draft” and the date is compulsory.

Working Drafts should be developed, and utilize the above version numbering scheme, within the standard VAMDC document templates.

Once a Work package working group has reached internal agreement on a document, the document becomes a Proposed Recommendation keeping its last labelling [#.#r#], having a status set to “Proposed Recommendation” and including the date. The chair of the working group submits the Proposed Recommendation to the Document Coordinator for publication in the VAMDC Document Collection. If the Proposed Recommendation is amended, the version does not change, only the revision number and the date are updated. During this amendement period, the different revisions are carried out on GitHub.

Once the Proposed Recommendation is accepted, the document becomes a Recommendation document with the new version number, increased by 0.1 compared to previous version, no revision number, a new date. Its status is “Recommended”.

The Recommended Documents are published at the the time of Release with Html and PDF versions.

Document/Software Distribution

The VAMDC document/software collection is the primary source for VAMDC documents. VAMDC users, especially from outside the core collaboration, should always be directed to the document/software collection rather than be sent private copies of documents/softwares.

The Document/Software Collection

The VAMDC document/software collection keep track of the different Releases and Recommended Documents. The Proposed Recommendations are maintained on the VAMDC document/software collection prior to recommendation, and are then removed when the document/software is approved. All other revisions are kept on GitHub.