LUMIERA.clone/doc/devel/rfc/VersionNumberScheme.txt

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 <prg@ichthyostega.de>
-------------------------------------

[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 <ct@pipapo.org>


//endof_comments:

''''
Back to link:/documentation/devel/rfc.html[Lumiera Design Process overview]