Difference: WDNumberingNomenclature (8 vs. 9)

TCG discussion about the WD Standards numbering nomenclature

As per section 3.5 of the IVOA Technical Assesment and Roadmap for 2008:

Although there are already some numbering schemes envisaged in sections 4 and 5 of the Guidelines and Procedures for IVOA Document Standards Management v1.0, dated 25th April 2004, it would be useful to have a numbering nomenclature which clearly and immediately shows that a certain IVOA standard is a REC or in a WD. Of course, that would take place only for the new standardsto be produced.

Various options can be envisaged, so some discussion should take place within the TCG in coordination with the Standing Committee on Standards and Processes to determine a possible better scheme.

But we don't need to change the scheme if we feel that the current one is adequate, so each WG/IG chair should express clearly her/his choice :

1. I am happy with the existing scheme, so I will use it and make sure I enforce it for all future WDs.

2. I believe that the existing scheme could be improved, so I explain why and how I feel it could be improved.

I believe the current scheme as per the document is not intuitive and therefore is not being used by people writing WD. While it could potentially cover correctly the NEW standards on their way to 1.0, there has been various examples where we’ve run out of numbers (0.9+) or when v1.0 was send to the RFC, to the TCG and or to the EXEC for their comments/approval while further changes were required on the document. And we don’t want to have the first version of the standard being 1.01. Sometimes, we even had to go directly to v2.0 (eg ADQL) which is confusing. Personally, I dislike the notation 0.11 as it is difficult to intuitively guess if 0.11 is between 0.1 and 0.2 or between 0.9 and 1.0. Furthermore, the numbering does not cover well cases when we have to go from STD v1.0 to STD v1.1 as this is not clear what should be the intermediate version numbers of the WD.

So my proposal (based also on some inputs from Norman when we initially discussed this) is to reflect the version not just by a number but by the following: IVOASTANDARD vN.m-YYYYMMDD-STATUS

Where

• N.m represent the version of the FINAL standard (eg 1.0, 1.1, 2.0)
• YYYYMMDD represents the date of the document
• STATUS can be : DRAFT, WD, PR, REC

That presents the following advantages:

• There is no ambiguity in the numbering scheme
• We always know what is the goal for the final version number (vN.m)
• We always know the status of the document (STATUS)

So for the case of a completely new standard (eg VOSTD 1.0) :

The document is being discussed amongst a few authors

• VOSTD 1.0-20081022-DRAFT --- initial draft version, really not yet a WD
• VOSTD 1.0-20081101-DRAFT --- an other draft version

• VOSTD 1.0-20081102-WD --- Ok, this is now a real WD within the working group
• VOSTD 1.0-20081201-WD --- new version of WD after interop
• VOSTD 1.0-20090301-WD --- new version of WD in WG

• VOSTD 1.0-20090501-PR --- submitted at the start of RFC
• VOSTD 1.0-20090701-PR --- updated after RFC and submitted to the TCG
• VOSTD 1.0-20090801-PR --- updated after TCG comments and submitted to the EXEC
• VOSTD 1.0-20090815-PR --- updated after EXEC comments

• VOSTD 1.0-20090901-REC

If we then need to slightly update the VOSTD with backward compatibility (so it goes with v1.1), we start again with:

The document is being discussed amongst a few authors

• VOSTD 1.1-20091022-DRAFT --- initial draft version, really not yet a WD

• VOSTD 1.1-20091102-WD --- Ok, this is now a real WD within the working group
• VOSTD 1.1-20091201-WD --- new version of WD after interop
• VOSTD 1.1-20100301-WD --- new version of WD in WG

• VOSTD 1.1-20100501-PR --- submitted at the start of RFC
• VOSTD 1.1-20100701-PR --- updated after RFC and submitted to the TCG
• VOSTD 1.1-20100801-PR --- updated after TCG comments and submitted to the EXEC
• VOSTD 1.1-20100815-PR --- updated after EXEC comments

• VOSTD 1.1-20100901-REC

For a significant update without backward compatibility, it goes with v2.0 and follows the same scheme:

The document is being discussed amongst a few authors

• VOSTD 2.0-20091022-DRAFT --- initial draft version, really not yet a WD

• VOSTD 2.0-20091102-WD --- Ok, this is now a real WD within the working group
• VOSTD 2.0-20091201-WD --- new version of WD after interop
• VOSTD 2.0-20100301-WD --- new version of WD in WG

• VOSTD 2.0-20100501-PR --- submitted at the start of RFC
• VOSTD 2.0-20100701-PR --- updated after RFC and submitted to the TCG
• VOSTD 2.0-20100801-PR --- updated after TCG comments and submitted to the EXEC
• VOSTD 2.0-20100815-PR --- updated after EXEC comments

• VOSTD 2.0-20100901-REC

Whilst I would not choose the current form of the document numbering if starting from scratch, I think that we can live with it if we change some practices slightly.

The main problem with current practice appears to be the conflict with the desire for a REC to be a 1.0 version and the (probable) necessary changes that are required for the transition from public WD -> REC. This requires a little planning on the part of each working group, in that it would be sensible when promoting a document to public WD and give it a version number of 0.9 rather than 1.0 as seems to be the current practice. Even with the deficiencies of the current numbering scheme this gives a headroom of 9 iterations of the document before it is forced to be a 1.0 version, and allows the transition from PR to REC to contain some changes to the document, rather than PR1.0 potentially being a different document to REC1.0, so that the version number of the document is a true indicator of different content.

I think that this proposal has the important side effect of encouraging slightly earlier promotion of a document outside of a working group, so that cross working group issues can be explored before the document becomes too solidified

The comments above from GWS basically make sense, but I think it needs to be clarified that there are two semi-independent labels for documents: the version number and the status of WD, PR, or REC. Thus, the first public release of a WD is supposed to be V1.0, which then progresses to PR V1.0 and REC V1.0. Right now the status of WD, PR, or REC is not visible in the document name, but rather only by the color coding of links on the IVOA documents page.

I remain basically satisfied with the system we have.

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->