From rplante at poplar.ncsa.uiuc.edu Thu Apr 1 04:24:59 2004 From: rplante at poplar.ncsa.uiuc.edu (Ray Plante) Date: Thu, 1 Apr 2004 06:24:59 -0600 (CST) Subject: version numbers In-Reply-To: <406BC6AE.2060905@eso.org> Message-ID: Hi Marco, On Thu, 1 Apr 2004, Marco C. Leoni wrote: > - do we really need 10000 versions in between ver. 0.1 and the first > published WD (i.e. ver. 1.0)? No, of course not. But I expect that it won't be uncommon that we'll need more than ten. > - the documents process does not take into account the xml files et > similia: they are "supplementary resources" that means you can follow > your preferred numbering schema (CVS, RCS, VSS, etc.). In some cases where a document has an associated standard schema (e.g. ADQL), it would advantageous to have the XML version track the document version. Even in general, people will want to just adopt one system as a matter of practice. Consider the situation of VOResource, whose version now sits at 0.9. We have a choice between whether to make a major fundemental change to the core model or just an incremental change. (This is not hypothetical.) In my suggested system, it's a choice between going to 0.10 or 0.9.1. In the IVOA system, I'm pretty much forced to go to 0.91. Is there functional disadvantage to my system? (I hope I'm not overblowing this one.) cheers, Ray > > > Cheers, > Marco > > > > > Ray Plante wrote: > > >Hi Bob, Markus, Marco, > > > >I know I should have said something earlier, so feel free to say, "it's > >too late to change it." > > > >Thanks for the acknowledgement in the Guidelines Note regarding version > >numbers; however, you modified my suggestion in toward a direction I was > >trying to get away from. The convention of having 0.21 come between 0.2 > >and 0.22 has a real problem: you only get ten revisions of a particular > >level. What comes after 0.99 if you are not ready for 1.0? 0.991? Or > >are you out of luck? The result is that you no longer have a sense of how > >major a change the revision is. > > > >The point of *my* saying "fields on either side of the period (.) are > >integers" is to say that 3 comes between 2 and 4, and 21 come between 20 > >and 22. All increments between a set of periods are considered the same > >level of change. > > > >This is how RCS, CVS, and probably most other revision control systems > >work. > > > >cheers, > >Ray > > > From mchill at dial.pipex.com Thu Apr 1 04:40:45 2004 From: mchill at dial.pipex.com (Martin Hill) Date: Thu, 01 Apr 2004 13:40:45 +0100 Subject: version numbers In-Reply-To: References: Message-ID: <406C0DCD.1070302@dial.pipex.com> Throw in my opinion (how unusual) in support of Ray: 1) the numbering scheme that says that 0.10 is the version after 0.9 is reasonably common and gives all the flexibility we need. Limiting ourselves to one digit creates problems as Ray says with depth and with what happens after v0.9. Please please lets have a consistent pattern that lets us say v0.17 is after v0.7.3 2) Keeping the human document and associated schemas, WSDLs, etc versions the same makes life so much easier for the users of these documents! Given that we are setting *a* standard at each version change, then the whole set of documents describing that standard should make it clear they belong to that version of that standard. Cheers MC Ray Plante wrote: > Hi Marco, > > On Thu, 1 Apr 2004, Marco C. Leoni wrote: > >>- do we really need 10000 versions in between ver. 0.1 and the first >>published WD (i.e. ver. 1.0)? > > > No, of course not. But I expect that it won't be uncommon that we'll > need more than ten. > > >>- the documents process does not take into account the xml files et >>similia: they are "supplementary resources" that means you can follow >>your preferred numbering schema (CVS, RCS, VSS, etc.). > > > In some cases where a document has an associated standard schema (e.g. > ADQL), it would advantageous to have the XML version track the document > version. Even in general, people will want to just adopt one system as a > matter of practice. > > Consider the situation of VOResource, whose version now sits at 0.9. We > have a choice between whether to make a major fundemental change to the > core model or just an incremental change. (This is not hypothetical.) > In my suggested system, it's a choice between going to 0.10 or 0.9.1. In > the IVOA system, I'm pretty much forced to go to 0.91. > > Is there functional disadvantage to my system? > > (I hope I'm not overblowing this one.) > > cheers, > Ray > > > >> >>Cheers, >> Marco >> >> >> >> >>Ray Plante wrote: >> >> >>>Hi Bob, Markus, Marco, >>> >>>I know I should have said something earlier, so feel free to say, "it's >>>too late to change it." >>> >>>Thanks for the acknowledgement in the Guidelines Note regarding version >>>numbers; however, you modified my suggestion in toward a direction I was >>>trying to get away from. The convention of having 0.21 come between 0.2 >>>and 0.22 has a real problem: you only get ten revisions of a particular >>>level. What comes after 0.99 if you are not ready for 1.0? 0.991? Or >>>are you out of luck? The result is that you no longer have a sense of how >>>major a change the revision is. >>> >>>The point of *my* saying "fields on either side of the period (.) are >>>integers" is to say that 3 comes between 2 and 4, and 21 come between 20 >>>and 22. All increments between a set of periods are considered the same >>>level of change. >>> >>>This is how RCS, CVS, and probably most other revision control systems >>>work. >>> >>>cheers, >>>Ray >>> >> > > From mleoni at eso.org Thu Apr 1 05:04:53 2004 From: mleoni at eso.org (Marco C. Leoni) Date: Thu, 01 Apr 2004 15:04:53 +0200 Subject: Guidelines and Procedures note and version numbers Message-ID: <406C1375.30108@eso.org> Hi Everybody, The most labour intensive part for the DC is reformatting documents to/from HTML, especially if the input HTML is automatically generated by some word processor. I'd like to propose the following section to clarify how to go about this. 2. Document Format The official format for IVOA documents is HTML. Templates in this format can be found at http://www.ivoa.net/Documents/templates. An automatic procedure is used to convert HTML documents into other common formats (PDF, MS-WORD). If the resulting output of this procedure is not satisfactory, the Document Coordinator will assist the Author(s) in producing the initial Working Draft version 1.0 from which such a loss less conversion is possible. In any case the Author(s) will be informed about the technical problem and advised to use the massaged html document as the baseline for future updates. If the authors prefer to work from a different baseline thereafter the conversion to other formats will be performed only if the output is complete and therefore consistent with the original and if this can be achieved without manual editing of the original. - About version numbers First of all, the standard process is about document specification, whereas software implementation is something different. Having said that, let me recall a discussion Tony, Ray and myself had some time ago: "[...] I would prefer: http://www.ivoa.net/xml/VOResource/v0.9 Since the status as working draft is irrelevant for the namespace - it *IS* the namespace we are using for that schema, it is not a working draft, it is actual. [...] We cannot guarantee a 1:1 relationship between schema and document so it is pointless to tie the schema namespace to any document naming scheme." [Tony] This should explain why we do not want to have the same numbering for documents and xml files. By the way, having ten possibilities to go from one level to another should be sufficient, simply requires some attention in producing a new *document*. Cheers, Marco From mchill at dial.pipex.com Thu Apr 1 05:40:28 2004 From: mchill at dial.pipex.com (Martin Hill) Date: Thu, 01 Apr 2004 14:40:28 +0100 Subject: Guidelines and Procedures note and version numbers In-Reply-To: <406C1375.30108@eso.org> References: <406C1375.30108@eso.org> Message-ID: <406C1BCC.4090106@dial.pipex.com> Marco C. Leoni wrote: > - About version numbers > > First of all, the standard process is about document specification, > whereas software implementation is something different. If the full standard was described in the document, I would agree; the schemas/wsdls/etc are implementation issues. However we are using the schemas/wsdls to describe the standard, so I see them as being part of the specification. In other words, if I read the SkyNode document, I see the 'sorts of things' that an astrogrid datacenter must supply, but it is not in sufficient detail for me to create a datacenter that conforms closely enough to the standard that it will work with the VO. For that I need the WSDL and schemas. > Having said that, let me recall a discussion Tony, Ray and myself had > some time ago: > > "[...] I would prefer: http://www.ivoa.net/xml/VOResource/v0.9 > Since the status as working draft is irrelevant for the namespace - it *IS* > the namespace we are using for that schema, it is not a working draft, > it is actual. > [...] > We cannot guarantee a 1:1 relationship between schema and document so it is > pointless to tie the schema namespace to any document naming scheme." > [Tony] > > This should explain why we do not want to have the same numbering for > documents and xml files. While Tony's comment is technically true (we can't guarantee it) would it not make sense as a working practice? On the other hand, I understand that having to copy half a dozen files for a small change in one of them would be a pain... > By the way, having ten possibilities to go from one level to another > should be sufficient, simply requires some attention in producing a new > *document*. ? Ten's not nearly enough! SkyNode *was* passing v0.8 (somehow it's slipped back to 0.7.1?) and there's only one or two prototypes of it so far. Can we expect only two more changes before it's ready for general release v1? Why restrict ourselves to that if we have another industry-common versioning pattern? Now I really am going to take some time off.... honest I will be quiet now... MC From rplante at poplar.ncsa.uiuc.edu Thu Apr 1 07:58:45 2004 From: rplante at poplar.ncsa.uiuc.edu (Ray Plante) Date: Thu, 1 Apr 2004 09:58:45 -0600 (CST) Subject: Guidelines and Procedures note and version numbers In-Reply-To: <406C1375.30108@eso.org> Message-ID: Hi Marco, (Thanks for reminding us of the previous discussion--often necessary as not everyone may have been aware of how we got to this point, and I know you're not operating in a vacuum.) > By the way, having ten possibilities to go from one level to another > should be sufficient, simply requires some attention in producing a new > *document*. As Martin points out, we are demonstrating that 10 is not enough. It doesn't matter if we are talking about documents, schemas, or software--the revision process is essentially the same. I guess I'm failing see what the advantage of the "simplified" system is. cheers, Ray From Markus.Dolensky at eso.org Fri Apr 2 02:00:34 2004 From: Markus.Dolensky at eso.org (Markus Dolensky) Date: Fri, 02 Apr 2004 12:00:34 +0200 Subject: 4 reasons why ver. # suffice + 3 reasons why more is harmful In-Reply-To: References: Message-ID: <406D39C2.2080807@eso.org> 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. 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. 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. *** 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? 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. 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. 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. *** 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. A remark to Ray: It is a bit unfortunate that your name is acknowledged as the one suggesting the scheme, after we put it upside down. I can understand that you don't want to be blamed for something which is not your fault, but on the other hand Bob just tried to give credit where it seemed to be due. Give us advice at the end of the discussion on how to change it. Markus From mch at roe.ac.uk Fri Apr 2 03:46:12 2004 From: mch at roe.ac.uk (Martin @ ROE) Date: Fri, 02 Apr 2004 12:46:12 +0100 Subject: Version 0.3.2 of the version numbering debate... In-Reply-To: <406D39C2.2080807@eso.org> References: <406D39C2.2080807@eso.org> Message-ID: <406D5284.4010105@roe.ac.uk> 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 From Markus.Dolensky at eso.org Fri Apr 2 04:20:31 2004 From: Markus.Dolensky at eso.org (Markus Dolensky) Date: Fri, 02 Apr 2004 14:20:31 +0200 Subject: Version 0.3.2 of the version numbering debate... In-Reply-To: <406D5284.4010105@roe.ac.uk> References: <406D39C2.2080807@eso.org> <406D5284.4010105@roe.ac.uk> Message-ID: <406D5A8F.8050706@eso.org> Martin Hill wrote: > Now I really am going to take some time off.... honest I will be quiet From mleoni at eso.org Fri Apr 2 06:11:01 2004 From: mleoni at eso.org (Marco C. Leoni) Date: Fri, 02 Apr 2004 16:11:01 +0200 Subject: Fwd: IVOA Standard Documents In-Reply-To: <200404021311.i32DB1ti012727@urania.cfa.harvard.edu> References: <200404021311.i32DB1ti012727@urania.cfa.harvard.edu> Message-ID: <406D7475.9020508@eso.org> Hi Jonathan, I'm forwarding your mail to the stdproc list ..... as you said, discussion about the the standards document recommendation should be addressed there. Cheers, Marco Jonathan McDowell wrote: >Marco wrote: > > > >>Well, html is the standard format for IVOA documents >> >> > >[This is now beyond the scope of the voql list, but anyway...] >Marco, although I support the decision to make HTML the canonical >format for IVOA, I didn't realize we were going to be so restrictive, >and I think we may need eventually to revise this rule. > I think there are two roles for documents - > a source version which someone might use as a starting point for changes > a representation which is easy to read for everyone >and I think both should be found on the official IVOA documents page, >in multiple formats. HTML is in theory good for both because everyone >can access it, although in practice it does not always come out the >same in different browsers. PDF is also pretty good because I think >it's easy to read and print for most people, but it's not a source version. >Still it should be allowed as it's much easier to print a big PDF than >a big HTML. And the operating system specific formats - latex and postscript >for Unix, .doc for Microsoft - are good for source but each is inconvenient >for some users - still I think they should both be findable on the >official page, not just the twiki, if they are provided, AS LONG AS they >are accompanied by a universally printable format version (HTML or, I would >argue, PDF). > I worry that the current system may become so inflexible and >inconvenient that people will end up just bypassing it. It would be much >better if the IVOA Documents tree were the default place people went >to find the official document they wanted, the WG twikis are not optimal >for this. > - Jonathan McDowell > -------------- next part -------------- An HTML attachment was scrubbed... URL: From rplante at poplar.ncsa.uiuc.edu Fri Apr 2 11:31:07 2004 From: rplante at poplar.ncsa.uiuc.edu (Ray Plante) Date: Fri, 2 Apr 2004 13:31:07 -0600 (CST) Subject: 4 reasons why ver. # suffice + 3 reasons why more is harmful In-Reply-To: <406D39C2.2080807@eso.org> Message-ID: 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 From Markus.Dolensky at eso.org Sat Apr 3 07:07:08 2004 From: Markus.Dolensky at eso.org (Markus Dolensky) Date: Sat, 03 Apr 2004 17:07:08 +0200 Subject: 4 reasons why ver. # suffice + 3 reasons why more is harmful In-Reply-To: References: Message-ID: <406ED31C.7070309@eso.org> Hi, Ray, to my believe the main source of disagreement on your proposed version scheme is that we have a different idea of its scope. The DC needs to enumerate documents - again, documents only - in a way that is enough for readers to identify them. This is already the case by assigning a release date and title. Even the simplest version number is already redundant information in this context. All the rest of the discussion belongs to software development and maintenance - it's nothing that the reader of standard documents needs to worry about and therefore such internal bookkeeping doesn't need to be exposed on the official doc. tree and hence DC doesn't need to worry about it. > So, if can suffer through more of my opinion, read my detailed reactions > below. ditto ... In the note (http://www.ivoa.net/Documents/latest/DocStdProc.html) it says that there can be supplementary resources (like Schema) which the DC publishes as is, i.e., embedded version info stays untouched. This will assure consistency with the source of information which is most likely some CVS system or some other dev. suite that is assigning revision numbers. Mapping such numbers to a uniform IVOA scheme implies that there can be 2(!) version numbers for the same item. If you think this is really essential and justifies the overhead of such an endless source of potential confusion then I'm not against introducing such a scheme: BUT, the mapping of the two namespaces has to be maintained internally (for instance on the Wiki) and by the relevant people in each WG and NOT at all by the DC. I vehemently object to offload the task of enumerating configuration files onto the shoulder of the DC. (For instance, the Wiki uses RCS to automatically assign revision numbers to topics and each attachment. It'll be fun to maintain a mapping with this kind of source.) Conclusion: 1. introduce an IVOA version scheme (on top of RCS, CVS etc.) where the community considers it essential, but not for the official doc. tree. 2. If it appears inconsistent to have a doc. tree with a different scheme, then let's remove version numbers from official documents altogether and simply use title and release date to identify them. Markus From rplante at poplar.ncsa.uiuc.edu Thu Apr 1 04:24:59 2004 From: rplante at poplar.ncsa.uiuc.edu (Ray Plante) Date: Thu, 1 Apr 2004 06:24:59 -0600 (CST) Subject: version numbers In-Reply-To: <406BC6AE.2060905@eso.org> Message-ID: Hi Marco, On Thu, 1 Apr 2004, Marco C. Leoni wrote: > - do we really need 10000 versions in between ver. 0.1 and the first > published WD (i.e. ver. 1.0)? No, of course not. But I expect that it won't be uncommon that we'll need more than ten. > - the documents process does not take into account the xml files et > similia: they are "supplementary resources" that means you can follow > your preferred numbering schema (CVS, RCS, VSS, etc.). In some cases where a document has an associated standard schema (e.g. ADQL), it would advantageous to have the XML version track the document version. Even in general, people will want to just adopt one system as a matter of practice. Consider the situation of VOResource, whose version now sits at 0.9. We have a choice between whether to make a major fundemental change to the core model or just an incremental change. (This is not hypothetical.) In my suggested system, it's a choice between going to 0.10 or 0.9.1. In the IVOA system, I'm pretty much forced to go to 0.91. Is there functional disadvantage to my system? (I hope I'm not overblowing this one.) cheers, Ray > > > Cheers, > Marco > > > > > Ray Plante wrote: > > >Hi Bob, Markus, Marco, > > > >I know I should have said something earlier, so feel free to say, "it's > >too late to change it." > > > >Thanks for the acknowledgement in the Guidelines Note regarding version > >numbers; however, you modified my suggestion in toward a direction I was > >trying to get away from. The convention of having 0.21 come between 0.2 > >and 0.22 has a real problem: you only get ten revisions of a particular > >level. What comes after 0.99 if you are not ready for 1.0? 0.991? Or > >are you out of luck? The result is that you no longer have a sense of how > >major a change the revision is. > > > >The point of *my* saying "fields on either side of the period (.) are > >integers" is to say that 3 comes between 2 and 4, and 21 come between 20 > >and 22. All increments between a set of periods are considered the same > >level of change. > > > >This is how RCS, CVS, and probably most other revision control systems > >work. > > > >cheers, > >Ray > > > From mchill at dial.pipex.com Thu Apr 1 04:40:45 2004 From: mchill at dial.pipex.com (Martin Hill) Date: Thu, 01 Apr 2004 13:40:45 +0100 Subject: version numbers In-Reply-To: References: Message-ID: <406C0DCD.1070302@dial.pipex.com> Throw in my opinion (how unusual) in support of Ray: 1) the numbering scheme that says that 0.10 is the version after 0.9 is reasonably common and gives all the flexibility we need. Limiting ourselves to one digit creates problems as Ray says with depth and with what happens after v0.9. Please please lets have a consistent pattern that lets us say v0.17 is after v0.7.3 2) Keeping the human document and associated schemas, WSDLs, etc versions the same makes life so much easier for the users of these documents! Given that we are setting *a* standard at each version change, then the whole set of documents describing that standard should make it clear they belong to that version of that standard. Cheers MC Ray Plante wrote: > Hi Marco, > > On Thu, 1 Apr 2004, Marco C. Leoni wrote: > >>- do we really need 10000 versions in between ver. 0.1 and the first >>published WD (i.e. ver. 1.0)? > > > No, of course not. But I expect that it won't be uncommon that we'll > need more than ten. > > >>- the documents process does not take into account the xml files et >>similia: they are "supplementary resources" that means you can follow >>your preferred numbering schema (CVS, RCS, VSS, etc.). > > > In some cases where a document has an associated standard schema (e.g. > ADQL), it would advantageous to have the XML version track the document > version. Even in general, people will want to just adopt one system as a > matter of practice. > > Consider the situation of VOResource, whose version now sits at 0.9. We > have a choice between whether to make a major fundemental change to the > core model or just an incremental change. (This is not hypothetical.) > In my suggested system, it's a choice between going to 0.10 or 0.9.1. In > the IVOA system, I'm pretty much forced to go to 0.91. > > Is there functional disadvantage to my system? > > (I hope I'm not overblowing this one.) > > cheers, > Ray > > > >> >>Cheers, >> Marco >> >> >> >> >>Ray Plante wrote: >> >> >>>Hi Bob, Markus, Marco, >>> >>>I know I should have said something earlier, so feel free to say, "it's >>>too late to change it." >>> >>>Thanks for the acknowledgement in the Guidelines Note regarding version >>>numbers; however, you modified my suggestion in toward a direction I was >>>trying to get away from. The convention of having 0.21 come between 0.2 >>>and 0.22 has a real problem: you only get ten revisions of a particular >>>level. What comes after 0.99 if you are not ready for 1.0? 0.991? Or >>>are you out of luck? The result is that you no longer have a sense of how >>>major a change the revision is. >>> >>>The point of *my* saying "fields on either side of the period (.) are >>>integers" is to say that 3 comes between 2 and 4, and 21 come between 20 >>>and 22. All increments between a set of periods are considered the same >>>level of change. >>> >>>This is how RCS, CVS, and probably most other revision control systems >>>work. >>> >>>cheers, >>>Ray >>> >> > > From mleoni at eso.org Thu Apr 1 05:04:53 2004 From: mleoni at eso.org (Marco C. Leoni) Date: Thu, 01 Apr 2004 15:04:53 +0200 Subject: Guidelines and Procedures note and version numbers Message-ID: <406C1375.30108@eso.org> Hi Everybody, The most labour intensive part for the DC is reformatting documents to/from HTML, especially if the input HTML is automatically generated by some word processor. I'd like to propose the following section to clarify how to go about this. 2. Document Format The official format for IVOA documents is HTML. Templates in this format can be found at http://www.ivoa.net/Documents/templates. An automatic procedure is used to convert HTML documents into other common formats (PDF, MS-WORD). If the resulting output of this procedure is not satisfactory, the Document Coordinator will assist the Author(s) in producing the initial Working Draft version 1.0 from which such a loss less conversion is possible. In any case the Author(s) will be informed about the technical problem and advised to use the massaged html document as the baseline for future updates. If the authors prefer to work from a different baseline thereafter the conversion to other formats will be performed only if the output is complete and therefore consistent with the original and if this can be achieved without manual editing of the original. - About version numbers First of all, the standard process is about document specification, whereas software implementation is something different. Having said that, let me recall a discussion Tony, Ray and myself had some time ago: "[...] I would prefer: http://www.ivoa.net/xml/VOResource/v0.9 Since the status as working draft is irrelevant for the namespace - it *IS* the namespace we are using for that schema, it is not a working draft, it is actual. [...] We cannot guarantee a 1:1 relationship between schema and document so it is pointless to tie the schema namespace to any document naming scheme." [Tony] This should explain why we do not want to have the same numbering for documents and xml files. By the way, having ten possibilities to go from one level to another should be sufficient, simply requires some attention in producing a new *document*. Cheers, Marco From mchill at dial.pipex.com Thu Apr 1 05:40:28 2004 From: mchill at dial.pipex.com (Martin Hill) Date: Thu, 01 Apr 2004 14:40:28 +0100 Subject: Guidelines and Procedures note and version numbers In-Reply-To: <406C1375.30108@eso.org> References: <406C1375.30108@eso.org> Message-ID: <406C1BCC.4090106@dial.pipex.com> Marco C. Leoni wrote: > - About version numbers > > First of all, the standard process is about document specification, > whereas software implementation is something different. If the full standard was described in the document, I would agree; the schemas/wsdls/etc are implementation issues. However we are using the schemas/wsdls to describe the standard, so I see them as being part of the specification. In other words, if I read the SkyNode document, I see the 'sorts of things' that an astrogrid datacenter must supply, but it is not in sufficient detail for me to create a datacenter that conforms closely enough to the standard that it will work with the VO. For that I need the WSDL and schemas. > Having said that, let me recall a discussion Tony, Ray and myself had > some time ago: > > "[...] I would prefer: http://www.ivoa.net/xml/VOResource/v0.9 > Since the status as working draft is irrelevant for the namespace - it *IS* > the namespace we are using for that schema, it is not a working draft, > it is actual. > [...] > We cannot guarantee a 1:1 relationship between schema and document so it is > pointless to tie the schema namespace to any document naming scheme." > [Tony] > > This should explain why we do not want to have the same numbering for > documents and xml files. While Tony's comment is technically true (we can't guarantee it) would it not make sense as a working practice? On the other hand, I understand that having to copy half a dozen files for a small change in one of them would be a pain... > By the way, having ten possibilities to go from one level to another > should be sufficient, simply requires some attention in producing a new > *document*. ? Ten's not nearly enough! SkyNode *was* passing v0.8 (somehow it's slipped back to 0.7.1?) and there's only one or two prototypes of it so far. Can we expect only two more changes before it's ready for general release v1? Why restrict ourselves to that if we have another industry-common versioning pattern? Now I really am going to take some time off.... honest I will be quiet now... MC From rplante at poplar.ncsa.uiuc.edu Thu Apr 1 07:58:45 2004 From: rplante at poplar.ncsa.uiuc.edu (Ray Plante) Date: Thu, 1 Apr 2004 09:58:45 -0600 (CST) Subject: Guidelines and Procedures note and version numbers In-Reply-To: <406C1375.30108@eso.org> Message-ID: Hi Marco, (Thanks for reminding us of the previous discussion--often necessary as not everyone may have been aware of how we got to this point, and I know you're not operating in a vacuum.) > By the way, having ten possibilities to go from one level to another > should be sufficient, simply requires some attention in producing a new > *document*. As Martin points out, we are demonstrating that 10 is not enough. It doesn't matter if we are talking about documents, schemas, or software--the revision process is essentially the same. I guess I'm failing see what the advantage of the "simplified" system is. cheers, Ray From Markus.Dolensky at eso.org Fri Apr 2 02:00:34 2004 From: Markus.Dolensky at eso.org (Markus Dolensky) Date: Fri, 02 Apr 2004 12:00:34 +0200 Subject: 4 reasons why ver. # suffice + 3 reasons why more is harmful In-Reply-To: References: Message-ID: <406D39C2.2080807@eso.org> 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. 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. 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. *** 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? 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. 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. 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. *** 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. A remark to Ray: It is a bit unfortunate that your name is acknowledged as the one suggesting the scheme, after we put it upside down. I can understand that you don't want to be blamed for something which is not your fault, but on the other hand Bob just tried to give credit where it seemed to be due. Give us advice at the end of the discussion on how to change it. Markus From mch at roe.ac.uk Fri Apr 2 03:46:12 2004 From: mch at roe.ac.uk (Martin @ ROE) Date: Fri, 02 Apr 2004 12:46:12 +0100 Subject: Version 0.3.2 of the version numbering debate... In-Reply-To: <406D39C2.2080807@eso.org> References: <406D39C2.2080807@eso.org> Message-ID: <406D5284.4010105@roe.ac.uk> 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 From Markus.Dolensky at eso.org Fri Apr 2 04:20:31 2004 From: Markus.Dolensky at eso.org (Markus Dolensky) Date: Fri, 02 Apr 2004 14:20:31 +0200 Subject: Version 0.3.2 of the version numbering debate... In-Reply-To: <406D5284.4010105@roe.ac.uk> References: <406D39C2.2080807@eso.org> <406D5284.4010105@roe.ac.uk> Message-ID: <406D5A8F.8050706@eso.org> Martin Hill wrote: > Now I really am going to take some time off.... honest I will be quiet From mleoni at eso.org Fri Apr 2 06:11:01 2004 From: mleoni at eso.org (Marco C. Leoni) Date: Fri, 02 Apr 2004 16:11:01 +0200 Subject: Fwd: IVOA Standard Documents In-Reply-To: <200404021311.i32DB1ti012727@urania.cfa.harvard.edu> References: <200404021311.i32DB1ti012727@urania.cfa.harvard.edu> Message-ID: <406D7475.9020508@eso.org> Hi Jonathan, I'm forwarding your mail to the stdproc list ..... as you said, discussion about the the standards document recommendation should be addressed there. Cheers, Marco Jonathan McDowell wrote: >Marco wrote: > > > >>Well, html is the standard format for IVOA documents >> >> > >[This is now beyond the scope of the voql list, but anyway...] >Marco, although I support the decision to make HTML the canonical >format for IVOA, I didn't realize we were going to be so restrictive, >and I think we may need eventually to revise this rule. > I think there are two roles for documents - > a source version which someone might use as a starting point for changes > a representation which is easy to read for everyone >and I think both should be found on the official IVOA documents page, >in multiple formats. HTML is in theory good for both because everyone >can access it, although in practice it does not always come out the >same in different browsers. PDF is also pretty good because I think >it's easy to read and print for most people, but it's not a source version. >Still it should be allowed as it's much easier to print a big PDF than >a big HTML. And the operating system specific formats - latex and postscript >for Unix, .doc for Microsoft - are good for source but each is inconvenient >for some users - still I think they should both be findable on the >official page, not just the twiki, if they are provided, AS LONG AS they >are accompanied by a universally printable format version (HTML or, I would >argue, PDF). > I worry that the current system may become so inflexible and >inconvenient that people will end up just bypassing it. It would be much >better if the IVOA Documents tree were the default place people went >to find the official document they wanted, the WG twikis are not optimal >for this. > - Jonathan McDowell > -------------- next part -------------- An HTML attachment was scrubbed... URL: From rplante at poplar.ncsa.uiuc.edu Fri Apr 2 11:31:07 2004 From: rplante at poplar.ncsa.uiuc.edu (Ray Plante) Date: Fri, 2 Apr 2004 13:31:07 -0600 (CST) Subject: 4 reasons why ver. # suffice + 3 reasons why more is harmful In-Reply-To: <406D39C2.2080807@eso.org> Message-ID: 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 From Markus.Dolensky at eso.org Sat Apr 3 07:07:08 2004 From: Markus.Dolensky at eso.org (Markus Dolensky) Date: Sat, 03 Apr 2004 17:07:08 +0200 Subject: 4 reasons why ver. # suffice + 3 reasons why more is harmful In-Reply-To: References: Message-ID: <406ED31C.7070309@eso.org> Hi, Ray, to my believe the main source of disagreement on your proposed version scheme is that we have a different idea of its scope. The DC needs to enumerate documents - again, documents only - in a way that is enough for readers to identify them. This is already the case by assigning a release date and title. Even the simplest version number is already redundant information in this context. All the rest of the discussion belongs to software development and maintenance - it's nothing that the reader of standard documents needs to worry about and therefore such internal bookkeeping doesn't need to be exposed on the official doc. tree and hence DC doesn't need to worry about it. > So, if can suffer through more of my opinion, read my detailed reactions > below. ditto ... In the note (http://www.ivoa.net/Documents/latest/DocStdProc.html) it says that there can be supplementary resources (like Schema) which the DC publishes as is, i.e., embedded version info stays untouched. This will assure consistency with the source of information which is most likely some CVS system or some other dev. suite that is assigning revision numbers. Mapping such numbers to a uniform IVOA scheme implies that there can be 2(!) version numbers for the same item. If you think this is really essential and justifies the overhead of such an endless source of potential confusion then I'm not against introducing such a scheme: BUT, the mapping of the two namespaces has to be maintained internally (for instance on the Wiki) and by the relevant people in each WG and NOT at all by the DC. I vehemently object to offload the task of enumerating configuration files onto the shoulder of the DC. (For instance, the Wiki uses RCS to automatically assign revision numbers to topics and each attachment. It'll be fun to maintain a mapping with this kind of source.) Conclusion: 1. introduce an IVOA version scheme (on top of RCS, CVS etc.) where the community considers it essential, but not for the official doc. tree. 2. If it appears inconsistent to have a doc. tree with a different scheme, then let's remove version numbers from official documents altogether and simply use title and release date to identify them. Markus