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
Received on 2004-04-02Z19:31:26