KEP:5

From Kolab Wiki

Revision as of 10:29, 24 August 2011 by Kanarip (Talk | contribs)
(diff) ← Older revision | Current revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Contents

This page is a draft only
It is still under construction and content may change. Do not rely on the information on this page.

KEP 5: Server Product Versioning

Status DRAFT
Type informational
Author Jeroen van Meeuwen
Revision ID 11708
Created 2010-11-18
Last Modified 2011-8-24
Latest Working Copy KEP-0005.txt
Tracker Ticket N/A

Abstract

The Kolab Groupware solution is deployed across many organisations, and certain administrator expectations are inherent to certain product version components. To consistently communicate the impact and implications of a certain release, for a certain component or for the complete suite, a product versioning standard must be formulated.

Major, Minor and Teeny

The Major.Minor.Teeny product versioning schema (usually represented as x.y.z) is commonly used amongst many of the Open Source development projects that form our various upstreams [1] [2] [3] [4], and thus this product versioning schema is most suitable for Kolab as well.

MMT Does not Do Pre-releases
Note that the Major.Minor.Teeny product versioning schema does not address pre-releases. See #Releases for more information on versioning pre-releases.


In general, the following versioning guidelines establish the base-line for product versioning. As different situations occur, these guidelines can be updated and amended, based on a case-by-case assessment of the situation.

The Major Version Component

An increment of the Major component of the version is often associated with a large change or set of large changes, and as such often causes the consumer to test the software, its features, and/or the upgrade path extensively despite whether Certified Binaries are available to that consumer. Additionally, the first minor or first few minors in a major series are often considered unstable and not suitable for large and/or mission-critical production environments.

The Major component in the product versioning shema MUST be incremented in any of the following situations;

  • No seamless (e.g. automatic without intervention, guaranteed) upgrade path exists,
  • No downgrade path exists (for purposes of failed upgrade rollbacks),
  • Manual intervention is required altering data (conversion of objects),
  • Changes to the product that entail functional changes, e.g. a change in how the product works or how administrators or users can, should or must work with the product,
  • backwards compatibility is broken (in terms of ABI, API and configuration changes).

The Major component MAY be incremented in any of the following situations;

  • To emphasize the importance of the milestone achieved,
  • To mark a point in time the versioning starts to conform to the guidelines documented here,
  • Based on community and/or release engineering/management consensus.

However, because incrementing the major version raises expectations and workload on the receiving end of the product, careful consideration is warranted.

The Minor Version Component

The general expectation formed with an increment of the Minor version component is to gain feature enhancements, such as performance increases, additional functions and/or components, and/or small rewrites of (parts of) code included in Kolab Groupware.

An increment of the Minor component of the version usually warrants the following actions on the consumer end;

  • Quick deployment of the former Minor version,
  • Test upgrade path,
  • Test base functionality,
  • Test new functionality.

The Minor component in the product versioning schema MUST be incremented in any of the following situations;

  • Feature enhancements that require additional configuration or setup are included in the release,
  • Despite whether the release contains only bug-fixes, the upgrade path is not seamless,
  • Backwards compatibility is being marked deprecated in any ABI, API or configuration, and as such issues warnings in a reasonable fashion,
  • Any of the components are upgraded, whether automatically or not.

The Minor component in the product versioning schema MAY be incremented in any of the following situations;

  • To emphasize the importance of the milestone achieved,
  • To mark the end of a time-based development cycle,
  • Based on community and/or release engineering/management consensus.

The Teeny Version Component

The Teeny Version SHALL only be incremented for bug-fix releases. Included with bug-fix releases are, of course, security fixes. The update MUST be seamless.

Release

Regular releases are versioned x.y.z, using the regular versioning schema, but pre-releases SHOULD NOT be versioned x.y.z.

Pre-releases

Upstream pre-releases are often simply appended to the x.y.z version: x.y.z-alpha1, x.y.z-beta2. However, this is only valid as long as the appended version component is logically greater then the previous appended version component, and does not apply to the move to the final release (e.g. updating x.y.z-rc1 to x.y.z).

Since, in conjunction with the aforementioned product versioning semantics, z in the situations of pre-releases is usually 0. Skipping the 0 in the product version entirely solves the complete problem. A beta1 pre-release for 2.5.0, which would traditionally become 2.5.0-beta1, would then become 2.5-beta1, allowing for an update to the 2.5.0 final version.

Exceptions for Unstable Bug-fix Releases
Exceptions can be made for bug-fix releases deemed unstable -maybe the bug-fix touched critical code and warrants testing. In such cases, consider using a one-time 4-octet release: x.y.z-rc1 for the pre-release, and x.y.z.0 for the final release; x.y.(z+1) can then upgrade from the final release. Be aware this type of exception only applies to pre-releases for bug-fix releases, should they be needed, as opposed to the general rule applying to pre-releases for Minor version component increments.


Releases and Native Packaging

The release of a product from upstream as version x.y.z of the product will descent on the native packaging of the product, but packaging implies yet one new component to the product; the packaging and building of the package.

To indicate one version of the package is newer then a former version of the package, the release component is incremented with every package build released. In fact, it should be incremented with every successful build of the package.

The first number in packaging for a final upstream release of the product is set to '1'. From there, it is to be incremented with steps of 1. Additionally, a distribution tag is often included with the release tag.

Pre-Releases and Native Packaging

In the case of package management such as APT or RPM, a release version is often included. While different platforms have different mechanisms to work around the issue of alpha- and beta-releases, and release candidates for a certain product version, we hereby set the following standard:

For a pre-release of product X.Y.Z, the release component in packaging shall include in the release tag;

  • A one-decimal float smaller then 1, to be incremented by 0.1 for each pre-release issued,
  • A . (dot) character,
  • The pre-release name, such as alpha, beta1, beta2, rc1, rc2,
  • (optionally) the distribution tag, if appropriate.

Such would build package file names such as: 

kolabd-2.3-0.1.beta1.el5       (initial upstream 2.3 beta1 release packaged for the Enterprise Linux 5 RPM-based distribution)
kolabd-2.3-0.2.beta1.el5       (initial upstream 2.3 beta1 release with packaging fix)
kolabd-2.3-0.3.beta2.el5       (initial upstream 2.3 beta2 release)
kolabd-2.3-0.4.rc1.el5         (initial upstream 2.3 release candidate 1 release)
kolabd-2.3.0-1.el5             (initial, final upstream 2.3.0 release)

For Debian (APT) packaging, this would be along the lines of: 

kolabd-2.3~beta1-0.1           (initial upstream 2.3 beta1 release packaged for current stable Debian)
kolabd-2.3~beta1-0.1~bpo50+1   (initial upstream 2.3 beta1 release packaged for current old-stable Debian (bpo50, where '50'
                               is supposed to indicate the Debian release version number the package is backported to))
kolabd-2.3~beta1-0.2           (initial upstream 2.3 beta1 release with packaging fix)
kolabd-2.3~beta2-0.3           (initial upstream 2.3 beta2 release)
kolabd-2.3~rc1-0.4             (initial upstream 2.3 release candidate 1 release)
kolabd-2.3.0-1                 (initial, final upstream 2.3.0 release)
Debian Version and Release Comparison Routine Requirement
Given that the DPKG compares epoch, upstream version and debian version much alike RPM does [5], it's policy depicts the upstream release is part of the upstream version component (i.e. 2.3~beta2 is the upstream version). This requires packagers to acknowledge upstream will have to name their pre-releases in alphabetical order which is most often the case for alpha, beta and rc releases, but does not necessarily have to hold true under all circumstances such as with a prealpha release[6].


References

  1. ↑ Cyrus IMAP, http://www.cyrusimap.org
  2. ↑ Postfix, http://www.postfix.org
  3. ↑ Horde, http://www.horde.org
  4. ↑ RoundCube, http://roundcube.net
  5. ↑ http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version
  6. ↑ http://en.wikipedia.org/wiki/Software_release_life_cycle

Copyright

This document is placed in the public domain.

Retrieved from "http://wiki.kolab.org/KEP:5"
Personal tools
Page Categories