Packaging Best Practices - Versioning

h1. Overview

Consistent treatment of package versions help address the following interests:
* Helps customers understand the level of change and degree of compatibility represented in updated software.
* Helps set the stage for accurate dependency specification.
* Build identifiers enable Sun to distinguish amongst similar, but different deliveries of the same package.
* Helps ease the process by which interim fixes are made available to customers.

The Image Packaging System uses the following version syntax:
{noformat}
<component-version>,<built-on-version>-<branch-version>:<publish-time-stamp>
{noformat}
For example:
{noformat}
pkg:/wxpython2.8-minimal@2.8.8,0-13.1055:20080805T201347Z
{noformat}
Where:
|| Version Field || Description || Example ||
| {{component-version}} | is the dotted decimal version of the component. Typically taken from the actual version of the original open source or source project. | {{2.8.8}} |
| {{built-on-version}} | is intended to represent the minimum OS version the package will work on. Currently, this field is used only for packages delivered into the OpenSolaris OS distribution. It does not readily apply to packages delivered for other OS platforms or for packages used in an unbundled manner on top of OpenSolaris. | {{0}} |
| {{branch-version}} | is a dotted decimal package revision number. Enables package authors and distributions to provide distro-specific versioning information that qualifies the {{component-version}}. Typical values used here are: project build numbers and monotonically increasing package versions. | {{13.1055}} |
| {{publish-time-stamp}} | is automatically set each time you publish the package. Even if you don't change the version number, the publish time stamp will change. | {{20080805T201347Z}}\\
\\
The {{Z}} represents "Zulu" time or Universal Coordinated Time (UTC). |
{note:title=Only Numeric Values Are Allowed}
Only dot-separated numeric values are allowed in the version fields. If the component you are packaging has historically used a non-numeric version string, then map that to a numeric version for the official package version, and put the non-numeric version in the package description.

Since version comparisons a performed on a numerical basis, {{01.02}} is equivalent to {{1.2}}.
{note}

h1. Best Practices

|| \# || Title || Description ||
| 1. | Reuse upstream project versions in {{component-version}} | To help users correlate the versions of your packages with the versions of the upstream project releases, you should try to represent the base version level of the component as used in the upstream project in the {{component-version}} portion of the package version. |
| 2. | For newly determined versions, use conventional major.minor.micro numbering | When your project is assigning a {{component-version}} rather than inheriting it from an upstream project, you should follow this advice.\\
\\
See the [Futher Details|#section-2] section for more information. |
| 3. | Syncrhonize {{component-version}} across OS platforms | When delivering platform-specific binaries of the same component in different packages, try to use the same {{component-version}} value. As needed, use the {{branch-version}} portion of the package version to represent different levels of platform-specific change across the same named and generally same component versions of packages. Any version number difference must reflect an unsynchronized release schedule or an actual difference in features between platforms. |
| 4. | Use {{branch-version}} to represent both component and package build levels | You will often need to maintain the component's upstream version number in {{component-version}}, but also reflect in the overall package version your own build level of the package. In these cases, consider using the {{branch-version}} to represent your own change level of the package.\\
\\
Also consider explicitly noting the build level of a package within the {{branch-version}}\\
\\
See the [Further Details|#section-4] section for more information. |
| 5. | Maven, OSGi and pkg(5) versioning | If you want to use Maven artifacts during development and/or OSGi artifacts wrapped in pkg(5) packages as a way to deliver new and updated runtime binaries to OSGi-based runtimes, you'll probably want to align versioning of these artifacts. In doing so you need consider the version specification constraints of each technology.\\
\\
See the [Further Details|#section-5] section for more information. |
| 6. | Use {{summary}} and {{description}} to convey quality levels | Since only numeric values are allowed in the version fields, when you need to convey that a package is of a certain quality level, e.g. "alpha", "beta", etc, you are encouraged to represent the quality level in the {{summary}} and {{description}} attributes of your package. As the package progresses to high levels of quality, you can modify the value of these attributes to convey the revised level of quality.\\
\\
Refer to the [Summary and Description|Packaging Best Practices - Summary and Description] best practices for details. |
| 7. | Consider dependency specifications | When determining versions of your packages, consider how your project and other projects may refer to your package's version via package level dependency actions. Refer to the [Dependencies|Packaging Best Practices - Dependencies] best practices for more details. |

h1. Further Details

{anchor:section-2}

h2. Conventional major.minor.micro Version Numbering

When you are not simply reusing an upstream project's version number and your are assigning a new {{component-version}}, consider these conventions.

Version numbers should be in three number dotted form. Version numbers should conform to the following string format:
{noformat}
X[.Y[.Z]]
{noformat}
Where {{.Y}} and {{.Z}} are optional. In some cases a product may have the need for a "Patch" level which adds a fourth dotted number ({{X.Y.Z.P}})
|| Level || Description ||
| Major | Major number changes should introduce significant software functionality or architectural changes. The lifetime of a major version can be expected to be quite long. It is expected to serve as the foundation for many minor and micro releases. A new version is the time obsolete hardware platforms, interfaces, and file formats. Installing the new version may require a complete install, rather than a simple upgrade, though a migration path must be provided for users of the current version. |
| Minor | Minor number changes signals that a software release contains either new, non-interfering features and architectural changes, or bug fixes. Each minor release must contain all the changes introduced in previous minor releases against the same major release. Interfaces may only be obsoleted by a minor release after a suitable warning and phase\- out period. Minor releases should occur at regular, predictable intervals. |
| Micro | Micro releases are scheduled as necessary to introduce bug fixes or support new hardware platforms -- their primary purpose is to sustain a particular version family, although they may contain minor, safe, compatible features as well. For Sun products micro releases are often called Updates. Each micro release must contain all changes introduced since the last minor release, as well as all patches made available since the last minor release. Interfaces must not be obsoleted by a micro release.\\
\\
Micro may not be relevant when the upstream project does not reflect a micro level of change or when this level of change is reflected in the {{branch-version}} of your package. |
| Patch | A patch release is similar to a Micro release except that it contains a smaller amount of change: no features and fewer fixes. Generally speaking the use of patch releases is discouraged unless for some reason you have a need to create a sustaining tail on a Micro (Update) release. Like Micro releases, Patch releases are cumulative.

Note that if you need to ship a point fix, or a hot fix those are typically represented by incrementing the {{branch-version}} as described below.

{anchor:section-4}

h2. Use {{branch-version}} to represent both component and package build levels

In situations where you do not expect to increment the {{component-version}} to represent your own update or fix level for a package, you should consider representing those change levels in the {{branch-version}} portion of the package version.

Even if you intend to represent the update or fix level of a package in the {{component-version}} part, you should consider representing the package build level in the {{branch-version}} portion of the package version.

In these situations, the {{branch-version}} can be treated as either a multi-part value with a "dot" (.) separator. For example, two fields in {{branch-version}} can be:
{noformat}
<component-version>,<built-on-version>-<component-build-level>.<package-build-level>:<publish-time-stamp>
{noformat}
|| {{branch-version}} Fields || Description ||
| {{component-build-level}} | A means for a package maintainer to track change levels of the package that are not reflected in the upstream project's version and are not reflected in the {{component-version}} portion of the package's version.\\
\\
Optional depending on whether you are using the {{component-version}} portion for this purpose. |
| {{package-build-level}} | A means for package maintainers to identify specific iterations or builds of a package. |
This approach is intended to meet the following requirements:
# Different builds of a package integrated into a release dock must have unique {{branch-version}} fields if they share the same package name and {{component-version}} field strings. The point of this requirement is to head of errors in Q/A testing and release. (Although the automatically generated publish time stamp offers an additional level of assurance that packages will be treated as distinct, using explicit and simple numbers to represent new deliveries of a package is generally viewed as a useful).
# The pair of {{component-version}} and {{branch-version}} must advance to numerically greater values with each release. Users must be able to assume that a package with a greater combined {{component-version}} and {{branch-version}} value supersedes a package with a smaller value.
# It must be possible to ship a new "urgent" or "critical" update package, containing fixes to newly discovered critical bugs, after a package with the same base version has been released.

h3. {{component-build-level}} and {{package-build-level}} Usage Guidance

Use the {{component-build-level}} portion of the {{branch-version}} to indicate new incremental update or fix levels of the package. You may choose to align this number with an overarching update level of your component or simply the project build number associated with the delivery of these updates or fixes.

For example, if your project is delivering "Update 1" of a package and you elect to not modify the {{component-version}}, you can simply set the {{branch-version}} to "1.x" where "1" represents "Update 1" and ".x" represents iterations (or builds) of the package leading up to the final release of the "Update 1" version of the package.

If your project produces formal deliveries of packages as development builds, you may choose to represent the formal build number in the {{component-build-level}} and represent iterations of the package leading up to the final release of the build in the {{package-build-level}}.

Within a particular {{component-version}} value, the {{component-build-level}} values should be ever increasing. Likewise, within a given value of {{component-build-level}}, the {{package-build-level}} should be ever increasing. When your package's {{component-version}} value changes, you may choose to reset the {{component-build-level}}. When {{component-build-level}} changes, you may elect to reset the {{package-build-level}}.

{anchor:section-5}

h2. Maven, OSGi, and pkg(5) Versioning

If you want to use Maven artifacts during development and/or OSGi artifacts wrapped in pkg(5) packages as a way to deliver new and updated runtime binaries to OSGi-based runtimes, you'll probably want to align versioning of these artifacts. In doing so you need consider the version specification constraints of each technology.

h3. Versioning in Maven

Maven supports any format for the version. If you use the recommended format given below, version comparison is based on the integer values of each part. If you do not use the recommended format, maven2 uses a string comparison. So you'll need to ensure that the ordering as a string is consistent with what you are expecting in choosing versions (i.e {{0.10.1.2 < 0.7.0.0}} i.e you need to keep the parts the same length) in case you are not following the recommended format. Either don't use number greater than nine or prefix the number with enough zeros if you are deviating from the recommended format.

Recommended format:
{noformat}
<major>.<minor>.<revision>(\[ \-<qualififer> \] \| \[ \-<build> \])
{noformat}
where:
* the qualifier section is optional (and is SNAPSHOT, alpha-1, alpha-2)
* the build section is optional (and increments starting at 1 if specified)
* any '0' build or revision elements can be omitted.
* only one of build and qualifier can be given (note that the timestamped qualifier includes a build number, but this is not the same)
* the build number is for those that repackage the original artifact (eg, as is often done with rpms)

You can read more about Maven versioning recommendations in the document {Dependency Mediation and Conflict Resolution|http://docs.codehaus.org/display/MAVEN/Dependency+Mediation+and+Conflict+Resolution].

h3. OSGi Versioning

The version format supported by OSGi is
{noformat}
<major>.<minor>.<micro>.<qualifier>
{noformat}
where major, minor and micro are numbers and qualifier is alphanumeric.
* <major> - indicates a significant update which doesn't guarantee any compatibility
* <minor> - indicates an update which preserves compatibility with older minor versions
* <micro> - represents an insignificant update from the user point of view which is perfectly compatible both forwards and backwards
* <qualifier> - is a user defined string - it is not widely used and can provide an additional label to the version number, such as the build number or target platform without a standardized meaning

The default version (if the attribute Bundle-Version is missing in the OSGi manifest file) is "{{0.0.0}}".

You can read more about OSGi bundle versioning in the document [Supporting OSGi Bundles in the Java Module System|http://openjdk.java.net/projects/modules/osgi-support-draft.html] (see section 4.2).

h3. Versioning for All Three Systems

The version should have three parts in it excluding the build number. That is <major>.<minor>.<revision/micro>. This format can be represented in all of the systems. If you want to include the build number in the version then,

pkg(5) FMRI:
{noformat}
pkg:/sample@1.0.7,0-1198:20080805T201347Z
{noformat}
and the OSGi version:
{noformat}
Bundle-Version = 1.0.7.1198
{noformat}
and the Maven2 version:
{noformat}
<version>1.0.7-1198<version>
{noformat}
where,

{{sample}} is the package name or OSGi bundle name or maven2 artifact
{{1.0.7}} is the version number {{1198}} is the build number.

The recommendation is not to have more than 3 parts in your version number excluding build number.Please insert 0 in <minor> or <revision/micro> level if you don't want to represent any of these parts in the version number.
{noformat}
pkg:/glassfish-web@3.0,0-14.1.6:20080805T201347Z
{noformat}

h1. Example

A development project maintains a package of the wxPython component. The version of wxPython as obtained from the upstream project is represented in the {{component-version}} portion of the package version. In the following example, {{2.8.8}} is the version obtained from the upstream wxPython project.

The package maintainers have elected to reflect their own ever increasing component build number and an SVN revision number in the {{component-build-level}} and {{package-build-level}} respectively of the {{branch-version}} portion of the package version.

{{pkg:/wxpython2.8-minimal@2.8.8,0-13.1055:20080805T201347Z}}

As planned modifications to the package and minor patches or fixes are made to the package contents, the package maintainers increment the {{component-build-level}} or the first portion of the {{branch-release}} area.

Each time the package is created to fix packaging and local fixes and enhancements to the base component version, the SVN revision number is updated to reflect the {{package-build-level}} in the second portion of the {{branch-release}} area. Doing so enables the development team to make changes in the context of a targeted update level while still tracking unique builds of the package. (A package maintainer may choose to depend on the automatically generated {{publish-time-stamp}} instead of maintaining an explicit {{package-build-level}}).

Once {{2.8.8,0-13.1055}} is made generally available and {{14.x}}, the next build level of the component is already development, the package maintainers may still make fixes to the {{13.x}} build level of the package and publish those fixes by modifying the content of the {{13.x}} version of the package and incrementing the {{package-build-level}}.

When a new version of wxPython is obtained from the upstream project, that new version is reflected in the {{component-version}} portion of the package version. In this case, the package maintainers may or may not reset the {{component-build-level}} of the {{branch-version}} portion.

h2. Variation: Multiple {{component-build-level}} Fields

If your project uses alphanumeric build numbers such as {{14a}}, you may choose to use {{14.1}} as a way of representing this build level within the {{component-build-level}}. If you still add a {{package-build-level}}, then you might end up with {{14.1.6}} where the {{6}} represents a simple, ever increasing integer reflecting the build level of the package.
{section}
{section}
{include:Footer}
{section}