| Revision History | ||
|---|---|---|
| Revision 2.0.4 | Feb 9, 2004 | Revised by: JN |
| Updated release constant definition to remove provision for release constants of zero (0), see FAQ 2. | ||
| Revision 2.0.3 | Nov 24, 2003 | Revised by: JN |
| Added clarification to the vendor tag. An empty vendor tag is now valid in certain situations which is now illustrated in some of the updated examples. | ||
| Revision 2.0.2 | Nov 8, 2003 | Revised by: JN |
| Added notes in the glossary concerning the epoch. | ||
| Revision 2.0.1 | Oct 30, 2003 | Revised by: JN |
| Fixed a number of typos in version examples. | ||
| Revision 2.0.0 | Oct 24, 2003 | Revised by: JN |
| Overhauled versioning rules so that the release constant is the most significant part of the lindows portion of the downstream number. Added initial version component table, import policy, FAQ, version examples, new glossary entries and other cleanups. | ||
| Revision 1.1.0 | Oct 16, 2003 | Revised by: JN |
| Updated versioning rules to new spec, improved introduction, added definition for release constant. | ||
| Revision 1.0.2 | Oct 6, 2003 | Revised by: DS |
| Fleshed out some definitions. | ||
| Revision 1.0.1 | Oct 6, 2003 | Revised by: JN |
| Initial document created. | ||
Package versioning is very important because:
It reveals important details about the contents of the package and how it was constructed.
It shows which upstream debian package it is based on (if any).
It shows which release the package was built for.
It provides information about what kind of changes where made to the package (ie: upstream changes, downstream changes, build dependency changes, etc.) as well as who made the changes (ie: Debian, Lindows.com, NMUs, etc.)
It provides a total, consistent ordering on all packages created, regardless of which release the package was built for. This allows us to accurately compare versions and report and track changes. It also makes things like upgrading possible both within a release and from release to release.
These advantages can only be realized when the following fundamental rules of versioning are followed:
No packages with the same name and version number can contain different contents. This creates confusion and makes changes impossible to track.
No packages with the same name and different version numbers can contain the same contents. A violation here is not as serious as rule 1 above, but is serious nonetheless. When this happens, it indicates that there are superfluous builds happening. Since every proper version number change indicates in some way how the package changed, the new version will be misleading because no change really happened. When this rule is ignored, people can no longer read version numbers accurately because they cease to become meaningful. (In the real world, sometimes superfluous builds happen. This is ok every once in a while, but the point is that it should never become the normal case).
A version is an ordered collection of fields, as described in the definition.
Once you understand the different types and specifications, reading version numbers becomes easy: There are two types of package versions that we deal with at Lindows.com.
Debian Versions
Table 1. Debian Version Specification
| Field | Description | Optional | Starting point | |
|---|---|---|---|---|
| Section | Name | |||
| epoch | definition | yes (although if so, the upstream section may not contain any colons (:)). If omitted, the value is implicitly 0. | n/a | |
| upstream | definition | no | n/a | |
| downstream | packaging revision | definition | yes | 1 |
| non maintainer upload | definition | yes | 1 | |
| recompilation only | definition | yes | 1 | |
Examples:
3:1.8.2-17. This is the seventeenth debian packaging revision of the upstream source 1.8.2 with an epoch of 3 applied.
2.4-7.0.2. This is the second debian re-compilation only of the seventh debian packaging revision of the upstream source 2.4.
2:1:1.0-0.0.2003.10.23-2-9.4.1. This is the first debian re-compilation only of the fourth debian non-maintainer upload of the ninth debian packaging revision of the upstream source '1:1.0-0.0.2003.10.23-2'.
Lindows Versions
Table 5. Lindows Version Specification
| Field | Description | Optional | Starting point | |
|---|---|---|---|---|
| Section | Name | |||
| epoch | definition | yes (although if so, the upstream section may not contain any colons). If omitted, the value is implicitly 0. | n/a | |
| upstream | definition | no | n/a | |
| debian downstream | debian packaging revision | definition | yes | 1 |
| debian non maintainer upload | definition | yes | 1 | |
| debian recompilation only | definition | yes | 1 | |
| lindows downstream | lindows release constant | definition | yes | n/a |
| lindows vendor tag | definition (note: this is not an actual field, but rather part of the field separator between the lindows release constant and the lindows branch number). | yes | n/a | |
| lindows branch number | definition | yes | 0 | |
| lindows packaging revision | definition | yes | 1 | |
| lindows non maintainer upload | definition | yes | 1 | |
| lindows recompilation only | definition | yes | 1 | |
Examples:
1.1.0-17.0.0.45.0.0.0.1. This is the first lindows recompilation only against release 45 (coho) of the debian upstream package 1.1.0-17 (of which it is the seventeenth package revision of the upstream source 1.1.0).
Table 6. Lindows version: 1.1.0-17.0.0.45.0.0.0.1
| Field | Value |
|---|---|
| epoch | 0 (implicit) |
| upstream | 1.1.0 |
| downstream debian packaging revision | 17 |
| downstream debian non maintainer upload | 0 |
| downstream debian recompilation only | 0 |
| downstream lindows release constant | 45 |
| downstream lindows vendor tag | . (empty) |
| downstream lindows branch number | 0 |
| downstream lindows packaging revision | 0 |
| downstream lindows non maintainer upload | 0 |
| downstream lindows recompilation only | 1 |
1.4.9-17.3.0.50.lindows0.4. This is the fourth lindows packaging revision against release 50 (marlin) of the debian upstream package 1.4.9-17.3 (of which it is the third debian non-maintainer upload of the seventeenth debian package revision of the upstream source 1.4.9).
Table 7. Lindows version: 1.4.9-17.3.0.50.lindows0.4
| Field | Value |
|---|---|
| epoch | 0 (implicit) |
| upstream | 1.4.9 |
| downstream debian packaging revision | 17 |
| downstream debian non maintainer upload | 3 |
| downstream debian recompilation only | 0 |
| downstream lindows release constant | 50 |
| downstream lindows vendor tag | .lindows |
| downstream lindows branch number | 0 |
| downstream lindows packaging revision | 4 |
| downstream lindows non maintainer upload | 0 (implicit) |
| downstream lindows recompilation only | 0 (implicit) |
5.2-0.0.0.40.lindows1.1.0.8. This is the eighth lindows recompilation only of the first lindows packaging revision on the lindows branch one against release 40 (prickleback) of the upstream debian package 5.2 (of which based on the upstream source 5.2 with no debian package revisions listed).
Table 8. Lindows version: 5.2-0.0.0.40.lindows1.1.0.8
| Field | Value |
|---|---|
| epoch | 0 (implicit) |
| upstream | 5.2 |
| downstream debian packaging revision | 0 |
| downstream debian non maintainer upload | 0 |
| downstream debian recompilation only | 0 |
| downstream lindows release constant | 40 |
| downstream lindows vendor tag | .lindows |
| downstream lindows branch number | 1 |
| downstream lindows packaging revision | 1 |
| downstream lindows non maintainer upload | 0 |
| downstream lindows recompilation only | 8 |
0.8-7.0.0.45.contrib0.1. This is the first packaging revision by a publisher, which was built against release 45 (coho), based on the upstream debian package 0.8-7 (which is the seventh debian packaging revision of the upstream source 0.8).
Table 9. Lindows version: 0.8-7.0.0.45.contrib0.1
| Field | Value |
|---|---|
| epoch | 0 (implicit) |
| upstream | 0.8 |
| downstream debian packaging revision | 7 |
| downstream debian non maintainer upload | 0 |
| downstream debian recompilation only | 0 |
| downstream lindows release constant | 45 |
| downstream lindows vendor tag | .contrib |
| downstream lindows branch number | 0 |
| downstream lindows packaging revision | 1 |
| downstream lindows non maintainer upload | 0 (implicit) |
| downstream lindows recompilation only | 0 (implicit) |
5.8.1-3.0.0.45.0.0.0.1. This is the first lindows recompilation only against release 45 (coho) of the debian upstream package 5.8.1-3 (of which it is the third package revision of the upstream source 5.8.1).
Table 10. Lindows version: 5.8.1-3.0.0.45.0.0.0.1
| Field | Value |
|---|---|
| epoch | 0 (implicit) |
| upstream | 5.8.1 |
| downstream debian packaging revision | 3 |
| downstream debian non maintainer upload | 0 |
| downstream debian recompilation only | 0 |
| downstream lindows release constant | 45 |
| downstream lindows vendor tag | . (empty) |
| downstream lindows branch number | 0 |
| downstream lindows packaging revision | 0 |
| downstream lindows non maintainer upload | 0 |
| downstream lindows recompilation only | 1 |
We are downstream from the downstream maintainers of Debian, and we must take care not to interfere with the Debian versioning scheme; we want to be able to tell when there are packages in Debian that supersede ours. The Debian Policy Manual and Debian Developer's Reference specify several "magic" properties of versions that we must preserve in our versioning. Even in cases where we are the upstream maintainers of a package that is not in Debian and never will be in Debian, we still must preserve the debian portion of the downstream version. (For a detailed explanation why, see FAQ 1.
The first three fields in the release version are reserved for Debian. The first numeric field in the release version is the Debian revision; the second numeric field is reserved for non-maintainer uploads, and the third numeric field is reserved for recompilation-only uploads. Therefore, any package modifications we do should result in changes to the release version only after the third numeric field. If all three numeric fields do not exist in the current version, zeroes must be inserted as placeholders.
Lindows.com versioning begins after the third separator field. The fourth field is the release constant. The next field separator indicates the vendor tag (ie: '.lindows' for Lindows.com packages, '.contrib' for packages contributed by the publisher program). The fifth field is the downstream lindows branch number (starting with zero). The next three fields (fields six through eight) are used exactly as Debian uses the first three. Fields after the eighth are reserved for the warehouse program when performing binary package mangling.
For example, if the Debian version of apache is 2.0-3, a Lindows.com revision of that package compiled for the coho distribution (release constant 45) would be 2.0-3.0.0.45.lindows0.1. If the next change was a simple recompilation-only, the version would become 2.0-3.0.0.45.lindows0.1.0.1. Next, if there was a packaging revision made, the version would become 2.0-3.0.0.45.lindows0.2.
As a more advanced example, if apache is then just recompiled for the marlin release (release constant 50), the version would become 2.0-3.0.0.50.lindows0.2.0.x, where x = the next available downstream lindows recompilation only field in marlin of all versions of apache matching 2.0-3.0.0.50.lindows0.2.0.*.
If a package is imported into a release, the following rules must be satisfied:
The package version must be less than or equal to the version of that package in all releases greater than the release being imported to.
Question. Why must packages which have an upstream source that originates at Lindows.com pad the 3 debian downstream fields with zeros (0)? For these packages, can we not drop these 3 fields because this package never has and never will go to Debian?
Answer. The reason we must keep these 3 fields is because the warehouse could mangle the package version. In this case, it needs to pad the appropriate number of fields with zero (0) so that any "real" downstream change in the future will supercede it. If the numbers of fields were different in the two schemes, we would have to be able to determine what scheme the package was using in order to add the proper number of padded fields. However, this would be impossible to determine because a version like 2.0 (with no downstream number), is valid in both schemes.
Question. Why is the release constant a required field? Why can't it be implicitly or explicitly zero (0) indicating that it is release neutral (meaning no build dependencies)?
Answer. Nothing is release neutral because it always has some build dependencies, even if at the very least it's just the build essential packages (ie: dpkg-dev, debhelper, etc.). Furthermore, if the release constant was explicitly zero (0), and it was mangled, it's version number would potentially collide with other packages in other releases.
A package version is a string describing the version of that package. It is composed of an upstream version and optionally an epoch and/or a release version, in the form: [epoch:]upstream_version[-release_version].
From the Debian Policy Manual: 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 upstream_version may contain only alphanumerics and the characters . + - : (full stop, plus, hyphen, colon) 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.
From the Debian Policy Manual: " This is a single (generally small) unsigned integer. It may be omitted, in which case zero is assumed. This is a single (generally small) unsigned integer. It is used 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. It should only be used for this purpose. "
Note: The epoch should should never, under any circumstances, be incremented on packages that originate from debian. The epoch is only used by debian to fix old versioning problems. We cannot use it or else we make it impossible to ever be superceded by the original debian package which is something that the new versioning scheme makes provision for.
From the Debian Policy Manual: 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 + and . (plus and full stop).
The Debian Developer's Reference also specifies several "magic" fields in the release version. The first numeric field is the revision; the second numeric field is reserved for non-maintainer uploads, and the third numeric field is reserved for recompilation-only uploads. Therefore, any modifications we do to packages should result in changes to the release version only after the third numeric field.
Indicates a Debian packaging revision. Counting for this field begins at 1. Every time it increments, the following fields are reset:
downstream debian non maintainer upload field is reset to 0 (implicitly).
downstream debian recompilation only field is reset to 0 (implicitly).
Indicates a Debian non-maintainer upload. Counting for this field begins at 1. Every time it increments, the following fields are reset:
downstream debian recompilation only field is reset to 0 (implicitly).
Indicates a Debian recompilation only change. Counting for this field begins at 1.
The first portion of the Lindows.com downstream release. This numeric field is fixed per release. This is a required field. The following release constants are defined thus far:
40 prickleback
45 coho
50 marlin
60 skipjack
Note: When this field changes, no fields are reset, however at least a recompilation change must accompany this change.
This denotes the vendor that owns the lindows branch field and the lindows package revision field.
Valid values:
".contrib": The vendor is a developer in the publisher program (actual person is in the 'Maintainer' field in the package).
".lindows": The vendor is Lindows.com.
"." (empty): There is no vendor. In other words, the lindows branch field and the lindows package revision field are both zero (ie: have not been claimed yet).
Indicates a Lindows branch. Counting for this field begins at 0. Every time it increments, the following fields are reset:
downstream lindows packaging revision is reset to 1.
downstream lindows non maintainer upload field is reset to 0 (implicitly).
downstream lindows recompilation only field is reset to 0 (implicitly).
Indicates a Lindows packaging revision. Counting for this field begins at 1. Every time it increments, the following fields are reset:
downstream lindows non maintainer upload field is reset to 0 (implicitly).
downstream lindows recompilation only field is reset to 0 (implicitly).
Indicates a new Lindows non-maintainer upload. Counting for this field begins at 1. Every time it increments, the following fields are reset:
downstream lindows recompilation only field is reset to 0 (implicitly).
Indicates a Lindows recompilation only change. Counting for this field begins at 1.
Synonymous with a downstream version.
Synonymous with a downstream version.
A contiguous portion of the version containing either entirely numeric characters or entirely non-numeric characters, bounded by either fields of the other type or by either end of the version.
A version field composed entirely of numeric characters.
A version field composed entirely of non-numeric characters.
A non-numeric field with at least 1 period (.).