Proposal how to handle versioning for group documents/implementations
Background As a group we had two kinds of documents: * those submitted to OGF * unofficial at the time that had their own release numbers not fully following OGF ones Once the group realized that the unofficial documents could be useful for the wider audience, the implementation were already in the field synchronized with those unofficial documents. Proposal candidate This proposal advocates we keep the keep official DRMAA documents fully synchronized in versioning numbers when the content is synchronized. The implementations would follow the same versioning as the documents they refer to, proclaiming OGF document compliance. The benefit of the scheme is uniformity across both documents and implementations, resulting in greater user confidence, by avoiding potential doubts due to versioning discrepancy. It is expected that same binding version releases would not be necessarily simultaneous, so there could be time lags and possible different current versions. When the versions are matched in numbers the same semantics is the norm, when adjusted for different language bindings. The "bug implementation releases" could use a third number (subminor?) in their versions, meaning link compatibility with the implementations having the same major and minor versions. [It goes without saying that there is an adjustment that needs to be made to make the above proposal a reality. A good side is that it is one time adjustment, not allowing exceptions also in the future.] -Hrabri
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.
participants (2)
-
Peter Tröger -
Rajic, Hrabri