[DRMAA-WG] Proposal how to handle versioning for group documents/implementations

[Peter Tröger]

Here is mine:

DRMAA document versioning proposal
----------------------------------

The proposal is based on the wish of having DRMAA documents as reference 
for implemented API's.

Every document gets a version number A.B.C. 'A' expresses the version of
the basic DRMAA API semantics. 'B' expresses whether or not this 
document is an update of an existing one with OGF number. 'C' expresses 
the document text version, and increases with every text editing.

The minor version returned by the DRMAA API implementation is the string 
concatenation of B and C. Every document can have one of the following 
states, which is reflected in its version number style:

'Draft': The group initially published a spec. It was so far not
submitted to the OGF editors. Major changes should be expected by the
adopters.
'A' MUST always be zero.
'C' changes with published document updates.
'B' is zero when the document was never in an OGF document chain. For
updated OGF standards, 'B' increases with every new round.

'Under standardization': The document was submitted to the OGF editors.
Minor changes should be expected by the adopters.
'A' MUST be one.
'C' might change with updates during the OGF review.
'B' is zero when the document is in OGF chain for the first time, and
increases with every new round.

'OGF prop. rec.': The document has an OGF number and is available from
ogf.org. References to this document should contain only the "A.B"
version number and the GFD number.

'OGF grid rec.': The document has an OGF number and is available from
ogf.org. It has the same version number as the proposed recommendation.
References to this document should contain the "A.B" version number, the
term 'grid recommendation' and the GFD number.


Migration strategy:
-------------------

- Documents in the OGF chain keep their numbers:

"DRMAA 1.0 Grid Recommendation (GFD.22)" -> "DRMAA 1.0 Grid
Recommendation (GFD.22)"
"DRMAA IDL v1.0" -> "DRMAA IDL v1.0", later "DRMAA IDL v1.0 (GFD.XXX)"

- Already adopted draft documents keep their (wrong) 'A' number,
but get a status indicator in the document title. The returned DRMAA
version in the implementation must be similar to the document version:

"DRMAA Java Binding v1.0" -> "DRMAA Java Binding v1.0.123 (draft)"
"DRMAA C Binding v1.0" -> "DRMAA C Binding v1.0.127 (draft)"

- New documents get the new numbering:

"DRMAA Perl Binding v0.0.256" (draft)
"DRMAA Perl Binding v1.0.289" (under stand.)
"DRMAA Perl Binding v1.0" (prop. rec.)
"DRMAA Perl Binding v1.0 Grid Recommendation" (grid rec.)
"DRMAA Perl Binding v0.1.124" (draft for updated grid rec.)
"DRMAA Perl Binding v1.1.124" (update under stand.)
"DRMAA Perl Binding v1.1" (prop. rec. of update)
"DRMAA Perl Binding v1.1 Grid Recommendation" (grid rec. of update)

Rationales:
------------
We need to consider the fact that people take DRMAA drafts from the
mailing list, the web or GridForge and implement it. Therefore, whenever
a document changes, it must change its version number. If a document
relies on another document (like the language-independent spec), it
should be referred both in the abstract and the introduction section.

Having a lot of zeros for draft documents shows their weak status.

The updated Java spec should therefore be named '1.0.1', counting the C
number up from now on.