VersionNumberScheme =================== // please don't remove the //word: comments [grid="all"] `------------`----------------------- *State* _Final_ *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 .State -> Final considered common practice Do 14 Apr 2011 03:46:07 CEST Christian Thaeter //endof_comments: '''' Back to link:/documentation/devel/rfc.html[Lumiera Design Process overview]