eLxr package versioning

General Discussions
1

Summary

The goal is to provide a principle for eLxr package version strategy. It should be as concise and clear as possible to facilitate understanding and mastery

Both Ubuntu and eLxr are derived from Debian. Ubuntu rebuilds all packages from Debian. eLxr only rebuilds packages when we need to add changes, therefore Ubuntu package version strategy (Reference 1) can’t perfectly suit eLxr, but it should be a reference. On the other hand, beside Debian upstream, eLxr imports packages from the package upstream, and eLxr has own packages.

3 type packages

There are three types of packages in eLxr.

  • Debian package

  • Upstream package

    • The package is from package upstream or 3rd party, for example, trivy, cri-o

  • eLxr package

    • eLxr are the package the upstream, for example d2o tools, wr-elxr-pro

Basic pattern of package version

Debian supports 2 format packages, native and quilt. The Native package is modified directly on the source codes. It doesn’t have orig.tar.gz file, for example, desktop-base, base-files. The Quilt package needs to modify the source codes by adding patches in the debian/patches directory. It has orign.tar.gz file. Therefore, Native package doesn’t have revision (“-”) in version, but Quilt package must have revision (“-”).

Debian package

Quilt package: add elxrX appended to Debian revision

[upstream_version]-[debian_revision]elxr[elxr_revision]

Native package:

[debian_version]elxr[elxr_revision]

Upstream package

The package comes from package upstream instead of Debian. Normally, it should be quilt package to keep original source codes clean.

Add -elxrX append to upstream version

[upstream_version]-elxr[elxr_revision]

eLxr package

Normally, it should be native package since the package is own by eLxr.

Add elxrX append to package version.

[package_version]elxr[elxr_revision]

Adding a change

Changes require adding or incrementing the number immediately following the elxr string. Consequently, the first eLxr modification would have elxr1 appended to the Debian revision. Subsequent eLxr changes would increment this suffix, i.e. elxr1-->elxr2.

Here’s a listing of examples of the application of these rules:

Previous version Modification type Recommended version
13.8+deb13u1 eLxr change 13.8+deb13u1elxr1
13.8+deb13u1elxr1 eLxr change 13.8+deb13u1elxr2
0.66.0 eLxr change 0.66.0-elxr1

No-change Rebuilds

Sometimes a package has previously successfully built into eLxr, and still does not require changes to the packaging or source code, but the generated binaries do require rebuilding against newer versions of dependencies, for example kernel OOT drivers, when we upgrade kernel version, we need to rebuild OOT drivers, like qat, dpdk-kmods. In this case, nothing to change except for changelog.

In this case one would:

  • Adding a bX suffix appended to previous version

  • If there is already one such bX suffix present, increment it

  • Removing the bX once adding a new change

List of this evolution of versions and further related examples:

Previous version Modification type Recommended version
1.1.40-00018elxr6 No-change rebuild 1.1.40-00018elxr6b1
1.1.40-00018elxr6b1 No-change rebuild 1.1.40-00018elxr6b2
1.1.40-00018elxr6b2 eLxr change 1.1.40-00018elxr7
1.1.40-00018elxr7 No-change rebuild 1.1.40-00018elxr7b1

Upgrading a package

If eLxr has local changes to the package from Debian, eLxr developer rebases the local changes to new version package. The counter for eLxr increments resets to 1, therefore the version for the new upload to the eLxr mirror is the version from Debian with a suffix of elxr1. There are 2 scenarios:

  • Migrating local changes of a package from an old eLxr main release to a new main release, for example aria → bianca

  • When Debian delivers a new revision package in same main release, eLxr needs to upgrade to the revision and rebase local changes.

After upgrading new version package, eLxr developer needs to git cherry-pick all local commits on top and merges all modifications of changelog into one modification on top of changelog.

The idea is from Debian, that Debian doesn’t request a change must update changelog in developing phase, because the changes aren’t exposed to end users until release. When reaching a milestone, the package maintainer will update all previous changes in one changelog item and increase the package version.

The package upgrading is a chance to merge all previous changelog items and reset the eLxr revision to 1 to avoid the eLxr revision number is carried to next main version.

List of this evolution of versions and further related examples:

Previous version Modification type Recommended version Note
0.66-elxr2 eLxr change 0.66-elxr3
0.66-elxr3 eLxr change 0.66-elxr4
0.66-elxr4 upgrade package 0.68.2-elxr1 Merge 4 revision to 1
0.68.2-elxr1 eLxr change 0.68.2-elxr2

Adding Debian NMU (bN) into source package revision

Debian supports NMU update (Reference 2), that the source package version isn’t changed, but a suffix +b appended binary version, for example

Package Source version Binary version
busybox 1:1.35.0-4 1:1.35.0-4+b2

According to the above rules to add eLxr revision, the version will be changed to 1:1.35.0-4elxr1. In Debian’s version specification, 1:1.35.0-4+b2 is higher than 1:1.35.0-4elxr1, that misleads end users think the newer version is 1:1.35.0-4+b2, and they fail to get the eLxr changes.

$ dpkg --compare-versions 1:1.35.0-4elxr1 gt 1:1.35.0-4+b2 && echo true || echo false
false

To ensure that eLxr version is always higher than the original version, eLxr developer needs to apply the +b into source package version along with eLxr revision.

[upstream_version]-[debian_revision]+bNelxr[elxr_revision]

List of this evolution of versions and further related examples:

Previous version Modification type Recommended version Note
1:1.35.0-4 eLxr change 1:1.35.0-4+b2elxr1 There is +b in binary version
1:1.35.0-4+b2elxr1 eLxr change 1:1.35.0-4+b2elxr2
1:1.35.0-4+b2elxr2 No-change rebuild 1:1.35.0-4+b2elxr2b1 The fist b2 is Debian NUM update, the second b1 is eLxr No-change Rebuilds

Same version of a package in multi-releases

If two eLxr releases have the same version package, then this would make the package non-upgradable and cause a version conflict (two builds, but not the same). It rarely happens on upstream or native package. For example, there isn’t change of a native package between aria and bianca, To resolve this, add the numeric .YY.MM release version appended to elxrX.

List of this evolution of versions and further related examples:

Previous version Recommended version Note
0.66.0-elxr1 in 3 releases 0.66.0-elxr1 (aria) aria is the first release of eLxr, so no need to append release version
0.66.0-elxr1.26.04.01 (bianca)
0.66.0-elxr1.27.04.01 (next eLxr main release)

The idea is come from Ubuntu Version string format (Reference 1)

Kernel version

eLxr kernel is a special case. BSPs need to append a bundle of BSP changes, for example, NXP BSPs have 5000+ commits. If following standard process, it needs to add 5000+ local patch files in Debian folder, that‘s crazy. When upgrading kernel to next version, that needs to refresh the 5000+ local patches. If applying the 5000+ patches on top Linux git tree, it’s pretty easy to rebase the local commits via git rebase/merge commends. Consequently, all eLxr BSP changes are needed to pack into orig.tar.gz rather than debian.tar.xz, that requests to increase the package upstream version, please see the table below.

Previous version Modification type Recommended version
6.1.153-1 eLxr BSP change 6.1.153-elxr1-1
6.1.153-elxr1-1 eLxr BSP change 6.1.153-elxr2-1
6.1.153-elxr2-1 Upgrade kernel version 6.1.158-elxr1-1

linux_6.1.158.orig.tar.gz → linux_6.1.158-elxr1.orig.tar.gz

linux_6.1.158-1.debian.tar.xz → linux_6.1.158-elxr1-1.debian.tar.xz

Reference:

  1. https://documentation.ubuntu.com/project/how-ubuntu-is-made/concepts/version-strings/
2 Likes
2
  1. https://www.debian.org/doc/manuals/developers-reference/pkgs.html#binary-only-nmu
  2. 5. Control files and their fields — Debian Policy Manual v4.7.3.0
3

This topic was automatically closed 21 days after the last reply. New replies are no longer allowed.

5

eLxr Package Version Update

Table of Contents

  • 0 - Introduction
  • 1 - Updated version proposal
  • 2 - Addressing eLxr release needs
  • 3 - Interpreting version string

0 - Introduction

Due to the needs and challenges arising from how eLxr supports packages, the current version string policy leaves some gaps in terms of all the packaging scenarios we encounter. The current version string policy also has certain degree of deviance from Debian upstream. This version proposal aims to improve based on the existing version policy to address the aforementioned gaps and deviations.

1 - Updated version proposal

To understand the version string policy, first we need to understand native/non-native packages as they fundamentally change the version string syntax.

There are two fundamental types of packages - (1) native, or (2) non-native. A non-native package means that the source tree of this package is maintained by some third-party, and this third-party is called “the upstream”. A native package means that we eLxr maintains the source tree. For example, the cri-o package is non-native, since the source code is maintained by CRI-O upstream. On the other hand, the tiler package - part of eLxr’s distro-to-order (D2O) software bundle - is native, since eLxr maintains the source tree.

The version syntax is extended on the version syntax from Debian upstream defined in Debian Policy Manual - Section 5.6.12 Version.

1.1 - Version syntax for non-native packages

The following is a specification of the version syntax for non-native packages written in a modified Extended Backus-Naur form (EBNF).

<non_native_version> ::= [ <epoch> ":" ] <upstream_version> "-" <debian_revision>

<epoch> ::= # A single unsigned integer to track upstream version numbering scheme change.

<upstream_version> ::= <targeted_upstream_version> <repackage_suffix>*

<targeted_upstream_version> ::= # The version of the upstream source code we are packaging. This has drastically different format if we are doing rollback or if we are doing an packaging an unreleased version from the upstream. The exact syntax will be described later.

<repackage_suffix> ::= "+dfsgN" | "+dfsg.N" | "+dsN" | "+ds.N" | <repackage_suffix_elxr_specific>

<repackage_suffix_elxr_specific> ::= # The repackage suffix introduced due to the need in eLxr.

<debian_revision> ::= <lineage_debian_revision> <elxr_revision_type> <elxr_revision_suffix>

<lineage_debian_revision> ::= # The revision of work we are basing on. Will be explained in details later.

<elxr_revision_type> ::= "+" | "~"

<elxr_revision_suffix> ::= "elxr" <elxr_release_number> "u" <elxr_upload_count>

<elxr_release_number> ::= # eLxr release number. eLxr Aria is "12", while eLxr Bianca is "26".

<elxr_upload_count> ::= # An integer numbering from 1. This indicates the number of uploads of the same version of the package to an eLxr release.
EBNF term reference quote reference comment
<elxr_upload_count> debian_revision components in non-native packages ending in debNuX also indicate a stable update. Either ~ or + will be used before this string depending on the details of the update. N is the major version number of the Debian stable release to which the package was uploaded, and X is a number, starting at 1, that is increased for each stable upload of this package. Debian Policy Manual - Section 5.6.12.2. Special version conventions n/a

WIP