Ichthyostega
b556d2b770
Some sections of the Lumiera website document meeting minutes, discussion protocols and design proposals from the early days of the project; these pages were initially authored in the »Moin Moin Wiki« operated by Cehteh on pipapo.org at that time; this wiki backed the first publications of the »Cinelerra-3« initiative, which turned into the Lumiera project eventually. Some years later, those pages were transliterated into Asciidoc semi-automatically, resulting in a lot of broken markup and links. This is a long standing maintenance problem problem plaguing the Lumiera website, since those breakages cause a lot of warnings and flood the logs of any linkchecker run.
181 lines
6.5 KiB
Text
181 lines
6.5 KiB
Text
VersionNumberScheme
|
|
===================
|
|
|
|
// please don't remove the //word: comments
|
|
|
|
[options="autowidth"]
|
|
|====================================
|
|
|*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 approved (this proposal becomes a Final)
|
|
// write some conclusions about its process:
|
|
|
|
|
|
|
|
|
|
Comments
|
|
--------
|
|
//comments: append below
|
|
|
|
.State -> Final
|
|
considered common practice
|
|
|
|
Christian Thaeter:: 'Thu 14 Apr 2011 03:46:07 CEST' ~<ct@pipapo.org>~
|
|
|
|
|
|
💡 +
|
|
[underline]#Please Note#: our Git branching model has been switched to
|
|
link:{ldoc}/technical/code/GitBranching.html[Git-flow] recently. On occasion
|
|
of that change, I wrote two helper scripts
|
|
|
|
- 'admin/buildVersion.py' extracts version info from the latest preceding
|
|
Git tag, and additionally allows to _bump some component_ of the version-ID
|
|
- 'admin/setVersion' edits a hard-wired small selection of known documents
|
|
in the tree with `sed` to update a version-ID
|
|
|
|
These are both related to version numbers, and also our conventions
|
|
for Git-flow refer directly to this RfC.
|
|
|
|
Ichthyostega:: '2025-09-15'
|
|
|
|
|
|
//endof_comments:
|
|
|
|
''''
|
|
Back to link:/x/DesignProcess.html[Lumiera Design Process overview]
|
|
|