.. -*- coding: utf-8 -*-

=================
 Version format.
=================
.. contents::

Feature set versioning.
=======================

Feature set versioning pretend to show how serious changes made according to
feature availability and how compatible these versions.

Marketing versioning.
=====================

Marketing versioning schema used for marketing, advertising, branding purpose.
It is usually inconsistent and can changed over the time.

Examples of marketing version schema:

 * Years.
 * Ancient gods.
 * Star/satellite/galactic names.

Look thread for GDB:

  http://www.cygwin.com/ml/gdb/2007-07/msg00061.html

There discussed:

 * Is it essential to update major version if significant change made for
   licence? Answer: NO!

   GPLv3 is a big deal spread out over the whole GNU project, but not a big deal
   for GDB in particular.
 * Is it right follow date version schema regardless major changes? Answer: NO!

   Many OS distribution encode year in versions but versions does not present
   featureset but package set instead.

Year as version name.
---------------------

If year used as version some people can decide that 2005 is too old and broken
if it used in 2007. So companies release product by leading year number. So in
2007 they release 2008 version.

Version name components.
========================

 * major
 * minor
 * patch (patchlevel), micro
 * rev (revision)
 * build
 * date
 * hotfix, fix

Version components usually combined in such group::

  major.minor.build
  major.minor.date
  major.minor.hotfix
  major.minor.hotfix.build
  major.minor.rev
  major.minor.rev.build
  major.current.age

Its conventional to have at least a major and minor number.

Prefixing version with a "v" seems to be less common.

Versioning for libraries/modules/components.
============================================

Major version component.
------------------------

Major number change means that fundamental change made in the architecture of
the system the new version is incompatible with the old one, upgrade between
versions is non-trivial, and any dependent of the prior version will require
code changes to upgrade to the new package.

Major number rare changed (this can take a lot of year).

Minor version component.
------------------------

Minor number change means that the new version is backward compatible with the
previous version but has significant enhancements over the previous version
(like new functionality or changed UI).

Functional enhancement releases. Contain new or significantly changed
functionality and/or layout.

New releases are usually only published several times a year or less.

Revision, micro, bugfix version component.
------------------------------------------

Revision number is updated whenever a bugfix or security patche is applied to
the build such that it doesn't bring a compatibility change or introduce newer
features.

Patches are released frequently (sometimes daily).

Milestone markers.
------------------

 * a (alpha) means new development is complete and code checkins are frozen.
   Alpha builds should work well enough to be testable.
 * b (beta) means most severe bugs are fixed and end users can start trying the
   release.
 * rc (release candidate) are believed to meet all of the criteria for release
   and can be installed on test instances of production systems.

Versioning for products.
========================

Versioning for products differ from versioning for libraries.

Product is a set of conponents fixed to some versions. Components can be
switches as written for library versioning:

 * Any fix release interchanged.
 * Any minor release interchanged starting from some minor.
 * Major release does not interchanged at all.

Product update vs upgrade.
--------------------------

Product update involve:

 * Replacing product executable files, resources files.
 * Config files and user data stay unchanged.

Product update involve:

 * Replacing product executable files, resources files.
 * Config files and used data require modification and performed by upgrade
   scripts or manually by user.

Release build version data.
===========================

 * Build number.
 * Build date.
 * VCS revision.
 * Branch-tag used.
 * Overnight build (Y/N).
 * QA tested (Y/N).
 * QA test results (Pass/Fail).
 * Location of full logs.

Stop your VCS hook to update version!
=====================================

Don't update version without human decision.

Why do not do this on success build:

 * You can have several build machine which may concurrently update version.
 * There not exist tools for easy querying for status of build (as ok/fail,
   build configuration, date, coverage, lint checks, etc).
 * Some part of development team may not have permission for bumping version and
   after build they must revert some automatically updated files.

Why do not do this from pre-/post-commit hooks:

 * Some changes can only partially introduce feature/bugfix.

Version ordering formula.
=========================

Strongly recommend:

 * Numbers are not decimal fractions. They are integers separated by delimiters.
 * Only offically released versions of the program get version numbers.
   Development snapshots don't. Nor do test releases.
 * If the last component is zero, it may be omitted. Do not distinguish version
   X.Y from version X.Y.0.
 * Avoid using anything other than numbers in version numbers.


Debian version ordering formula.
--------------------------------

TODO

Semver version ordering formula.
--------------------------------
::

  if (A.major != B.major) return A.major > B.major;
  if (A.minor != B.minor) return A.minor > B.minor;
  if (A.patch != B.patch) return A.patch > B.patch;
  if (A.special == B.special) return 0;
  if (A.special == "") return 1;
  if (B.special == "") return -1;
  return A.special > B.special;

**NOTE** Accoding to this definition 1.0.1rc1 < 1.0.1rc10 < 1.0.1rc2 which is
non meaningful.

Odd/even numbering.
-------------------

Who use:

  GLib GTK+ Gimp GNOME Kaffe

Forms of compatibility.
=======================

Runtime of binary compatibility mean that binary can be swaped with another
version without breaking.

Compile time or source compatibility mean that supplied header/interfaces allow
successful compiling/linking.

Examples:

 * Change type of argument in method to more generic take source compatibility
   but break binary compatibility.
 * Adding new mothod to abstract class take binary compatibility but break
   compilation (unimplement method error).

File format compatibility.

Protocol compatibility.

Compatibility formula.
======================

Assume that app linked with new version of lib. Thus::

  is_compatible_with_old(old, new) {
    if (old.major != new.major) return 0;
    if (old.minor > new.minor) return 0;
    return 1;
  }

Assume that app linked with old version of lib. Thus::

  is_compatible_with_new(old, new) {
    if (old.major != new.major) return 0;
    return 1;
  }

Reference.
==========

  https://developer.mozilla.org/en/toolkit_version_format
                Toolkit version format
  http://apr.apache.org/versioning.html
                APR's Version Numbering
  http://semver.org/
                Semantic Versioning