+
−.. -*- coding: utf-8; -*-
+
−.. include:: HEADER.rst
+
−
+
−=================
+
− 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.
+
−
+
−Version in package/release name.
+
−================================
+
−::
+
−
+
−  PACKAGE-MAJ.MIN.FIX.tar.gz   (Common style)
+
−  PACKAGE-MAJ.MIN.FIX.zip
+
−  PACKAGE-MAJ.MIN.FIX-DISTROFIX.tar.gz  (Cygwin style)
+
−  PACKAGE_EPOCH:MAJ.MIN.FIX-DISTROFIX_ARCH.deb (Debian style)
+
−
+
−From "Debian Policy Manual"::
+
−
+
−  Package names must consist only of lower case letters (`a-z'), digits
+
−  (`0-9'), plus (`+') and minus (`-') signs, and periods (`.').  They
+
−  must be at least two characters long and must start with an
+
−  alphanumeric character.
+
−
+
−If you look carefully there are no any ``_`` (underscore) chars!! Also ``-`` is
+
−portable char in file name accoding to POSIX.
+
−
+
−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.
+
−
+
−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;
+
−  }
+
−
+
−Versioning for products.
+
−========================
+
−
+
−Versioning for products differ from versioning for libraries.
+
−
+
−Product is a set of conponents that stalled to some versions. Components can be
+
−switches as written for library versioning:
+
−
+
− * Any fix releases interchanged, greater version mean less bug count.
+
− * Any minor release interchanged with next minor releases.
+
− * Major release does not interchanged at all, switching from old to new require
+
−   upgrade.
+
−
+
−Product update vs upgrade.
+
−--------------------------
+
−
+
−Product update involve:
+
−
+
− * Replacing product executable files, resources files.
+
− * Config files and user data stay unchanged.
+
−
+
−Product upgrade involve:
+
−
+
− * Replacing product executable files, resources files.
+
− * Config files and used data require modification and performed by upgrade
+
−   scripts or manually by user (if this is ever possible).
+
−
+
−Build 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 build 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 does not exist tools for easy querying for status of build by its
+
−   number (as ok/fail, build configuration, date, coverage, lint checks status,
+
−   etc).
+
− * Some part of development team may not have permission for bumping version and
+
−   they must revert some automatically updated files after build.
+
−
+
−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.
+
−--------------------------------
+
−
+
−The version number of a package.  The format is::
+
−
+
−  [<epoch>`:']<upstream_version>[`-'<debian_revision>]
+
−
+
−The three components here are:
+
−
+
−``epoch``
+
−     This is a single (generally small) unsigned integer.  It may be
+
−     omitted, in which case zero is assumed.  If it is omitted then
+
−     the <upstream_version> may not contain any colons.
+
−
+
−     It is provided to allow mistakes in the version numbers of older
+
−     versions of a package, and also a package's previous version
+
−     numbering schemes, to be left behind.
+
−
+
−``upstream_version``
+
−     This is the main part of the version number.  It is usually the
+
−     version number of the original ("upstream") package from which
+
−     the ``.deb`` file has been made, if this is applicable.  Usually
+
−     this will be in the same format as that specified by the upstream
+
−     author(s); however, it may need to be reformatted to fit into the
+
−     package management system's format and comparison scheme.
+
−
+
−     The comparison behavior of the package management system with
+
−     respect to the <upstream_version> is described below.  The
+
−     <upstream_version> portion of the version number is mandatory.
+
−
+
−     The <upstream_version> may contain only alphanumerics[1] and the characters
+
−     ``.`` ``+`` ``-`` ``:`` ``~`` (full stop, plus, hyphen, colon, tilde) and
+
−     should start with a digit. If there is no <debian_revision> then hyphens
+
−     are not allowed; if there is no <epoch> then colons are not allowed.
+
−
+
−``debian_revision``
+
−     This part of the version number specifies the version of the
+
−     Debian package based on the upstream version.  It may contain
+
−     only alphanumerics and the characters ``+`` ``.`` ``~`` (plus, full
+
−     stop, tilde) and is compared in the same way as the
+
−     <upstream_version> is.
+
−
+
−     It is optional; if it isn't present then the <upstream_version>
+
−     may not contain a hyphen.  This format represents the case where
+
−     a piece of software was written specifically to be turned into a
+
−     Debian package, and so there is only one "debianisation" of it
+
−     and therefore no revision indication is required.
+
−
+
−     It is conventional to restart the <debian_revision> at ``1`` each
+
−     time the <upstream_version> is increased.
+
−
+
−     The package management system will break the version number apart
+
−     at the last hyphen in the string (if there is one) to determine
+
−     the <upstream_version> and <debian_revision>.  The absence of a
+
−     <debian_revision> compares earlier than the presence of one (but
+
−     note that the <debian_revision> is the least significant part of
+
−     the version number).
+
−
+
−The <upstream_version> and <debian_revision> parts are compared by the
+
−package management system using the same algorithm:
+
−
+
−The strings are compared from left to right.
+
−
+
−First the initial part of each string consisting entirely of non-digit
+
−characters is determined.  These two parts (one of which may be empty)
+
−are compared lexically.  If a difference is found it is returned.  The
+
−lexical comparison is a comparison of ASCII values modified so that
+
−all the letters sort earlier than all the non-letters and so that a
+
−tilde sorts before anything, even the end of a part.  For example, the
+
−following parts are in sorted order from earliest to latest: ``~~``,
+
−``~~a``, ``~``, the empty part, ``a``.[2]
+
−
+
−Then the initial part of the remainder of each string which consists
+
−entirely of digit characters is determined.  The numerical values of
+
−these two parts are compared, and any difference found is returned as
+
−the result of the comparison.  For these purposes an empty string
+
−(which can only occur at the end of one or both version strings being
+
−compared) counts as zero.
+
−
+
−These two steps (comparing and removing initial non-digit strings and
+
−initial digit strings) are repeated until a difference is found or
+
−both strings are exhausted.
+
−
+
−Note that the purpose of epochs is to allow us to leave behind
+
−mistakes in version numbering, and to cope with situations where the
+
−version numbering scheme changes.  It is _not_ intended to cope with
+
−version numbers containing strings of letters which the package
+
−management system cannot interpret (such as ``ALPHA`` or ``pre-``), or
+
−with silly orderings (the author of this manual has heard of a package
+
−whose versions went ``1.1``, ``1.2``, ``1.3``, ``1``, ``2.1``, ``2.2``,
+
−``2`` and so forth).
+
−
+
−[1]  Alphanumerics are ``A-Za-z0-9`` only.
+
−
+
−[2]  One common use of ``~`` is for upstream pre-releases.  For example,
+
−     ``1.0~beta1~svn1245`` sorts earlier than ``1.0~beta1``, which sorts
+
−     earlier than ``1.0``.
+
−
+
−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.
+
−=======================
+
−
+
−Backward/forward compatibility.
+
−-------------------------------
+
−
+
−Backward compatibility for library, file format, protocol means that new version
+
−of program can work with old library, file format, protocol.
+
−
+
−Forward compatibility for library, file format, protocol means that old version
+
−of program can work with new library, file format, protocol but without using
+
−any benefits from new versions and more essentially without posibility damage
+
−any user data.
+
−
+
−Example of backward compatibility: adding to graphic library new image format
+
−for reading/saving.
+
−
+
−Example of forward compatibility: old browser ignore any new (unknown) HTML
+
−tags.
+
−
+
−Source/binary compatibility.
+
−----------------------------
+
−
+
−Runtime or binary compatibility mean that binary can be swaped with another
+
−version without breaking normal program work.
+
−
+
−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 method to abstract class take binary compatibility but break
+
−   compilation (unimplement method error).
+
−
+
−Format or protocol compatibility.
+
−---------------------------------
+
−
+
−File format or protocol backward compatibility mean that new program can use old
+
−format or protocol.
+
−
+
−In order to do that file format or protocol MUST store or provide some
+
−versioning information. Usually this done by:
+
−
+
− * Separate versioning field in data.
+
− * New prefix or name in data.
+
− * List of feature requirements, supported algorighm, etc.
+
−
+
−It is essential to make code that detect unknown or possibly new format or
+
−protocol and stop working with them to avoid user data corruption.
+
−
+
−It is essential to make file format or protocol extensible. This can be achieved
+
−by:
+
−
+
− * Reserving some possible names/prefixes for future use.
+
− * Generalising file format or protocol to envelop more cases.
+
−
+
−Extracting version from VCS.
+
−============================
+
−
+
−Including version in sources.
+
−=============================
+
−
+
−Don't use any ``$REVISION`` like keywords (usual practice in CVS, SVN)!
+
−
+
−Use sed, awk, M4 or any other preprocessor for non-compiled or non-preprocessed
+
−files (like .lisp, .py, .java files)::
+
−
+
−  $ cat my-version.el.in
+
−  (defvar my-major-version @VMAJOR@
+
−    "Major version.")
+
−  (defvar my-major-version @VMAJOR@
+
−    "Major version.")
+
−  (provide 'my-version)
+
−
+
−  $ cat Makefile
+
−  %: %.in
+
−      sed -e 's|@VMAJOR@|$(VMAJOR)|' -e 's|@VMINOR@|$(VMINOR)|' <$< >$@
+
−
+
−Pass version component to preprocessed file (like .c, .cxx files) through
+
−preprocessor::
+
−
+
−  $ cat my-version.c
+
−  int get_major_version() { return VMAJOR; }
+
−  int get_minor_version() { return VMINOR; }
+
−
+
−  $ cat Makefile
+
−  %.o: %.c
+
−      $(CC) -DVMAJOR=$(VMAJOR) -DVMINOR=$(VMINOR) -o $@ $<
+
−
+
−Reference.
+
−==========
+
−
+
−  http://semver.org/
+
−                Semantic Versioning
+
−  http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version
+
−                Debian
+
−  http://www.openbsd.org/faq/ports/specialtopics.html
+
−                OpenBSD
+
−  http://java.sun.com/j2se/versioning_naming.html
+
−                Oracle
+
−  http://www.intel.com/support/graphics/sb/CS-020667.htm
+
−                Intel
+
−  http://wiki.eclipse.org/index.php/Version_Numbering
+
−                Eclipse
+
−  http://apr.apache.org/versioning.html
+
−                Apache
+
−  http://www106.pair.com/rhp/parallel.html
+
−                Conflict resolution
+
−  http://www.rpm.org/wiki/PackagerDocs/Dependencies
+
−                RH
+
−  http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html
+
−                RH
+
−  http://fedoraproject.org/wiki/Packaging/NamingGuidelines
+
−                RH
+
−  http://wikis.sun.com/display/IpsBestPractices/Packaging+Best+Practices+-+Versioning
+
−                Oracle
+
−  http://docs.codehaus.org/display/MAVEN/Dependency+Mediation+and+Conflict+Resolution
+
−                Maven
+
−  http://docs.codehaus.org/display/MAVEN/Versioning
+
−                Maven
+
−