4 reasons why ver. # suffice + 3 reasons why more is harmful

[Ray Plante]

Hi Markos,

Forgive me if I'm reading between the lines too much here, but I get the 
sense that you have two concerns:  One is what the numbers communicate to 
the community.  The other is the impact on the document coordinator of 
having to manage many versions on the IVOA site.  

I want to note that version numbers--particular the common convention I
recommended--is a familiar concept in the software community.  First, we
all understand vaguely the relative significance of a change between two
periods carries.  (Unlike the "n.mm" pattern, where n.21 comes between n.2
and n.3., which is not commonly understood.)  Second, we all understand
that a change shift 2.1 from 2.2 in one product does not have much
relevence to a change in another; it is up to the authors to determine
what level of significance this is.  We all operate fine with this common,
albeit vague, notion of revisions.

Also, the fact that m.n.r.[...] system is unbounded is not about allowing 
more than 100 versions.  We have yet to generate 100 versions of anything 
nor do I expect us to (official or otherwise).  It's about adopting a 
widely recognized convention with the flexibility required by typical 
software and document developments.  I expect that most of the versions 
will never get posted to the official release page, yet we must track 
versions between them.  

I think we need to consider the way we are generating versions now, in 
practice.  The m.n.r system supports us, it does not necessarily impact 
the document maintainers (i.e. let's deal with that issue separately), and 
the community will recognize what we're doing.  

So, if can suffer through more of my opinion, read my detailed reactions 
below.  

On Fri, 2 Apr 2004, Markus Dolensky wrote:
> 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.

As Martin says, we need to track changes prior to 1.0.  Also, the 
suggestion that pre-WD version need not follow any stated policies is not 
viable; from the perspective of the WG, revision management is continuous 
prior to and after 1.0.

> 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. 

Recall my annotation that you put into the guidelines: "perhaps 0.3 never 
saw the light of day."  In that six months, you can have lots of minor 
revisions; if it's done collaboratively, all have to have a different 
version number.  Even when I was revising VOResource internally myself, I 
needed to track versions; my collaborators then saw 
multiple-increment jumps in the version number.  

The m.nn system indicates that the 2nd n is a minor revision on the first. 
That means you only get 10 revisions of a particular level.

> 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.

As I've alluded, the WG chair does not necessarily review each revision; 
only those of sufficient significance (including those released via the 
Document repository.) 

> 1. We should consider also the consumer point of view: Which one do you trust 
> more: V2.0 or V1.19.04?
> 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.

Actually, V2.0 implies fragility.  V1.19.04 implies that version one has 
been well tested and debugged.  

> 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.

I do not see detailed consistancy across different documents as necessary
beyond what I've stated above.  This is the reality of software
development.  I'm sure Apache doesn't coordinate its various projects'
versioning (see http://www.apache.org/foundation/roles.html, "Individual
projects define their own rules to add additional structure to their
development processes.").

> 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.

This is incorrect.  Any change in a standard--however minor--that affects 
how the standard is implemented must be versioned (example: IVOA 
Identifiers 1.1).  (This excludes typo-level changes.)

cheers,
Ray