Package version improvements

.github/workflows/build-kernel-deb.yml

@@ -53,13 +53,13 @@ on:
       debian-version-stub:
         description: 'Advanced: Debian version stub; the selected suite''s mapped suffix and a Daily-style trailing ~ are applied automatically'
         required: false
-        default: '0qli'
+        default: '0qli1'
       localversion:
         description: 'Advanced: LOCALVERSION override (auto-derived from the resolved ref if empty)'
         required: false
         default: ''
       kver-extra:
-        description: 'Advanced: extra package-version suffix (e.g. -ci42)'
+        description: 'Advanced: extra KVER suffix (e.g. -ci42), appended to the kernel release verbatim'
         required: false
         default: ''
       debug-build:
@@ -124,13 +124,13 @@ on:
       debian-revision:
         description: 'Debian revision component of the package version'
         type: string
-        default: '0qli~'
+        default: '0qli1~'
       localversion:
         description: 'Override LOCALVERSION suffix (auto-derived from the resolved ref if empty)'
         type: string
         default: ''
       kver-extra:
-        description: 'Extra suffix appended to the package version'
+        description: 'Extra KVER suffix, appended to the kernel release verbatim'
         type: string
         default: ''
       debusine-parent-workspace:
@@ -273,23 +273,50 @@ jobs:
           echo "KERNEL_SHA=$KERNEL_SHA" >> "$GITHUB_ENV"
           echo "Kernel HEAD SHA: $KERNEL_SHA"
 
-      - name: Derive LOCALVERSION
+          # Committer date of HEAD, normalised to UTC. Committer rather than
+          # author date: an author date can be months old on a backported
+          # patch, which would date the build by when someone first wrote the
+          # code rather than by when this snapshot came to exist.
+          KERNEL_DATE=$(TZ=UTC git -C "$KERNEL_DIR" log -1 --format=%cd --date=format-local:%Y%m%d)
+          [[ "$KERNEL_DATE" =~ ^[0-9]{8}$ ]] || {
+            echo "::error::could not read a YYYYMMDD commit date from $KERNEL_REF (got '$KERNEL_DATE')"
+            exit 1
+          }
+          echo "KERNEL_DATE=$KERNEL_DATE" >> "$GITHUB_ENV"
+          echo "Kernel HEAD commit date (UTC): $KERNEL_DATE"
+
+      - name: Derive version fields
         env:
           LOCALVERSION_INPUT: ${{ inputs.localversion }}
           KERNEL_VARIANT_INPUT: ${{ inputs.kernel-variant || 'qcom-next' }}
         run: |
           set -euo pipefail
           OVERRIDE_LV="$LOCALVERSION_INPUT"
           if [[ -n "$OVERRIDE_LV" ]]; then
+            # An override supplies no snapshot, and the ref it was chosen to
+            # replace cannot be trusted to describe it. The Debian version then
+            # carries no +git<date>; prepare-source.sh warns about the same.
             echo "Using explicit LOCALVERSION override: $OVERRIDE_LV"
             echo "LOCALVERSION=$OVERRIDE_LV" >> "$GITHUB_ENV"
+            echo "SNAPSHOT=" >> "$GITHUB_ENV"
+            echo "GITSHA=" >> "$GITHUB_ENV"
           else
-            LOCALVERSION=$(ci/scripts/derive-localversion.sh \
+            # Emits LOCALVERSION=, SNAPSHOT= and GITSHA= lines, already in
+            # GITHUB_ENV form.
+            #
+            # --date is only consulted for branch-tip builds, where the ref
+            # carries no snapshot of its own. It comes from the commit rather
+            # than the clock, so rebuilding a commit reproduces its version
+            # instead of inventing a higher one, and it lands in the same space
+            # as upstream's tag dates.
+            FIELDS=$(ci/scripts/derive-localversion.sh \
               --variant "$KERNEL_VARIANT_INPUT" \
               --ref "$KERNEL_REF" \
-              --sha "$(echo "$KERNEL_SHA" | cut -c1-12)")
-            echo "LOCALVERSION=$LOCALVERSION" >> "$GITHUB_ENV"
-            echo "Derived LOCALVERSION: $LOCALVERSION"
+              --sha "$KERNEL_SHA" \
+              --date "$KERNEL_DATE")
+            echo "$FIELDS" >> "$GITHUB_ENV"
+            echo "Derived version fields:"
+            echo "$FIELDS"
           fi
 
       - name: Resolve Debian revision
@@ -301,7 +328,7 @@ jobs:
         # non-promoting.
         env:
           DEBIAN_REVISION_INPUT: ${{ inputs.debian-revision }}
-          DEBIAN_VERSION_STUB_INPUT: ${{ inputs.debian-version-stub || '0qli' }}
+          DEBIAN_VERSION_STUB_INPUT: ${{ inputs.debian-version-stub || '0qli1' }}
         run: |
           set -euo pipefail
           INPUT_REVISION="$DEBIAN_REVISION_INPUT"
@@ -401,7 +428,16 @@ jobs:
             --debian-revision "$DEBIAN_REVISION"
           )
 
+          # All three version fields come from derive-localversion.sh, which
+          # composed them from the ref and HEAD together. Nothing here appends
+          # to them: the SHA is already inside LOCALVERSION, and GITSHA carries
+          # it separately for the Debian version, which joins it differently.
           [[ -n "$LOCALVERSION" ]]        && ARGS+=(--localversion "$LOCALVERSION")
+          [[ -n "$SNAPSHOT" ]]            && ARGS+=(--snapshot "$SNAPSHOT")
+          # Full SHA: prepare-source.sh takes the first 12 for the version
+          # strings and records the whole thing in the changelog, alongside the
+          # repository and ref that the version strings do not name.
+          ARGS+=(--git-sha "$KERNEL_SHA" --git-clone "$KERNEL_URL" --git-ref "$KERNEL_REF")
           [[ -n "$KVER_EXTRA_INPUT" ]]    && ARGS+=(--kver-extra "$KVER_EXTRA_INPUT")
           [[ -n "$KERNEL_CONFIG_INPUT" ]] && ARGS+=(--kernel-config "$KERNEL_CONFIG_INPUT")
           # Always passed, unlike the optional inputs above: an empty list is a

README.md

@@ -28,8 +28,9 @@ isolated `kernel_variant + suite` build leg.
 
 Both build the same kernel ref. `derive-localversion.sh` folds the variant name
 into LOCALVERSION, so each produces a distinct kernel release
-(`-qcom-next-<date>` and `-qcom-next-debug-<date>`) and therefore a distinct
-versioned image package that can be installed alongside the other.
+(`+qcom-next-<date>-g<sha>` and `+qcom-next-debug-<date>-g<sha>`) and therefore a
+distinct versioned image package that can be installed alongside the other. See
+[docs/version.md](docs/version.md) for how the version strings are composed.
 
 `ci/build-matrix.json` is the source of truth; this table is a summary.
 
@@ -62,7 +63,7 @@ The final Production matrix is conceptually:
       "binpkg": "linux-image-qcom-next",
       "kernel_config": [],
       "dkms": ["kgsl", "camx", "iris-vpu"],
-      "debian_version_stub": "0qli",
+      "debian_version_stub": "0qli1",
       "debian_version_suffix": "~"
     },
     {
@@ -76,7 +77,7 @@ The final Production matrix is conceptually:
       "binpkg": "linux-image-qcom-next",
       "kernel_config": [],
       "dkms": ["kgsl", "camx", "iris-vpu"],
-      "debian_version_stub": "0qli",
+      "debian_version_stub": "0qli1",
       "debian_version_suffix": "",
       "target_workspace": "qli"
     }
@@ -93,9 +94,9 @@ above:
 
 | Suite | Daily | Release |
 | --- | --- | --- |
-| Trixie | `0qli~bpo13+1~` | `0qli~bpo13+1` |
-| Forky | `0qli~` | `0qli` |
-| Resolute | `0qli~26.04.1~` | (not a configured Release suite) |
+| Trixie | `0qli1~bpo13+1~` | `0qli1~bpo13+1` |
+| Forky | `0qli1~` | `0qli1` |
+| Resolute | `0qli1~26.04.1~` | (not a configured Release suite) |
 
 `~` always sorts below the same prefix without it in Debian version
 ordering, so Daily always sorts below Release for the same suite and stub.
@@ -238,7 +239,7 @@ Supporting scripts keep workflow YAML small and testable:
 | --- | --- |
 | `ci/scripts/resolve-matrix.sh` | Validates and flattens matrix rows. |
 | `ci/scripts/resolve-kernel-ref.sh` | Resolves a matrix-selected dated tag or validates a direct ref. |
-| `ci/scripts/derive-localversion.sh` | Derives `LOCALVERSION` from the variant and resolved kernel ref. |
+| `ci/scripts/derive-localversion.sh` | Derives the version fields from the variant, resolved kernel ref and HEAD, printing `LOCALVERSION=`, `SNAPSHOT=` and `GITSHA=` lines. `SNAPSHOT` is the dated component of the Debian version: the tag's date, or the HEAD commit date for a branch-tip build. Scheme and rationale: [docs/version.md](docs/version.md). |
 | `ci/scripts/derive-debian-revision.sh` | Derives the final suite-specific `debian_revision` from `debian_version_stub`, `suite_suffix_mapping`, and delivery type. |
 
 ## Architecture
@@ -399,6 +400,17 @@ For the current matrix, package generation produces:
 names. Only the Debian version field converts it to `~rcN`, so a release
 candidate correctly sorts before the corresponding final kernel release.
 
+Every build names both its snapshot and the commit it was cut from:
+
+| | Format | Example |
+| --- | --- | --- |
+| Kernel release (`uname -r`) | `<base>+<variant>-<date>[.<respin>]-g<sha>` | `7.2.0-rc7+qcom-next-20260826.1-g011a82096bee` |
+| Debian version | `<base>+git<date>[.<respin>]~g<sha>-<revision>` | `7.2.0~rc7+git20260826.1~g011a82096bee-0qli1~bpo13+1` |
+
+The two strings spell the same fields differently because they are compared by
+different rules — `+` and `~` are both load-bearing, not stylistic. See
+[docs/version.md](docs/version.md) before changing either.
+
 `KVER_EXTRA` is supported for explicit suffixes such as `-ci42` or `-local`.
 The packaging rules verify that the declared versioned image package matches the
 resolved kernel release and fail instead of creating inconsistent metadata.
@@ -439,7 +451,7 @@ The available inputs are:
 | `srcpkg` | `linux-qcom-next` | Advanced source package identity override. |
 | `binpkg` | `linux-image-qcom-next` | Advanced image metapackage identity override. |
 | `kernel-config` | Empty | Advanced extra fragments applied on top of all of `debian/config-available/`, e.g. `intree:arch/arm64/configs/qcom_debug.config`. |
-| `debian-version-stub` | `0qli` | Advanced Debian version stub. The selected suite's mapped suffix and a Daily-style trailing `~` are applied automatically; direct builds always use Daily semantics since they are build-only and non-promoting. |
+| `debian-version-stub` | `0qli1` | Advanced Debian version stub. The selected suite's mapped suffix and a Daily-style trailing `~` are applied automatically; direct builds always use Daily semantics since they are build-only and non-promoting. |
 | `localversion` | Auto-derived | Advanced explicit `LOCALVERSION` override. |
 | `kver-extra` | Empty | Advanced kernel-release suffix. |
 | `debug-build` | `false` | Advanced debug configuration toggle. |

ci/build-matrix.json

@@ -26,7 +26,7 @@
         "iris-vpu",
         "audioreach"
       ],
-      "debian_version_stub": "0qli",
+      "debian_version_stub": "0qli1",
       "debian_version_suffix": "~"
     },
     {
@@ -49,7 +49,7 @@
         "iris-vpu",
         "audioreach"
       ],
-      "debian_version_stub": "0qli",
+      "debian_version_stub": "0qli1",
       "debian_version_suffix": ""
     },
     {
@@ -75,7 +75,7 @@
         "iris-vpu",
         "audioreach"
       ],
-      "debian_version_stub": "0qli",
+      "debian_version_stub": "0qli1",
       "debian_version_suffix": "~"
     },
     {
@@ -101,7 +101,7 @@
         "iris-vpu",
         "audioreach"
       ],
-      "debian_version_stub": "0qli",
+      "debian_version_stub": "0qli1",
       "debian_version_suffix": ""
     }
   ]

ci/scripts/derive-debian-revision.sh

@@ -15,11 +15,13 @@ set -euo pipefail
 # context), so the derivation and its validation live in exactly one place.
 #
 # Usage:
-#   ci/scripts/derive-debian-revision.sh --stub 0qli --suite trixie --delivery-type Daily
-#   ci/scripts/derive-debian-revision.sh --stub 0qli --suite forky --delivery-type Release --matrix-file ci/build-matrix.json
+#   ci/scripts/derive-debian-revision.sh --stub 0qli1 --suite trixie --delivery-type Daily
+#   ci/scripts/derive-debian-revision.sh --stub 0qli1 --suite forky --delivery-type Release --matrix-file ci/build-matrix.json
 #
 # Options:
-#   --stub STUB            Debian version stub. Must be non-empty and must not
+#   --stub STUB            Debian version stub, e.g. 0qli1. Must end in a digit:
+#                            that digit is the packaging revision, bumped for a
+#                            rebuild of an unchanged kernel snapshot. Must not
 #                            end in ~ (the delivery suffix supplies any
 #                            trailing ~). Required.
 #   --suite SUITE          Target suite; must have an entry in
@@ -62,6 +64,15 @@ done
 [[ -n "$SUITE" ]]         || { echo "ERROR: --suite is required" >&2; exit 1; }
 [[ -n "$DELIVERY_TYPE" ]] || { echo "ERROR: --delivery-type is required" >&2; exit 1; }
 [[ "$STUB" != *"~" ]]     || { echo "ERROR: --stub must not end in ~ (got '$STUB')" >&2; exit 1; }
+# The trailing digit is the packaging revision: it is the only field left to
+# bump when the kernel snapshot is unchanged but the packaging is rebuilt.
+# suite_suffix_mapping is a per-suite constant and cannot carry it, and the
+# delivery suffix is the Daily/Release marker, so a stub without a digit leaves
+# a rebuild with nowhere to go.
+[[ "$STUB" =~ [0-9]$ ]]   || {
+    echo "ERROR: --stub must end in a digit, the packaging revision (got '$STUB'; use '${STUB}1')" >&2
+    exit 1
+}
 [[ -f "$MATRIX_FILE" ]]   || { echo "ERROR: Matrix file not found: $MATRIX_FILE" >&2; exit 1; }
 
 jq empty "$MATRIX_FILE" 2>/dev/null \