Producing and Maintaining Packages
| 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). |
 | 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. |
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 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 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 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 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 best practices for more details. |
Further Details
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:
X[.Y[.Z]]
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.
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:
<component-version>,<built-on-version>-<component-build-level>.<package-build-level>:<publish-time-stamp>
| 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.
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.
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.
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:
<major>.<minor>.<revision>(\[ \-<qualififer> \] \| \[ \-<build> \])
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].
OSGi Versioning
The version format supported by OSGi is
<major>.<minor>.<micro>.<qualifier>
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 (see section 4.2).
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:
pkg:/sample@1.0.7,0-1198:20080805T201347Z
and the OSGi version:
Bundle-Version = 1.0.7.1198
and the Maven2 version:
<version>1.0.7-1198<version>
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.
pkg:/glassfish-web@3.0,0-14.1.6:20080805T201347Z
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.
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.