laily/.pouch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(builder): 版本时间精确到分钟，修复同日重构建的 apt 排序

Browse Source 
同日同分支的测试版本前缀完全相同，只剩 +g<sha> 可区分；Debian 版本比较把
hex 当普通文本，新构建可能小于旧构建，apt upgrade 因此拿不到最新包。

build_date() → build_stamp()，改为 YYYYMMDDHHMM，时间与日期拼成一段数字
才能按数值比较。不能写成 20260918T1722：Debian 里字母排在标点之前，带 T
的版本小于同日旧格式包的 20260918.…，修复当天仍抢不过已上传的旧包。

补回归测试，用 dpkg --compare-versions 锁定同日重建更大、且压过旧格式同日包。
This commit is contained in:
laily
2026-09-19 13:23:52 +08:00
parent b476176f3b
commit eb2d0ce651
4 changed files with 97 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/builder/README.md
+12 -8
View File
@@ -134,25 +134,29 @@ Docker registry/ns/foo:1.4.2
### 测试（其它任何 commit） ### 测试（其它任何 commit）
基线 = 祖先上最近的那颗稳定 tag（没有则为 `0.0.0`）。有基线时测试号把 基线 = 祖先上最近的那颗稳定 tag（没有则为 `0.0.0`）。有基线时测试号把
patch 机械 +1，再加构建日 `YYYYMMDD`、清洗后的分支名、相对距离、短 SHA。 patch 机械 +1，再加构建时间 `YYYYMMDDHHMM`、清洗后的分支名、相对距离、短 SHA。
这是排序键，不是在选定下一正式 SemVer。测试与正式进**同一个** apt / 这是排序键，不是在选定下一正式 SemVer。测试与正式进**同一个** apt /
Docker 仓库，所以 DEB 必须用 `~` 挂在下一 patch 上：`1.4.2` < Docker 仓库，所以 DEB 必须用 `~` 挂在下一 patch 上：`1.4.2` <
`1.4.3~20260908…` < `1.4.3`。已装上一正式版的机器可以升到 bugfix 测试包； `1.4.3~202609181430…` < `1.4.3`。已装上一正式版的机器可以升到 bugfix 测试包；
同号正式版仍盖住测试。 同号正式版仍盖住测试。
分支 `feat/login-v2`，相对 `v1.4.2` 第 7 个 commit，SHA `abc1234`， 分支 `feat/login-v2`，相对 `v1.4.2` 第 7 个 commit，SHA `abc1234`，
构建日 `20260908`： 构建时间 `202609181430`（带分钟，同一天重建才排得对）：
```text ```text
规范 / DEB 1.4.3~20260908.feat-login-v2.7+gabc1234 规范 / DEB 1.4.3~202609181430.feat-login-v2.7+gabc1234
文件名 foo_1.4.3~20260908.feat-login-v2.7+gabc1234_amd64.deb 文件名 foo_1.4.3~202609181430.feat-login-v2.7+gabc1234_amd64.deb
Docker registry/ns/foo:1.4.3-20260908.feat-login-v2.7.gabc1234 Docker registry/ns/foo:1.4.3-202609181430.feat-login-v2.7.gabc1234
``` ```
Docker tag 由规范版本映射：`~` → `-`，`+g` → `.g`（Docker 不允许 `~`）。 Docker tag 由规范版本映射：`~` → `-`，`+g` → `.g`（Docker 不允许 `~`）。
无参 `apt upgrade` 会从上一正式版升到下一 patch 的测试包，但不会盖住同号 无参 `apt upgrade` 会从上一正式版升到下一 patch 的测试包，但不会盖住同号
正式包。生产若不能自动吃到测试包，应拆仓库/组件。构建日取本机当前日期； 正式包。生产若不能自动吃到测试包，应拆仓库/组件。构建时间取本机当前本地
设了 `SOURCE_DATE_EPOCH` 则用该时刻的 UTC 日期。 时间（含分钟）；设了 `SOURCE_DATE_EPOCH` 则用该时刻的 UTC 时间。时间和日
期之间不写分隔符：Debian 把字母排在标点之前，`20260918T1430` 会小于同日旧
格式包的 `20260918.…`，同一天的包反而抢不到最新。`+g<sha>` 只用于记录
commit、不参与排序：只写到日期时，同一天重复构建的版本只差 `+g<sha>`，
Debian 版本比较把哈希当普通文本比，会把新包判成比旧包小。
### 分支名清洗 ### 分支名清洗
skills/builder/references/contract.md
+7 -2
View File
@@ -102,8 +102,13 @@ bugfix 测试包；同号正式版仍盖住测试。不要写成 `1.4.2~…`（
`1.4.3`）。日期必须写在 `~` 之后。Docker tag 不得含 `~`、`/`、`:`，由规范 `1.4.3`）。日期必须写在 `~` 之后。Docker tag 不得含 `~`、`/`、`:`，由规范
版本把 `~` → `-`、`+g` → `.g`。 版本把 `~` → `-`、`+g` → `.g`。
`<date>`：构建日 `YYYYMMDD`。已设 `SOURCE_DATE_EPOCH` 时用该时刻的 UTC `<date>`：`YYYYMMDDHHMM`，构建的日期加分钟，中间不加分隔符。加分钟是
日期，否则用本机当前日期。正式 `X.Y.Z` 不加日期。 为了同一天重复构建也能排序：只写到日期时，同分支同日的版本前缀完全相
同，只剩 `+g<sha>` 可区分，而 Debian 把哈希当普通文本比较，新构建可能
排到旧构建下面（`apt upgrade` 因此看不到最新包）。不能写成
`YYYYMMDDTHHMM`：Debian 版本比较里字母排在标点之前，带 `T` 的版本会小于
同日旧格式包的 `YYYYMMDD.…`。已设 `SOURCE_DATE_EPOCH` 时用该时刻的 UTC
时间，否则用本机当前时间。正式 `X.Y.Z` 不加日期。
`<branch>`：`git rev-parse --abbrev-ref HEAD`，detached 时用 `<branch>`：`git rev-parse --abbrev-ref HEAD`，detached 时用
`BUILD_BRANCH` / `CI_COMMIT_BRANCH` / `GITHUB_REF_NAME`，再没有则 `BUILD_BRANCH` / `CI_COMMIT_BRANCH` / `GITHUB_REF_NAME`，再没有则
`detached`。清洗：小写；`/`、`_` → `-`；去掉非 `[a-z0-9-]`；压缩连续 `detached`。清洗：小写；`/`、`_` → `-`；去掉非 `[a-z0-9-]`；压缩连续
skills/builder/scripts/version.sh
+25 -13
View File
@@ -11,11 +11,19 @@ With --docker, print the Docker tag rendering of that version.
Derivation (builder contract «版本号»): Derivation (builder contract «版本号»):
official HEAD exact-match of vX.Y.Z → X.Y.Z official HEAD exact-match of vX.Y.Z → X.Y.Z
test nearest ancestor stable tag vX.Y.Z → X.Y.(Z+1)~YYYYMMDD.branch.n+gSHA test nearest ancestor stable tag vX.Y.Z → X.Y.(Z+1)~YYYYMMDDHHMM.branch.n+gSHA
no tag no stable tag reachable from HEAD → 0.0.0~YYYYMMDD.branch+gSHA no tag no stable tag reachable from HEAD → 0.0.0~YYYYMMDDHHMM.branch+gSHA
YYYYMMDD is the build date. SOURCE_DATE_EPOCH, if set, is that instant in YYYYMMDDHHMM is the build minute (day plus time of day), with no separator:
UTC; otherwise the local calendar date. Official X.Y.Z never gets a date. the digits must stay in one run so Debian compares them numerically. A letter
separator (YYYYMMDDTHHMM) would compare *below* the bare date, because Debian
orders letters before punctuation — same-day packages built with the old
date-only scheme would outrank the new ones. SOURCE_DATE_EPOCH, if set, is
that instant in UTC; otherwise the local date and time. Official X.Y.Z never
gets a date. Minute precision is required for apt: Debian version comparison
ignores upload order, so same-day rebuilds that differ only in +gSHA compare
as arbitrary text (a newer build can sort below an older one). With the minute
in the version, later builds always compare greater.
Stable tags match v<major>.<minor>.<patch> only. Baseline is ancestry, not Stable tags match v<major>.<minor>.<patch> only. Baseline is ancestry, not
the highest version in the repository. This script does not fetch tags. the highest version in the repository. This script does not fetch tags.
@@ -112,13 +120,17 @@ short_sha() {
gitc rev-parse HEAD | cut -c1-7 gitc rev-parse HEAD | cut -c1-7
} }
# Build-day YYYYMMDD. SOURCE_DATE_EPOCH (UTC) wins when set, for reproducible # Build-minute YYYYMMDDHHMM. SOURCE_DATE_EPOCH (UTC) wins when set, for
# test packages; otherwise the machine's current local date. # reproducible test packages; otherwise the machine's current local time.
build_date() { # The minute is not decoration: it is what keeps same-day rebuilds ordered in
# Debian version comparison (0.0.0~202609181036… < 0.0.0~202609181722…). It is
# glued to the date with no 'T' so the whole stamp stays one numeric run;
# '20260918T1722' would sort below '20260918.dev-…' and lose to old packages.
build_stamp() {
if [[ -n "${SOURCE_DATE_EPOCH:-}" ]]; then if [[ -n "${SOURCE_DATE_EPOCH:-}" ]]; then
date -u -d "@${SOURCE_DATE_EPOCH}" +%Y%m%d date -u -d "@${SOURCE_DATE_EPOCH}" +%Y%m%d%H%M
else else
date +%Y%m%d date +%Y%m%d%H%M
fi fi
} }
@@ -157,7 +169,7 @@ nearest_stable_tag() {
} }
derive_canonical() { derive_canonical() {
local tag base n sha branch ymd local tag base n sha branch stamp
tag=$(official_tag_at_head) tag=$(official_tag_at_head)
if [[ -n "$tag" ]]; then if [[ -n "$tag" ]]; then
printf '%s' "${tag#v}" printf '%s' "${tag#v}"
@@ -165,14 +177,14 @@ derive_canonical() {
fi fi
sha=$(short_sha) sha=$(short_sha)
branch=$(branch_slug) branch=$(branch_slug)
ymd=$(build_date) stamp=$(build_stamp)
base=$(nearest_stable_tag) base=$(nearest_stable_tag)
if [[ -z "$base" ]]; then if [[ -z "$base" ]]; then
printf '0.0.0~%s.%s+g%s' "$ymd" "$branch" "$sha" printf '0.0.0~%s.%s+g%s' "$stamp" "$branch" "$sha"
return return
fi fi
n=$(gitc rev-list --count "${base}..HEAD") n=$(gitc rev-list --count "${base}..HEAD")
printf '%s~%s.%s.%s+g%s' "$(bump_patch "$base")" "$ymd" "$branch" "$n" "$sha" printf '%s~%s.%s.%s+g%s' "$(bump_patch "$base")" "$stamp" "$branch" "$n" "$sha"
} }
to_docker() { to_docker() {
tests/test_builder_version.py
+53 -10
View File
@@ -1,6 +1,7 @@
from __future__ import annotations from __future__ import annotations
import os import os
import shutil
import stat import stat
import subprocess import subprocess
import tempfile import tempfile
@@ -14,9 +15,9 @@ VERSION_SH = SCRIPTS / "version.sh"
PUBLISH_DOCKER = SCRIPTS / "publish_docker.sh" PUBLISH_DOCKER = SCRIPTS / "publish_docker.sh"
VERSION_MK = SCRIPTS / "version.mk" VERSION_MK = SCRIPTS / "version.mk"
# Frozen build date so test versions are deterministic. # Frozen build instant so test versions are deterministic.
SOURCE_DATE_EPOCH = "1704067200" # 2024-01-01T00:00:00Z SOURCE_DATE_EPOCH = "1704067200" # 2024-01-01T00:00:00Z
BUILD_DATE = "20240101" BUILD_STAMP = "202401010000"
def git(cwd: Path, *args: str, env: dict[str, str] | None = None) -> str: def git(cwd: Path, *args: str, env: dict[str, str] | None = None) -> str:
@@ -106,12 +107,12 @@ class BuilderVersionTests(unittest.TestCase):
self.assertEqual(result.returncode, 0, result.stderr) self.assertEqual(result.returncode, 0, result.stderr)
self.assertEqual( self.assertEqual(
result.stdout.strip(), result.stdout.strip(),
f"1.2.1~{BUILD_DATE}.main.1+g{sha}", f"1.2.1~{BUILD_STAMP}.main.1+g{sha}",
) )
docker = version_sh("--docker", cwd=repo) docker = version_sh("--docker", cwd=repo)
self.assertEqual( self.assertEqual(
docker.stdout.strip(), docker.stdout.strip(),
f"1.2.1-{BUILD_DATE}.main.1.g{sha}", f"1.2.1-{BUILD_STAMP}.main.1.g{sha}",
) )
def test_test_version_uses_ancestor_not_global_max(self) -> None: def test_test_version_uses_ancestor_not_global_max(self) -> None:
@@ -141,12 +142,12 @@ class BuilderVersionTests(unittest.TestCase):
self.assertEqual(result.returncode, 0, result.stderr) self.assertEqual(result.returncode, 0, result.stderr)
self.assertEqual( self.assertEqual(
result.stdout.strip(), result.stdout.strip(),
f"1.4.3~{BUILD_DATE}.feat-login-v2.2+g{feature_sha}", f"1.4.3~{BUILD_STAMP}.feat-login-v2.2+g{feature_sha}",
) )
docker = version_sh("--docker", cwd=repo) docker = version_sh("--docker", cwd=repo)
self.assertEqual( self.assertEqual(
docker.stdout.strip(), docker.stdout.strip(),
f"1.4.3-{BUILD_DATE}.feat-login-v2.2.g{feature_sha}", f"1.4.3-{BUILD_STAMP}.feat-login-v2.2.g{feature_sha}",
) )
def test_ignores_prerelease_and_app_tags(self) -> None: def test_ignores_prerelease_and_app_tags(self) -> None:
@@ -164,7 +165,7 @@ class BuilderVersionTests(unittest.TestCase):
sha = sha7(repo) sha = sha7(repo)
result = version_sh(cwd=repo) result = version_sh(cwd=repo)
self.assertEqual(result.returncode, 0, result.stderr) self.assertEqual(result.returncode, 0, result.stderr)
self.assertEqual(result.stdout.strip(), f"1.0.1~{BUILD_DATE}.main.1+g{sha}") self.assertEqual(result.stdout.strip(), f"1.0.1~{BUILD_STAMP}.main.1+g{sha}")
def test_no_stable_tag(self) -> None: def test_no_stable_tag(self) -> None:
with tempfile.TemporaryDirectory() as temp: with tempfile.TemporaryDirectory() as temp:
@@ -176,7 +177,49 @@ class BuilderVersionTests(unittest.TestCase):
sha = sha7(repo) sha = sha7(repo)
result = version_sh(cwd=repo) result = version_sh(cwd=repo)
self.assertEqual(result.returncode, 0, result.stderr) self.assertEqual(result.returncode, 0, result.stderr)
self.assertEqual(result.stdout.strip(), f"0.0.0~{BUILD_DATE}.main+g{sha}") self.assertEqual(result.stdout.strip(), f"0.0.0~{BUILD_STAMP}.main+g{sha}")
def test_same_day_rebuild_sorts_higher(self) -> None:
"""同一天重建必须比上一包大，否则 apt 永远拿不到最新构建。
只写到日期时同分支同日的版本前缀完全相同，只剩 +g<sha> 可区分，
Debian 版本比较把哈希当普通文本，新包可能被判成比旧包小。带分钟的
时间必须与日期拼在同一段数字里：字母排在标点之前，YYYYMMDDTHHMM
这种带字母分隔的写法会小于同日旧格式包的 YYYYMMDD.…。
"""
if shutil.which("dpkg") is None:
self.skipTest("dpkg not available")
with tempfile.TemporaryDirectory() as temp:
repo = Path(temp) / "repo"
repo.mkdir()
init_repo(repo)
(repo / "a").write_text("1\n", encoding="utf-8")
commit(repo, "init")
early = version_sh(cwd=repo, env={"SOURCE_DATE_EPOCH": "1704067200"}) # 00:00Z
later = version_sh(cwd=repo, env={"SOURCE_DATE_EPOCH": "1704103200"}) # 10:00Z
self.assertEqual(early.returncode, 0, early.stderr)
self.assertEqual(later.returncode, 0, later.stderr)
first, second = early.stdout.strip(), later.stdout.strip()
self.assertEqual(first.rsplit(".", 1)[0].split("~")[1].split(".")[0], "202401010000")
self.assertEqual(second.rsplit(".", 1)[0].split("~")[1].split(".")[0], "202401011000")
self.assertEqual(
second,
f"0.0.0~202401011000.main+g{sha7(repo)}",
"时间必须与日期拼成一段数字，不能插入字母分隔符",
)
for label, a, b in (
("同日重建", second, first),
("已上传的旧格式同日包", second, "0.0.0~20240101.main+gaaaaaaa"),
("次日新格式包", "0.0.0~202401021000.main+gccccccc", second),
("下一正式版", "0.1.0", second),
):
compared = subprocess.run(
["dpkg", "--compare-versions", a, "gt", b],
text=True,
capture_output=True,
check=False,
)
self.assertEqual(compared.returncode, 0, f"{label}：{a} 应大于 {b}")
def test_detached_uses_env_branch(self) -> None: def test_detached_uses_env_branch(self) -> None:
with tempfile.TemporaryDirectory() as temp: with tempfile.TemporaryDirectory() as temp:
@@ -192,7 +235,7 @@ class BuilderVersionTests(unittest.TestCase):
git(repo, "checkout", "--detach", "HEAD") git(repo, "checkout", "--detach", "HEAD")
result = version_sh(cwd=repo, env={"BUILD_BRANCH": "ci_job"}) result = version_sh(cwd=repo, env={"BUILD_BRANCH": "ci_job"})
self.assertEqual(result.returncode, 0, result.stderr) self.assertEqual(result.returncode, 0, result.stderr)
self.assertEqual(result.stdout.strip(), f"0.1.1~{BUILD_DATE}.ci-job.1+g{sha}") self.assertEqual(result.stdout.strip(), f"0.1.1~{BUILD_STAMP}.ci-job.1+g{sha}")
def test_source_date_epoch_changes_test_date(self) -> None: def test_source_date_epoch_changes_test_date(self) -> None:
with tempfile.TemporaryDirectory() as temp: with tempfile.TemporaryDirectory() as temp:
@@ -207,7 +250,7 @@ class BuilderVersionTests(unittest.TestCase):
sha = sha7(repo) sha = sha7(repo)
later = version_sh(cwd=repo, env={"SOURCE_DATE_EPOCH": "1725148800"}) later = version_sh(cwd=repo, env={"SOURCE_DATE_EPOCH": "1725148800"})
self.assertEqual(later.returncode, 0, later.stderr) self.assertEqual(later.returncode, 0, later.stderr)
self.assertEqual(later.stdout.strip(), f"1.0.1~20240901.main.1+g{sha}") self.assertEqual(later.stdout.strip(), f"1.0.1~202409010000.main.1+g{sha}")
def test_official_version_ignores_build_date(self) -> None: def test_official_version_ignores_build_date(self) -> None:
with tempfile.TemporaryDirectory() as temp: with tempfile.TemporaryDirectory() as temp: