new RfC: proposed Version numbering scheme

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 <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
+
+
+//endof_comments:
+
+''''
+Back to link:/documentation/devel/rfc.html[Lumiera Design Process overview]
+