TWiki Release Naming Convention

Requirements

Agreed:

• Create a beta from the command line; no manual steps
• One topic in Codev web per Beta and Production release (for ease of reference)
• Descriptive but short names
• Easily sortable names
• Should be able to build list of releases dynamically for Plugins web and Support web
• The release topic should be named (almost) the same as the release name (production and beta)
• The package name should be named (almost) the same as the release name (production and beta)

Contentious:

• Date based release name
  • YES - PeterThoeny (relevant for end users, not developers)
    • Agreed to let go in the interest of developers -- PTh - 07 Jan 2006
  • NO - CrawfordCurrie (confusing for everybody)

Implementation note

There is some existing automation for release naming:

• when perl build.pl release is run, it prompts for a release name
• it =sed=s TWiki.pm to insert the release name, and checks it in to ensure correct repository labelling
• it derives a TWiki topic name from that name by replacing s/\W/_/g.

Proposals

PeterThoeny - 02 Nov 2005 - date based

Type	Release name (in documentation)	Release topic name	Package name
Beta	TWiki Release 2005-11-01-6954beta	TWikiRelease2005x10x10x6954beta	TWikiRelease2005x10x10x6954beta.zip
Production (example)	TWiki Release 2005-11-01-7954	TWikiRelease2005x11x01x7954	TWikiRelease2005x11x01x7954.zip, TWikiRelease2005x11x01x7954.tgz
Production fix (example)	TWiki Release 2005-11-01-9582fix	TWikiRelease2005x11x01x9582fix	TWikiRelease2005x11x01x9582fix.zip, TWikiRelease2005x11x01x9582fix.tgz

Up to CairoRelease, TWiki is using this naming convention: (by example)

Type	Release Name	Release topic	Package name
Beta	TWiki Beta Release 30-Oct-2004	TWikiBetaRelease2004x10x30	TWiki20041030.zip
Production	TWiki Release 04-Sep-2004	TWikiRelease04Sep2004	TWiki20040904.zip, TWiki20040904.tar.gz

Pros:

1. As used by TWiki up till now
2. Timeline is clear (though see point 6 in Cons)
3. Can automatically derive a version name

Cons:

1. Can't build two releases on the same day - (irrelevant for pace of TWiki releases)
2. No differentiation between releases from different branches - (not used to date)
3. Difficult to determine if a release is supposed to exist between two dates
4. Perceived as user unfriendly by some
5. Difficult to automate
6. Patch releases based on consecutive dates do not reflect actual release date

CrawfordCurrie - 03 Nov 2005 - release codename + SVN rev

1. The release name should incorporate the codename of the release i.e TWikiReleaseDakar7071.
2. Betas should have Beta last to aid sorting i.e. TWikiReleaseDakar6954Beta.

Thus:

Type	Release name
Beta	TWikiReleaseDakar6945Beta
Production (example)	TWikiReleaseDakar7954

The reason for wanting the release codename is so that a bugfix branch can be released. e.g. if there is a patch to Dakar, then we can branch from 7954 and build a new release from that branch e.g. TWikiReleaseDakar8219 wihout risk of confusion with an Edinburgh beta e.g. TWikiReleaseEdinburgh8218Beta

Pros:

1. Absolutely clear which major TWiki release the package relates to
2. Easy to automate (release number is tied to top rev of repository -- not $Rev$ in TWiki.pm is not the repository rev at the time of release, it's the rev when TWiki.pm was last checked in)
3. Rock-solid link to the repository, without having to muck about with labelling (though see point 3 in cons)

Cons:

1. Not a commonly accepted standard
2. Not clear if another release exists between two releases (minor)
3. SVN rev numbers are non-sequential (minor)
4. No distinction between maintenance and patch release (minor)
5. This was a working proposal, and I'm not hung up on it. In fact, I prefer the next proposal CC

SvenDowideit - TWiki-major.minor.patchlevel

(Entered on behalf of Sven by CrawfordCurrie, based on notes from DakarReleaseMeeting2006x01x07)

There are de facto OSS conventions for release naming, usually based around release.version.patchlevel. So, we might name 'Dakar' release 4. The first version of Dakar will be 0, at patch level 0. So DakarRelease would be TWiki-4.0.0

A patch release - e.g. to correct a security flaw, or similar critical patch, would be TWiki-4.0.1

A subsequent maintenance version that collects patches and fixes would be numbered TWiki-4.1.0

EdinburghRelease will be TWiki-5.0.0

Topics can be derived using simple rules e.g. TWiki-4.0.0 -> TWikiRelease4Version0Patch0 or simply TWikiR4_0_0 (note: automation creates TWiki_4_0_0 from TWiki-4.0.0)

The standard way to distinguish releases from different branches is TWiki-4.0.0-sd (for sven's branch)

Pros:

1. de facto OSS standard, easier for packaging e.g. in Debian
2. User friendly, easy to see etymology of release
3. Simple, sequential numbering, easy to understand
4. A release number maps easily into a release name, which helps developers (i.e. 'TWiki-4.9.75' is obviously Dakar)

Cons:

1. No obvious way to mark alphas/nightly releases/betas (TWiki-4.0.0.beta6 makes some sense....)
   • the standard way to deal with this is TWiki-4.0.0-beta6
     • which can be confusing since it lumps all betas into the TWiki-4.0.0 numbering scheme
     • possibly base name on previous production release number, such as TWiki-3.99.0-beta6?
     • how about -build number e.g. TWiki.4.0.0-4795?
2. Not sortable -- flip over to double-digits makes names sort out of alphabetic order
   • e.g. TWiki-4.1.0, TWiki-4.10.0, TWiki-4.2.0, TWiki-4.3.0
3. No simple way to automatically derive the next version name (actually this applies to all the proposals)

PeterThoeny - 16 Jan 2006 - TWikiRelease<code_name><svn_top_rev><release_suffix>

Type	Release name (in documentation)	Release topic name	Package name
Beta release	TWiki Release Dakar-7945-beta	TWikiReleaseDakar7945beta	TWikiReleaseDakar7945beta.zip
Sven's branch	TWiki Release Dakar-7958-sd	TWikiReleaseDakar7958sd	TWikiReleaseDakar7958sd.zip
Production release (example)	TWiki Release Dakar-8412	TWikiReleaseDakar8412	TWikiReleaseDakar8412.zip, TWikiReleaseDakar8412.tgz
Maintenance release (example)	TWiki Release Dakar-8536-fix	TWikiReleaseDakar8536fix	TWikiReleaseDakar8536fix.zip, TWikiReleaseDakar8536fix.tgz

Pros:

1. Absolutely clear which major TWiki release the package relates to
2. Easy to automate - names are based on code name, svn top rev and release suffix (release number is tied to top rev of repository)
   • Running build script without a command line switch will assume beta release, hence TWikiRelease<code_name><svn_top_rev>beta; running with -suffix sd will produce TWikiRelease<code_name><svn_top_rev>sd; running with -suffix none will produce TWikiRelease<code_name><svn_top_rev>
3. Rock-solid link to the repository, without having to muck about with labelling
4. The human readable release name is derivable from release name (for beta, production and patches)
5. The package name is identical the release topic name (for beta, production and patches)
6. Easy to understand by developers since code name equals release name
7. Works well with OneSvnBranchPerRelease
8. Easy to integrate with queries on TWiki.org (such as release selectors in Support web and Plugins web)
9. Sortable - also correct sorting order with existing production release names, such as TWikiRelease04Sep2004

Cons:

1. Not a commonly accepted standard (on plus side, it is the wiki-way -- TWiki is a wiki)
2. No distinction between maintenance and patch release (minor)
3. Not clear if another release exists between two releases (minor)
4. SVN rev numbers are non-sequential (minor)

Discussions

Taxonomy is the basis of all science and it IS important in this context as well.

Crawford's points are well founded and I support them because they not only structure the differentiation - as a well designed taxonomy should - but aid analysis and (and sorting), follow a proper most significant to least significant naming order, relate to the repository, give an idea of the delta (which a date-based system simply does not), and addresses may future concerns such as branching.

The naming scheme must be easily manipulate by such things as regular expressions for automation, and so having the release name, topic name and package name in a similar format - and the hierarchical taxonimy - is going to be important.

The more we can automate the easier things get. We don't want to have to waste time on the 'bumps & potholes in the road' of exceptions or special cases slowing us down.

-- AntonAylward - 03 Nov 2005

Crawford, thanks for creating the new Beta, good to test recent fixes.

But... this is not what I understand we discussed. The only requirement you listed was "Create a beta from the command line; no manual steps. that's it." And "if you want to call releases after dates, fine by me." We discussed several options, one was to base the release name on the code name, where I replied that "what we miss is the date."

A naming like TWikiReleaseDakar7954 for a production release is developer centric. My goal was always to use a release name that is user centric, hence the date in the name and no code name. A TWiki admin is more interested in knowing how old a release is, and where a release is in relation to other releases; (s)he does not care what the code name was for a release, and does not know that Cairo comes after Beijing. Hence the date in the release topic and package name. The date serves as an externally used release number. The internal build & release number can be based on the code name and SVN number.

To address the bug fix branch question: Use the external release date as the base, the SVN number and and a word such as "fix" as modifier. For example, a fix for production release TWikiRelease2005x11x01x7954 can be called TWikiRelease2005x11x01x9582fix. That is, same external release number 2005x11x01 with modifier.

I do not feel strongly about naming the package the same as the release name. The reason why I kept the previous TWiki20040901.zip naming convention was to ensure that existing scripts continue to work (someone (I forgot who) asked me if it is possible to keep the package naming convention). To be influenced, I aligned now the package name with the release topic name (but please escape the package names to avoid undesired WikiWord linking).

I updated the naming convention at the top based on the additional discussions.

-- PeterThoeny - 06 Nov 2005

I am not a developer.
I an not so much interested in when the release came out as as am in keeping current.
A revision number release system lets me know how far I am behind, whereas a date based system does not.
The mixed date and revision system, yo propose, Peter, is just confusing as its doens't lend itself to scripting as easily as a purely revision number sytem. For example, I look at InstalledPlugins on my Dakar system and I can see clearly which revision level each plugin is at. Having to deal with dates there or to translate dates to revisions or having to wtite scripts to munge and map is just too much hassle.

Peter, you have some funny ideas about what it adminsitering a system involves! Users, that is end users, are just users. There's no such thing as a 'user centric' naming scheme. This is for admins. Its not Microsoft Windows where each user gets to fiddle with his systems configuration and so make life difficult for tech suport. Its is administratrators, host, web, appliation administrators who deal with this, and the question they ask is "What revision am I running?" and "Am I up to date". A numberic scheme makes that so much easier. It makes understnading easier and it makes scripting easier.

I don't understand why you want to make life difficult for us poor overworked sods who have to run and maintian systems or why you think end users are the least bit interested in what revision the server is running.

-- AntonAylward - 06 Nov 2005

May be the word "user" is not specific enough. What I meant was "people who download and install the package / people who are not involved in the TWiki development". We developers who work long hours on TWiki know that Sep 2004 release means CairoRelease, so I do not see a strong argument to include the code name in the release name.

-- PeterThoeny - 06 Nov 2005

Crawford: To reduce confusion it is better to name the beta packages something else than TWiki.tgz. It is not obvious from the file name what release it is.

Agreed. It only works the way it does because the automation to "correct" the package name doesn't exist yet. CC

-- PeterThoeny - 06 Nov 2005

"We developers who work long hours on TWiki know that Sep 2004 release means CairoRelease, so I do not see a strong argument to include the code name in the release name." Well! I'd think that would be a good reason to include the release name for those of us who are not developers.

-- AntonAylward - 07 Nov 2005

The naming conventions for twiki releases has always been a bit bizarre for me. Looking at one random Linux system, I have approx 600 packages installed on it. The naming convention, from vendors/developers/random users all seem to follow the format: Package-Major.minor.patchlevel

I have to heartily agree with Sven - Twiki-4.0.0 followed by Twiki-4.0.1, Twiki-4.0.2 makes it significantly easier for me to track the version on the various servers that I run Twikis on.

Nightly snapshots, Beta and Release Candidate Naming can be as simple as: Twiki-5.0.0.snapshot1 Twiki-5.0.0.snapshot2 .. Twiki-5.0.0.Beta-1 ... Twiki-5.0.0.Beta-11 Twiki-5.0.0.RC-1 ... Twiki-5.0.0.RC-4

Finally with: Twiki-5.0.0

As the gold release.

One doesn't typically release a package with internal codenames (Dakar, Edinburgh, etc...)

Inserting the Date into a package name is also a little awkward.

-- GordonShephard - 08 Jan 2006

I sincerely hope that starting with the upcoming TWiki release we will have the naming convention as outlined by Sven. Given that TWiki will release more often than before we will have to support a set of releases in the wild and provide (security) patches for them. I don't know if the TWikiCommunity will be able to support a greater numbers of releases backwards but during a release cycle there will be at least two frontiers. Things are not linear and maintenance and development can only become more transparent given the "major.minor.patch" scheme.

-- MichaelDaum - 08 Jan 2006

I agree that major.minor.patch type release naming is preferable, like virtually every other software package out there. Much easier to deal with and remember than specific dates, particularly for patched production releases like 04Sep2004 - released well after that date.

-- RichardDonkin - 16 Jan 2006

I'd like to add a requirement; "release name should be defined and used consistently everywhere. If transformation rules are required (e.g. for deriving topic names) those rules should be simple and obvious".

-- CrawfordCurrie - 16 Jan 2006

My oppinion is that the current scheme is confusing and even a security risk. When someone has downloaded version TWikiRelease2004x09x02 in February 2005 and later see that there is a release called TWikiRelease2004x09x04 he will not even notice that it is a new version. He will assume that a version downloaded in February 2005 is newer than anything dated in September. You have to be an insider to understand the current scheme. My preferred is a plain traditional X.X.X numbering scheme. The SVN numbering scheme is better than the date scheme but it does not show very well if a release is a major platform like going from Cairo to Dakar or it is a small bug fix release.

I have seen so many times on IRC people being confused when asked which version they run. "Are you running Cairo?". "No I live close to London!". I think the traditional decimal numbering method (e.g. 4.0.1) much better communicates with the users and admins. So I have added my name on Sven's proposal.

-- KennethLavrsen - 16 Jan 2006

Summary of opinions expressed. Add your name under the proposal you like. I have taken the liberty of translating some people's comments into "likes".

1. Existing Scheme
2. Crawford's proposal
3. Sven's Proposal
   • CrawfordCurrie
   • AntonAylward
   • GordonShephard
   • MichaelDaum
   • RichardDonkin
   • KennethLavrsen
   • LynnwoodBrown
   • WillNorris
   • AntonioTerceiro
   • ArthurClemens
4. Peter's Proposal