It makes sense to introduce an internal version numbering scheme. This is to make TWiki upgrades and installation transparent. I.e. a plugin could require a certain TWiki versionto run. There are several places where it makes sense to keep track of a version:

• TWiki program version
• File format version
• Plugin API version
• (any other?)

It is probably best to have only one internal TWiki version number for all places. That means, the version is bumped up with each release where the file format or plugin API changes. We still should keep the existing ISO date version number, it is the external (or "official") TWiki version number that is communicated to the outside.

What format is better for the internal version number:

• Linear: 1, 2, 3, ...
• Major.Minor: 1.0, 1.1, 2.0, ...

-- PeterThoeny - 27 Apr 2001

I'd go Major.Minor.

-- MartinCleaver - 27 Apr 2001

I agree with major.minor and one version for all sounds sensible.

-- JohnTalintyre - 27 Apr 2001

I agree with major.minor (e.g. 1.001 ... 1.002 ....).

I would prefer a VERSION variable for each module (E.g. $TWiki::Plugins::VERSION = '1.000').

-- AndreaSterbini - 27 Apr 2001

Out of curiosity, which ISO standard defines the date in dd MMM yyyy format?

ISO 8601 (html, pdf) describes several formats, but they all share a strict ordering requirement that the most significant information comes first, e.g. yyyy-mm-dd. (The ISO site doesn't seem to want to serve up web pages right now, so the html link above had to be copied from google. The pdf link still works.) Personally I have no problem with the current TWiki date representation, since it is pretty obvious, but it isn't ISO and probably shouldn't be referred to as such.

Now, on the real topic. You may want to follow the crowd and use the major.minor.patch format that is used by many open/free source packages, where odd numbered minor versions are reserved for experimental releases. E.g. the Linux kernel is currently at 2.4.4, and 2.5.x will be used to forge ahead with unstable development.

-- JohnAltstadt - 28 Apr 2001

Not quite on topic, but I would like to see more (and easier to find) release notes documentation on the new features in a given release (current or upcoming). It's quite hard to work out what the new features are in the December 2000 release, for example. Links to the current and upcoming release notes should be placed in ReadmeFirst and Support . Support, and in pages such as KnownIssuesOfTWiki01Dec2000.

There should also be some mention of the version of code documented by the links from TWiki . TWiki - I guess this is the December 2000 release currently. I think this is the best current documentation of what is in this release.

I did a topic name search on Release in Codev and the only release pages I found were TWikiRelease01May2000, TWikiReleaseSpring2001, and TWikiProductionRelease, which don't link to any release notes.

A non-date release format would also make it easier to have a single release notes topic that describes that release (no need to change from Spring 2001 to June 2001 when things inevitably take a bit longer than planned )

-- RichardDonkin - 10 May 2001

TWiki.TWikiHistory is probably what you are looking for. That is the topic where we keep track of all changes to the TWiki core.

-- PeterThoeny - 11 May 2001

moving some comments from _TWiki.TWikiUpgradeGuide. I hope this doesn't distract too much from the BeijingRelease and RequestReviewTWikiUpgradeGuide -- GrantBow - 28 Jan 2003

Isn't a useful point of having code names so that they can be used in documentation (such as this topic) that links to one place rather than using dates that need to be changed? Am I missing something? I just changed two paragraphs above so far, but using the code names probably makes the most sense in documentation due to the static nature of the links it provides. The same process is used for the Debian release documentation.

I think all the references to a date for Beijing need to be replaced by Beijing so that documentation will not have to be updated after the release. I made one exception in the overview so that will need to be changed for the release. The topic headers need to remove the dates too. For consistency sake, keeping the date associated with Athens makes sense (since it's static), but getting folks onto a new scheme of using code names is useful.

-- GrantBow - 07 Jan 2003

Code names are used purely during development, the offical releases are named by date. Once a release is out, it gets two new topics in the Codev web, one for release info (e.g. TWikiRelease01Dec2001), the other for known issues (e.g. KnownIssuesOfTWiki01Dec2001). All releases are listed in Codev.TWikiReleases. Production releases have a date rounded to the first of the month, BeijingRelease will be 01 Jan 2003 (or 01 Feb 2003 if we have more delays in the docs).

-- PeterThoeny - 08 Jan 2003

So you want to have code names but not use them publically. OK. Perhaps I'm just wishing that a better versioning scheme was being used instead of dates. More and more references are made to different releases both before and during development. I fail to understand the logic of not using them for official release names as well. But It's not my call I guess.

I know for myself I will probably use the release names rather than dates. I can't remember dates very well.

There are also the moving monikers of Beta, Alpha and Release that are ultimately another seperate naming scheme for the same set of underlying releases. As a release moves from one temporary moniker to the other the Athens, Beijing, Cairo... names become more useful when you know what specifically what code base you are talking about. Each naming scheme has value and conveys meaning.

Regular versioning schemes such as major.minor.revision convey stability and as the numbers increase so does the awareness to all users instantly a rough guide of evolution of the code. Dates lack this useful connotation. TWiki has been stable for a very very long time. I don't know what other users think about the versioning system currently used. In my own personal experience with software the dated versioning schemes are generally used for versions that evolve very very quickly and/or are not very stable yet. I don't find either one applies to TWiki anymore though these might have applied early on.

I'm also more familiar with a choice of actually using code names publically from my Debian experiences and how useful I find it in that situation. Since the code name is the ONLY naming scheme that's constant during all time frames it has a usefullness that I have come to appreciate very much.

Oh well...

-- GrantBow - 09 Jan 2003

I'd like to weigh in on the side of using the code names (Athens, Beijing, etc.) after the release as well.

Although I am not a TWiki core developer, or even a TWiki developer, I would like to push this issue a little if I can.

GrantBow has expressed some good reasons for using the code names on a continuing basis. (I think somewhere else I listed similar reasons some time ago.)

So far I have not heard reasons for the preference to use dates -- perhaps someone could express some of those?

-- RandyKramer - 12 Jan 2003

I'm also a Debian user/fan, and really like the way releases are tagged. They have Woody right now, which maps to Debian v 3.01a, Potato, which maps to Debian v 2.2, etc. At first people might be a little confused by the naming, but the nice thing about using codenames is thay also make easy to remember WikiNames. At the very top of BeijingRelease (or at the bottom, to follow the plugin versioning schema), you could have a summary box, with version, date of release, short list of new features, etc.

Also, it's much easier for me to remember a name than a specific date.

-- MikeMaurer - 13 Jan '03

WRT the naming of releases: I too would prefer version numbers and/or names to major releases instead of dates. If I was in charge of naming, I would pretty much follow the debian example:

• use a name to demark development cycles (Beijing)
• use dates for alpha releases (Beijing_7.6-2002Dec12)
• use minor numbers for beta releases (Beijing 7.7)
• use major numbers for stable releases (Beijing 8.0)

The upcoming Cairo development cycle would therefore include v8.1 through v8.9. When Cairo production is released it becomes v9.0 and the Dakar cycle begins at v9.1.

I grabbed the example version numbers by counting the TWikiHistory stable releases.

-- MattWilkie - 28 Jan 2003

Hello Matt, this is an excellent proposal.

I also support this scheme!!!

-- MartinRaabe - 28 Jan 2003

Matt, I like your proposal. It's compatible with other opensource projects, IMHO easier to remember. IMHO it's counterproductive and not helping TWikiMission to invent yet another way to solve problems, if there is established way. If Twiki handles issues as customers learned on other websites/projects, and do not have to explain own quirky ways. I am again off topic on this page

-- PeterMasiar - 28 Jan 2003

End of copied comments from TWikiUpgradeGuide.

I like it! Of course, there's no reason to stop at nine. If there are more than 9 beta releases, they can just keep on going as 8.9, 8.10, 8.11, ... Many other OSS projects (incl. the Linux kernel) do this, and while it does somewhat disrupt the ordering if you try and sort versions as you would decimal-notation real numbers, it's still very useful.

However, I also like the Linux kernel convention of using every other "major number" as a development branch. So the Beijing release would be e.g. 8.0, and a security or bugfix revision to 8.0 would be 8.1, etc. Development on Cairo immediately begins as version 9.0, and when Cairo is released as production, it would be 10.0. As an alternative, number beta releases for Cairo 9.0bN, and then post-release revisions as 9.x.

So we have several versioning schemes that use numbers...here are the alternatives I see: (alpha releases are dated as usual - they don't really fit into this scheme at all, and I think than's okay.)

-- WalterMundt - 28 Jan 2003

How about a string naming the version per module, eg, I request:

Twiki:7.0,EditTablePlugin:1.5,KoalaSkin:1.21

If I need to run on a TWiki engine more than 7.0, plus some addons/plugins of more than such and such versions...

-- ColasNahaboo - 29 Jan 2003

Thanks Walter, Matt and the others who have have brought ideas to the table. For reasons I outlined above I feel this is an important topic. It's worth noting that PeterThoeny started this topic in 2001. One consideration is that this kind of scheme might require more work - i.e. CVS branches, etc. This should be considered carefully. A major benefit of organizing different branches is to allow different speeds of development concurrently. As features are known to work they are migrated to the next more stable version. CVS fixes that get into the release within a few days could be migrated quickly, but may not be the best idea as a rule. Simple features might also need to be "ported" to previous version numbers for upgrading past stable releases. Changing the TWiki versioning numbering scheme is not something you can implement several times without killing the project due to confusion. It's a one time change for the entire project with many ramifications, so a cautious and conservative approach is required. If the development cycles are not ready for this complex of a versioning system, I propose we hold off implementing it and stick with what works.

I propose an alternative that more accurately represents the Linux kernel numbering. Please remember these numbers do already have a well-known meaning, and not following these conventions would only make matters worse than they are now. These meanings can shift from project to project, but the ideas are similar. Linux stable is only at version 2.4, so going too fast would certainly dilute the meaning as well. Changing revision numbers also imply the amount of work that goes into a release by the development community. With only a few core developers (at the moment), changing the major numbers too often would be almost dishonest! The purpose of a version number is to convey meaning to everyone that might hear it, not just for development branching in CVS.

The Major number shouldn't be changed haphazardly since not every development cycle is a big deal. Items of the scale of the Plugin API change probably deserves a Major number change because it will effect compatibility. The user and administrators will really care about this, it will make them stand up and notice that a big change has happened and compatibility between major numbers might not work. I would started with 3.0 for Athens and 4.0 for Beijing since it's been about four years of TWiki history. Four is also an even number, again implying stability.

Major.Minor could work very well. Minors are for shifts that are more subtle. There may be issues but whole sub-systems probably haven't been rewritten.

Keeping dates for the Alpha releases is good. There is a limitless supply and this gives people downloading it the right impression - code updates happen all the time.

Plugins should have their own versions as they see fit. This exact scheme is probably too complex for smaller projects, but 1.0 for a good stable release of a plugin with documentation is a good standard. 1.1 for development, 1.2 for the next stable release, etc. However I think plugin authors should be able to choose what they want to call their code. Naming and versioning are sometimes sensitive, but it makes sense to have consistency as much as possible. I hope a greater focus on plugins is now placed as there already is highly useful functionality in many of the plugins. Efforts for plugins should be more clearly recognized. (I've been itching to redo the Plugins.WebHome page, but not before BeijingRelease is out the door!)

So this could mean Athens is 3.0, Dakar is 4.3 (later 4.4), E* is 4.5 (later 4.6), etc. From my talks with PeterThoeny this also fits with the strategy of stabilizing the code base for corporate users. When someone rewrites major portions that effect compatibility, go to 5.0. If the scheme of multiple releases in a year is adhered to, this could work very well.

I'm now headed over to BeijingRelease to review the documentation work that is needed. Please join me and help out! This is a great way to help out and get involved. Almost everyone can help improve TWiki in this area, even if in small ways. There are a couple topics like TWiki.TWikiAdminCookBook and TWiki.InstantEnhancements that just need someone with English and grammar skills to help them out. The TWiki.TWikiUpgradeGuide needs people to test it out as MattWilkie has done.

-- GrantBow - 29 Jan 2003

I like GrantBow's proposal. I like milestone releases have nice memorable names, like CairoRelease. Date of the release is just an attribute, should not go to the name. Whole point of WikiNames to make it easy to remember, right? So if developers will add code fixes into release after release date, release name based ondate is misleading. But Release date based on city name still holds. Has minor subnumbers, exactly as other OpenSource projects are using. Whole point is, to be compatible with the rest of the world.

-- PeterMasiar - 30 Jan 2003

Maybe I'm biased but I would have though intelligibility would have had something to do with it too

OK, now we've got the NUMBERING scheme worked out we need to work out the cross refernce documentation side of things. What changes and what is impacted at each revision.

Its all very well to have things like "an even number means stable", but that only applies to the core. Things like ImprovedOutlines (which I think is a great feature) are currently issued as revision to the core rather than a plug-in or even a patch/diff. Should we discourage this kind of behaviour and insist on plug-ins? What about the impact to the plug-ins of core revisions? What about a set of standard regression tests that anyone who proposes updates to the core has to work though before submitting them? (To say nothing of other PM/QC issues that have been around for over three decades....)

Grant, perhaps you can propose a few topic pages with "impact matrix" models of this.

-- AntonAylward - 31 Jan 2003

...now we've got the NUMBERING scheme worked out...

Anton, worked out? I think we have general agreement on what the people posting to this page think but not recent thoughts by core team members. In impact matrix sounds great. Can you start it? I apologize but I have a family situation I'm dealing with right now. That real life stuff gets in the way from time to time!

-- GrantBow - 01 Feb 2003

This is maybe a little different perspective, but I'm not sure we need any "official" changes to the numbering scheme.

Forever and a day (or maybe longer ;-), I will refer to what was released on 01 Feb 2003 as the Beijing release. Almost everybody will know what I am talking about -- those that don't can be educated. In fact, if there is not already a page that cross reference release dates to development release names, I will create one sometime in the next weeks (or someone else can).

The next beta release I will refer to as the first Cairo beta release.

Is this an act of rebellion? I don't really think so -- in the absence of an "official" change it is an easy thing for me to do that will be understandable to all concerned (I think). If it is considered an act of rebellion, I apologize, but plan to do it anyway.

How about alpha releases? Well, I'm not sure -- alpha releases are just CVS snapshots and I have never used one. If I have a fairly solid memory in my head that the Beijing release occurred 01 Feb 2003 (which it did), I may just refer to an alpha release by it's date (and rely on the solid memory to remind me whether the release is a Beijing alpha (before 01 Feb 2003) or a Cairo alpha. Or, for the benefit of everyone, maybe I'll refer to an alpha release like "Cairo alpha 03 Feb 2003".

-- RandyKramer - 02 Feb 2003