Version 0.3.2 of the version numbering debate...

[Martin @ ROE]

That's what we needed, a definite list of pros and cons...

Markus Dolensky wrote:

> Hi
> 
> The simplified version numbering scheme is partially my fault. In fact, 
> I was initially even in favor of format "n.m" instead of "n.mm". Here 
> are 4 reasons why m.nn version numbers (=> 100 revisions/increment of m) 
> will easily suffice and 3 reasons why a more elaborate scheme would be 
> harmful:
> 
> ***
> 
> 4 reasons why m.nn version numbers will suffice:
> 
> 1. WDs prior to version 1.0 are WG internal and therefore not in the doc 
> collection but remain in the roams of the WG where they can be freely 
> altered without following any particular policy as long as the document 
> layout is such that it prevents confusion with those on the official 
> document tree.
> 
We still need to version them, even if they are not on the official 
site.  That is what has been (and for some documents still is) causing 
confusion right now with the SkyNode spec.

> 2. But also after V1.0 internal drafts can be circulated within the WG, 
> on the Wiki and on the mailing lists as often as deemed necessary.

These too need to be versioned so we all know we are referring to the 
same document set.

> 3. Experience shows that it easily takes 6 weeks to review, rewrite and 
> repost a document. Having potentially 100 revisions allows to 
> intensively work on it for up to 10 years on a single version! If this 
> is not enough one should seriously consider splitting the document into 
> smaller solvable pieces.
> 
> 4. Each version increment also requires the WG chair to review things, 
> document changes within the doc. and - as our experience shows - to 
> fiddle together with the DC on little details. Neither the WG chairs nor 
> the DC have got the time to exhaust the potential number of possible 
> revisions assuming that we all have only 24 hours a day.

That's fair enough - shall we say that only high level (release.major) 
docs get posted to the ivoa site?  That allows us to continue to discuss 
and propose changes amongst the mailing list and experimental sites, 
using .minor versions to ensure amongst ourselves that we are talking 
about the same thing.

What about minor changes such as spelling or wording changes?  Or should 
these just be fixed without versioning on the official site?

> 
> ***
> 
> 3 reasons why a more elaborate scheme is harmful:
> 
> 1. We should consider also the consumer point of view: Which one do you 
> trust more: V2.0 or V1.19.04?

It is highly unlikely that V2.0 will live long. Soon there will be a few 
  fixes - do these result in v2.3 or v2.0.3?  The latter indicates minor 
changes, the former a relatively major one.

> V2.0 appears trustworthy and comforting to pick up and to develop 
> against whereas V1.19.04 implies fragility, uncertainty and one can 
> never remember the exact number anyway.

When it comes to releases we can always 'copy over' a version.  I would 
expect that when we all agree that v0.25.4.3 is the right version to 
release, we copy that into v1.0.  As we fix 'bugs' in the 
documents/specifications, these become v1.0.1, v1.0.2 etc, which 
indicates in an industry-common way to the user that these are minor 
changes.  When v1.1 appears the users know they will have to read the 
spec again!

This is exactly what happened to the JVM spec, and was very useful to 
people like myself who used JVM implementations.

> 
> 2. Each WG and author has a different attitude towards version 
> increments. The more freedom we leave the more inconsistent will version 
> numbers appear across the document tree.

Not really; we have a choice of whether a standard is a minor or major 
*increment*; that's it.  If we agree that major changes are posted to 
the ivoa that should be a straightforward decision, or?

> 
> 3. The official doc collection is aimed at the whole VO community and 
> beyond; if a revision is considered so minor that it isn't reflected 
> within the first 2 version number components then by definition it is 
> not worth bothering the whole community.

Agreed.

> 
> ***
> 
> It is interesting to note that the particular WG using numbers like 
> 0.7.n spends considerable time discussing which version they are 
> actually working on.

That's exactly the point; we were having trouble with the version 
numbers on the SkyNode document set *because* the standard was, largely, 
not versioned at all.

Now that some of those documents are versioned we *can* discuss which 
version we are working on. Previously it was all rather vague; we picked 
up snapshots of their stuff and worked with that.  Now we can find out 
what versions are being produced by which service and the problems and 
advantages of each, before submitting agreed new versions to the IVOA.

We can't do that without an exact 'handle' on the working document version.

MC


-- 
Martin Hill
Software Engineer, AstroGrid (ROE)
07901 55 24 66