WDNumberingNomenclature < IVOA

<h3>TCG discussion about the WD Standards numbering nomenclature</h3>

----
Update on 14/01/2009 - IVOA.ChristopheArviset

Taking into account the discussions and inputs from within the TCG about this subject, the Standing Committee on Standards & Processes have decided to adopt the [[%ATTACHURL%/IVOADocsNamingConvention.pdf][new IVOA Document Naming and Version numbering convention ]] which we think address most of the matters discussed.

This will be included in the next version of the IVOA Standard Document that should soon go to PR and to a new RFC, following the various inputs after the last RFC.

Thanks for your useful participation on that subject. 


----
Update on 16/12/2008 - IVOA.ChristopheArviset

Following inputs by TCG number and further discussions and thoughts about it within the Standing Committee on Standards & Processes, we came to the conclusion that it would be useful to modify the naming and numbering convention.

We are now proposing two options with description attached:

- option 1 STATUS-ConciseName-I.J.K-YYYYMMDD.ext with a variable version number I.J.K.
(Potentially, we could also decide to leave the version number with just I.K)

- option 2 STATUS-ConciseName-N.M-YYYYMMDD.ext with a fixed N.M which indicates the final REC version number.

Full details of these options are [[%ATTACHURL%/20081217NamingConvention.pdf][here]].


Please indicate your preference by Friday 09/01 so we can also progress on the IVOA Standard Document 1.1 where this description will be included.

----

As per section 3.5 of the IVOA Technical Assesment and Roadmap for 2008:
----
The numbering nomenclature of the working drafts of IVOA standards in preparation is not homogeneous across WGs and makes it quite confusing for people not used to it.

Although there are already some numbering schemes envisaged in sections 4 and 5 of the [[http://www.ivoa.net/Documents/Notes/DocStd/Procedures-20040425.html#WorkingDrafts][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.

----
TCG, [[IVOA.ChristopheArviset][Christophe Arviset]], [[IVOA.SeverinGaudet][Severin Gaudet]]

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
The document then enters the WG
   * 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
The document then enters PR
   * 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 
The document becomes REC
   * 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
The document then enters the WG
   * 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
The document then enters PR
   * 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 
The document becomes REC
   * 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
The document then enters the WG
   * 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
The document then enters PR
   * 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 
The document becomes REC
   * VOSTD 2.0-20100901-REC 

----
IVOA, [[IVOA.FabioPasian][Fabio Pasian]]
----
Applications, [[IVOA.TomMcGlynn][Tom McGlynn]], [[IVOA.MarkTaylor][Mark Taylor]]  

There are at least three pieces of information that we seem to be trying to encode in the version system:
   * The release to which this version of the document is intended to be associated.
   * A unique identifier such that if two documents share the identifier we are guaranteed that the document is the same.
   * The status of this document in the IVOA approval process.

It doesn't really seem like the current system is doing any of these very well.  There is no guarantee that identically named documents are the same.  We can often guess which final release a draft is pointing towards, but not reliably.  Were I to have a draft document version 2.3 it might be that that is eventually to be released as 3.0 or it might be that we plan on a recommendation version 2.3.

To me the first two are essential.  E.g., in the recent discussion of the ADQL document several readers (including myself) were confused about which version of the document was current.  It's also useful to have a system where having different names strongly implies that the content has changed.

The TCG approach above comes pretty close to this.  There are a few issues with it, e.g., there might be multiple versions produced within a single day.  I'm less clear that the status of the document within our system is a characteristic of the document that should be reflected in the document title.  If we can robustly identify unique documents, then simply noting that document XX is a PR or a REC or whatever, where XX uniquely identifies a version of the document, would work much better than the table we have now.  I also rather like the idea that there is 1-1 mapping between unique documents and document names.  However it's easy enough to ignore the status suffix if we keep it. If so it should be mandated XX-PR and XX-REC are word for word identical.

Presumably we can append A,B,... in the cases where we have multiple versions of a given document on a given day (perhaps a meeting produced a majority and minority recommendation for a standard) if we use TCG framework.  

I could also envisage that we create an SVN (or similar) repository for storing all versions of all documents that are to be formally discussed.  One could then use the repository version #  (or just a simple counter for documents entered) instead of the date.   Requiring that people uniformly submit documents would be nice for lots of reasons but perhaps not feasible.

----
Data Access Layer, [[IVOA.KeithNoddle][Keith Noddle]], [[IVOA.JesusSalgado][Jesus Salgado]]  
----
Data Model, [[IVOA.MireilleLouys][Mireille Louys]], [[IVOA.AnitaRichards][AnitaRichards]] 
----
Grid and Web Sevices, [[IVOA.MatthewGraham][Matthew Graham]], [[IVOA.PaulHarrison][Paul Harrison]] 

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

Another thought - there is no real reason why the document number needs to be tied to the version number of the standard that it describes. e.g. There could be several documents that have "TAP 1.0" in the title, but the document version number be a version number made up by the authors - this is in fact what the W3C actually does itself see http://www.w3.org/TR/REC-xml/

[[IVOA.PaulHarrison]]
----
Registry, [[IVOA.RayPlante][Ray Plante]], [[IVOA.AurelienStebe][Aurelien Stebe]]
----
Semantics, [[IVOA.SebastienDerriere][Sebastien Derriere]], [[IVOA.NormanGray][Norman Gray]]  

The two things I have always found both perplexing about, and unique to, the IVOA numbering scheme are (i) the prescription that the version number be parsed as a real number rather than a tuple of integers (which creates the 'running out of numbers' problem, and encourages the frankly bizarre notion that a 0.9 document is somehow 90% of the way towards 1.0), and (ii) the notion that WD1.0, PR1.0, and REC1.0 _can be different documents!_

I broadly agree with Christophe's proposal.  It makes clear that it is the (IVOASTANDARD, yyyymmdd) pair which is the unique identifier of a document, with the 'n.m' goal and status being essentially informative annotations.

I'm anxious that using both a version number _and_ a yyyymmdd is making it more complicated than necessary, and possibly trying to pack too much information into the number (I can't help feeling that if you need to be instructed how to parse the version number, it's a bad sign).  Having a n.m notation in a REC does communicate the pattern of compatibilities (REC-1.2 should be compatible with 1.1, but 2.0 may not be).  I do quite like the notion that release 1.1-20090101-WD is working towards a 1.0-20090202-REC, but the cost of this is to make the version string quite complicated.

I would be happy with Christophe's suggestion, but if the field is still open, how about having the sequence:

   1. =VOSTD WD-20090101=
   1. =VOSTD WD-20090201= (release after comments)
   1. =VOSTD PR-20090301= (ready for review)
   1. =VOSTD PR-20090401= (after TCG comments)
   1. =VOSTD REC-1.0= or =VOSTD REC-1.0-20090501= (finished!)
   1. =VOSTD WD-20090601= (working on the next version, 1.1 or 2.0?)

That's parsable without tuition, more compact, and the sequence and the uniqueness are both clear enough.  On the downside, it's less symmetrical, and it does lose the information that WD-20090601 is a development of REC-1.0.  However, anyone sufficiently involved in the technicalities to be looking at a non-final WD should be aware of this anyway, and would soon be informed of it by text within the document.  The WD/PR documents, and the REC documents, have different audiences – IVOA 'insiders' and implementers respectively – and avoiding version numbers in pre-REC documents emphasises their provisionality.

NormanGray

----
VOEvent, [[IVOA.RobSeaman][Rob Seaman]], [[IVOA.AlasdairAllan][Alasdair Allan]]
----
VO Query Language, [[IVOA.PedroOsuna][Pedro Osuna]], [[IVOA.YujiSHIRASAKI][Yuji Shirasaki]]
----
VOTable, [[IVOA.FrancoisOchsenbein][Fran&ccedil;ois Ochsenbein]]
----
Standard and Processes, [[IVOA.FrancoiseGenova][Francoise Genova]]  
----
Astro RG, [[IVOA.MasatoshiOhishi][Masatoshi Ohishi]] 

I don't find serious problems in the current numbering scheme.
But the issue is that some WG chairs (and vice chairs) may not have been aware of the guidline document that we have. The observed confusion could be eliminated if we inform them which document they should refer to.

----
Data Curation and Preservation, [[IVOA.BobHanisch][Bob Hanisch]]  

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.

----
Theory, [[IVOA.HerveWozniak][Herve Wozniak]], [[IVOA.ClaudioGheller][Claudio Gheller]]
----

I guess we need four independent informations to uniquely identify a document by its name:
   1. the standard; 
   1. the version of the standard; 
   1. the status of the document.
   1. the version of the document.

In that order.

For the name of the standard and its version, I'd like to suggest to use the year of recommendation (foreseen date since we have to named the standard since the WD phase) for the version as for the case of SQL92, Fortran90, Word97, Windows98 etc. Instead of ADQL 2.0 (without any 1.0 version) one could define ADQL08 as being the recently adopted standard. For SimDB, if we expect to have a recommendation in 2009, we can call it SIMDB09. 

The name+version of a standard can also be updated _after_ its recommendation, as for the case of Fortran90 which was known as Fortran8x for a long time before being recommended under its current name. 

I hope nobody expects to have more than 1 version of a standard per year.

The version of the _document_ could be exactly like a SVN version number. It can be coded on four digits instead of the eight needed by a date YYYYMMDD. 

The status is obviously DRAFT, WD, PR and REC. However I'm not sure that a DRAFT document has to be published somewhere before becoming a WD document. The PR phase is however a bit more complex. If we want to know whether the document has been reviewed by the TCG or not, submitted to EXEC, etc. we need a more detailed status flag. But this could appear at the beginning of the document, in a status sheet (including a Project Status Report Version Control, that is currently missing in all documents!), not in the name of the document.


<br/>
<!--
      * Set ALLOWTOPICRENAME = IVOA.TWikiAdminGroup
-->
This topic: IVOA > WebHome > IvoaTCG > WDNumberingNomenclature
Topic revision: r18 - 2009-01-14 - ChristopheArviset