From 472b1f7c75b3d337f2a6838b9ed58fded52fe5e9 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Wed, 9 Mar 2011 03:05:22 +0100 Subject: [PATCH] new RfC: proposed Version numbering scheme --- doc/devel/rfc_pending/VersionNumberScheme.txt | 160 ++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 doc/devel/rfc_pending/VersionNumberScheme.txt diff --git a/doc/devel/rfc_pending/VersionNumberScheme.txt b/doc/devel/rfc_pending/VersionNumberScheme.txt new file mode 100644 index 000000000..1894ab1e0 --- /dev/null +++ b/doc/devel/rfc_pending/VersionNumberScheme.txt @@ -0,0 +1,160 @@ +VersionNumberScheme +=================== + +// please don't remove the //word: comments + +[grid="all"] +`------------`----------------------- +*State* _Idea_ +*Date* _Mi 09 Mär 2011 02:00:41 CET_ +*Proposed by* Ichthyostega +------------------------------------- + +[abstract] +******************************************************************************** +Define and use a version numbering scheme for all releases, including the +development releases. Use the rules of the debian policy as a guideline. +******************************************************************************** + +Description +----------- +//description: add a detailed description: + +It should be clear right from start how version numbers are to be generated. +This numbering scheme should include a pattern for development builds. The +Debian policy defines a nice algorithm for ordering extended version numbers, +which could be used as a guideline. The sequence of version numbers should +be monotonous increasing according to this ordering. + +Version number sequence +~~~~~~~~~~~~~~~~~~~~~~~ +.... +0.pre.## < 0.01~dev.20YYMMDDhhmm < 0.01 < 0.99 < 1.0~dev.20YYMMDDhhmm < 1.0 < 1.0.1 +.... + +Specifications +~~~~~~~~~~~~~~ +A *tagged build* is made whenever there is a feature change tangible for users. +This might just be a *dev release*. Contrary to this, a *published release* is +a build expected to be installed and used by the users. Amongst the published +releases, we distinguish *major* and *minor* and *bugfix* releases. + +- before we reach _alpha_ status, we don't create any real releases, just + tagged preview builds from time to time. The criteria for reaching alpha + status are defined on the roadmap. + +- during _alpha_ and _beta_ status, we don't differentiate our releases; + they are just numbered consecutively with 2 digits (to start with). A + release is made whenever there is something significant new or otherwise + interesting to try out for the users. + +- besides the releases, we create *development snapshot releases*, which + are just _tagged builds_. + + * Not every build/check-in gets promoted to such a tagged build; + rather there needs to be any reason from the users point of view, + e.g. a bugfix we expect to be tried out at least by _someone_. + + * these _development snapshots_ are an _anticipation_ of the + upcoming next release and thus get a numbering _derived_ from this + _next_ release (not the previous one). + + * dev snapshots use a _timestamp_ attached with a '~' (tilde char). + It is common practice to order a tilde _below_ the release it is + attached to (and debian follows this practice) + +- when we decide the application to be stable enough for real use and + past the _beta_ phase, we switch over to the usual 3-digit version numbering. + + * _major_ releases start with 1.0 and feature high impact changes, usually linked + to some significant breakage of compatibility or some other disruptive event. + + * _minor_ releases may include some new features, but can be considered + evolutionary. Their numbers are incremented on the second digit, like + 1.1, 1.2, 1.3, 1.4, .... + + * _bugfix_ releases are created when we have serious bugfixes to publish, + without any real new features. + +- similar to the practice established in pre-1.0, we can create series of + development snapshots working against and anticipating the next major/minor + release. We'll do so for those users interested in following the development + more closely. The version numbers for such anticipating snapshots are again + created by attaching a timestamp with a '~' (tilde char). + + +Tasks +~~~~~ +// List what needs to be done to implement this Proposal: + * a debian packaging has been created ([green]#✔#) + * the first version was tagged [,yellow]#0.pre.01# + + +Discussion +~~~~~~~~~~ + +Pros +^^^^ +// add a fact list/enumeration which make this suitable: + * the format of the version numbers classifies the kind of build + * the changes in the scheme where chosen to reflect the changed + dynamics in pre-alpha, beta and post-1.0 + * the anticipating snapshots fit better into the usual habits of + developers: the moment a release is published, it is outdated + and uninteresting. + * this practice with the anticipating snapshots was popularised + in by Apache Maven and works well in practice + + +Cons +^^^^ +// fact list of the known/considered bad implications: + + * this visioning scheme might look overengineered at first sight + + +Alternatives +^^^^^^^^^^^^ +//alternatives: explain alternatives and tell why they are not viable: + +_don't worry -- be happy_ is what developers usually do with version numbering. +Especially _not caring_ for development snapshots might be viable for commercial +products; but users of open source software frequently follow the development +rather directly; thus it's a good idea to have a clear numbering for these +dev snapshots too. + +Alternatively we might consider to use Git SHA-Hashes for the dev builds. +But unfortunately, these are rather long and not very mnemonic. We're better +off just adding them to the changelog (as recommended by Debian policy anyway) + + +Rationale +--------- +//rationale: Give a concise summary why it should be done *this* way: + +Many projects face a lot of confusion and bad reputation when they ``happen to run into'' +more widely published releases without any forethought. Users tend to be confused quickly +and can't be expected to understand the details of the development process. Thus we should +discuss and set up a unambiguous numbering scheme really early -- including the criteria +when to use what version number. + + + +//Conclusion +//---------- +//conclusion: When approbate (this proposal becomes a Final) +// write some conclusions about its process: + + + + +Comments +-------- +//comments: append below + + +//endof_comments: + +'''' +Back to link:/documentation/devel/rfc.html[Lumiera Design Process overview] +