feat(version): 构建身份(release_version/build_kind/display_version),无基线也放行
解决"开发构建沿用已发布版本号,分不清开发版与正式版": - 新增 `scripts/version.py --identity`:release_version(无基线即空)/ build_kind / commit_sha(完整 40 位)/ display_version / built_at。显示规则:发布 `X.Y.Z`、 开发 `X.Y.Z-dev+g<短SHA>`、无基线 `dev+g<短SHA>`、什么都拿不到 `dev`。 - `build_kind=release` 只认**显式发布上下文**(`BUILD_KIND=release` / `--release`); 声明发布构建却没有已发布版本 ⇒ 拒绝(rc=2)。普通 main 构建永远是 development, **不许只显示上一正式版本号、不许自称正式版**。 - Go 侧 `internal/version` 加 ReleaseVersion/BuildKind/DisplayVersion()/IsRelease()/Info(), 原 Number/CommitSHA/BuildTime 语义不变(向后兼容);契约测试改成:发布构建必须等于 CHANGELOG 顶部、开发构建必须是 dev 形状;`make verify` 的 contracts 项新增 **负例**「自称正式版 ⇒ 必须红」(只有正例的契约会被静默掏空)。 - 构建接线:Makefile/Dockerfile/ci_checks `--internal-build` 统一走 identity; Makefile 的 `make version` 打印身份 JSON;Dockerfile 新增 RELEASE_VERSION/BUILD_KIND。 - `tests-go` 的"按设计跳过"声明补上 `TestDevBuildDoesNotClaimRelease`(它的强制点在 contracts)。 验证:go test 三态实测(未注入 SKIP、开发身份 PASS、自称正式版 FAIL); --internal-build 产出并打印 dev+g<sha>;--internal-identity 契约项 rc=0; make verify 15/15 success;反向夹具 80/0。
This commit is contained in:
+75
-32
@@ -37,7 +37,7 @@ from typing import Callable
|
||||
ROOT = Path(__file__).resolve().parent.parent
|
||||
WEB = ROOT / "web"
|
||||
REPORT_DEFAULT = ROOT / "ci-report.json"
|
||||
POLICY_REVISION = "ci-checks/2" # 判据变更时改这里,报告里跟着变
|
||||
POLICY_REVISION = "ci-checks/3" # 判据变更时改这里,报告里跟着变
|
||||
MANIFESTS = ["go.mod", "go.sum", "web/package.json", "web/package-lock.json"]
|
||||
|
||||
SUCCESS, FAILURE, SKIPPED, NOT_RUN = "success", "failure", "skipped", "not_run"
|
||||
@@ -249,9 +249,9 @@ def checks() -> list[Check]:
|
||||
[g, "test", "-count=1", "-json", "./..."], env=env, judge=judge_go_tests),
|
||||
Check("tests-web", "前端测试(vitest,必须真跑)",
|
||||
[py3, "scripts/ci_checks.py", "--internal-web-test"], env=env),
|
||||
Check("contracts", "版本与变更记录契约(不许 SKIP 后算过)",
|
||||
Check("contracts", "版本与变更记录契约(不许 SKIP;开发构建不许自称正式版)",
|
||||
[py3, "scripts/ci_checks.py", "--internal-contracts", g], env=env),
|
||||
Check("version", "CHANGELOG 与版本记录(四节齐备 + 正式 tag 与提交内版本一致)",
|
||||
Check("version", "CHANGELOG 与版本记录(四类小节无空栏目 + 正式 tag 与提交内版本一致)",
|
||||
[py3, "scripts/check_changelog.py", "--tags"]),
|
||||
Check("security-secrets", "密钥泄漏扫描(含扫描器自检)",
|
||||
[py3, "scripts/check_secrets.py"]),
|
||||
@@ -287,22 +287,47 @@ def cmd_internal_deps(out_dir: str) -> int:
|
||||
return 0
|
||||
|
||||
|
||||
def build_identity() -> tuple[dict | None, str]:
|
||||
"""构建身份(`scripts/version.py --identity`)。
|
||||
|
||||
⚠️ 刻意**不**跑裸的 `scripts/version.py`:那个在"还没有正式版本"时会非 0 退出,
|
||||
而开发构建**必须**能正常产出身份(release_version=null / display_version=dev+g<短SHA>)。
|
||||
"""
|
||||
p = subprocess.run(py("scripts/version.py", "--identity"), cwd=ROOT, capture_output=True, text=True)
|
||||
if p.returncode:
|
||||
return None, ((p.stderr or p.stdout).strip().splitlines() or [f"退出码 {p.returncode}"])[0][:400]
|
||||
try:
|
||||
return json.loads(p.stdout), ""
|
||||
except ValueError as e:
|
||||
return None, f"--identity 的输出不是 JSON:{e}"
|
||||
|
||||
|
||||
def ldflags_for(ident: dict, *, build_kind: str | None = None,
|
||||
release_version: str | None = None) -> str:
|
||||
"""把构建身份编成 -ldflags(负例可以覆盖 kind / release_version)。"""
|
||||
kind = build_kind or str(ident.get("build_kind") or "development")
|
||||
rel = ident.get("release_version") if release_version is None else release_version
|
||||
return " ".join([
|
||||
f"-X knowledge-governance/internal/version.Number={rel or 'dev'}",
|
||||
f"-X knowledge-governance/internal/version.ReleaseVersion={rel or ''}",
|
||||
f"-X knowledge-governance/internal/version.BuildKind={kind}",
|
||||
f"-X knowledge-governance/internal/version.CommitSHA={ident.get('commit_sha') or 'unknown'}",
|
||||
f"-X knowledge-governance/internal/version.BuildTime={ident.get('built_at') or 'unknown'}",
|
||||
])
|
||||
|
||||
|
||||
def cmd_internal_build(out_dir: str) -> int:
|
||||
out = Path(out_dir)
|
||||
out.mkdir(parents=True, exist_ok=True)
|
||||
version = subprocess.run(py("scripts/version.py"), cwd=ROOT, capture_output=True,
|
||||
text=True).stdout.strip() or "dev"
|
||||
sha = subprocess.run(["git", "rev-parse", "--short=12", "HEAD"], cwd=ROOT,
|
||||
capture_output=True, text=True).stdout.strip() or "unknown"
|
||||
ts = dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
|
||||
ldflags = " ".join([
|
||||
f"-X knowledge-governance/internal/version.Number={version}",
|
||||
f"-X knowledge-governance/internal/version.CommitSHA={sha}",
|
||||
f"-X knowledge-governance/internal/version.BuildTime={ts}",
|
||||
])
|
||||
ident, err = build_identity()
|
||||
if ident is None:
|
||||
print(f"❌ 拿不到构建身份:{err}", file=sys.stderr)
|
||||
return 1
|
||||
ldflags = ldflags_for(ident)
|
||||
p = subprocess.run([go_bin(), "build", "-trimpath", "-ldflags", ldflags, "-o", f"{out}/", "./cmd/..."],
|
||||
cwd=ROOT, env=go_env(), capture_output=True, text=True)
|
||||
print(f"-- go build(版本 {version} / 提交 {sha})--")
|
||||
print(f"-- go build(显示版本 {ident['display_version']}|{ident['build_kind']}|"
|
||||
f"提交 {str(ident['commit_sha'])[:12]})--")
|
||||
print(p.stdout[-2000:] if p.stdout else "", end="")
|
||||
if p.returncode:
|
||||
print(f"❌ 构建失败:{(p.stderr or '')[:2000]}", file=sys.stderr)
|
||||
@@ -327,31 +352,49 @@ def cmd_internal_web_test() -> int:
|
||||
|
||||
|
||||
def cmd_internal_contracts(go: str) -> int:
|
||||
"""版本契约:注入进二进制的号必须等于 CHANGELOG 顶部,而且**必须真的 PASS**。"""
|
||||
"""版本契约:结构 + 注入身份必须**真 PASS**(SKIP 判红),
|
||||
并且**开发构建不许自称正式版**(负例:标成 release ⇒ 必须红)。"""
|
||||
rc = subprocess.run(py("scripts/check_changelog.py"), cwd=ROOT).returncode
|
||||
if rc:
|
||||
return 1
|
||||
v = subprocess.run(py("scripts/version.py"), cwd=ROOT, capture_output=True, text=True)
|
||||
version = v.stdout.strip()
|
||||
if v.returncode or not version:
|
||||
print("❌ CHANGELOG 顶部解析不到版本号:没有条目就没有版本号,不许回落成假版本", file=sys.stderr)
|
||||
ident, err = build_identity()
|
||||
if ident is None:
|
||||
print(f"❌ 拿不到构建身份:{err}", file=sys.stderr)
|
||||
return 1
|
||||
print(f"-- 版本契约:CHANGELOG 顶部 = {version} --")
|
||||
p = subprocess.run([go, "test", f"-ldflags=-X knowledge-governance/internal/version.Number={version}",
|
||||
"-count=1", "-run", "TestNumberMatchesChangelog", "-v", "-json",
|
||||
"./internal/version/..."],
|
||||
cwd=ROOT, env=go_env(), capture_output=True, text=True)
|
||||
text = p.stdout + p.stderr
|
||||
print(text[-3000:], end="")
|
||||
print(f"-- 版本契约:显示版本 {ident['display_version']}({ident['build_kind']}"
|
||||
f"|release_version={ident['release_version']!r})--")
|
||||
tests = ("TestNumberMatchesChangelog", "TestDevBuildDoesNotClaimRelease")
|
||||
|
||||
def run(ld: str) -> tuple[int, str]:
|
||||
p = subprocess.run([go, "test", f"-ldflags={ld}", "-count=1", "-run", "Test", "-v", "-json",
|
||||
"./internal/version/..."], cwd=ROOT, env=go_env(),
|
||||
capture_output=True, text=True)
|
||||
return p.returncode, (p.stdout + p.stderr).replace("\\n", "\n")
|
||||
|
||||
rc1, text = run(ldflags_for(ident))
|
||||
print(text[-2000:], end="")
|
||||
# ⚠️ 被跳过的断言等于没有断言:必须看到 PASS,SKIP 一律判红。
|
||||
# 用 in 而不是 `| grep -q`:pipefail 下 grep -q 会因 SIGPIPE 谎报失败(trap-7)。
|
||||
if '--- PASS: TestNumberMatchesChangelog' not in text.replace("\\n", "\n"):
|
||||
print("❌ 版本契约没有真正 PASS(被 SKIP 或没跑到)—— 缺 -ldflags,或 CHANGELOG 解析失败", file=sys.stderr)
|
||||
for name in tests:
|
||||
if f"--- PASS: {name}" not in text:
|
||||
print(f"❌ 版本契约 {name} 没有真正 PASS(被 SKIP 或没跑到)—— "
|
||||
f"缺 -ldflags,或 CHANGELOG / 构建身份有问题", file=sys.stderr)
|
||||
return 1
|
||||
if f"--- SKIP: {name}" in text:
|
||||
print(f"❌ 版本契约 {name} 被跳过(构建身份没注入)—— 跳过不算通过", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
# 负例:把开发构建标成正式版(ReleaseVersion 指向 CHANGELOG 里没有的号)⇒ **必须红**。
|
||||
# 没有这条,"开发版沿用正式版号"这个病会静默回归。
|
||||
bogus = "9.9.9" if ident.get("release_version") != "9.9.9" else "8.8.8"
|
||||
rc2, _ = run(ldflags_for(ident, build_kind="release", release_version=bogus))
|
||||
if rc2 == 0:
|
||||
print(f"❌ 把构建标成正式版(BuildKind=release / ReleaseVersion={bogus})竟然还是绿的 —— "
|
||||
f"这条断言是死的", file=sys.stderr)
|
||||
return 1
|
||||
if "--- SKIP: TestNumberMatchesChangelog" in text:
|
||||
print("❌ 版本契约被跳过(未注入版本号)—— 跳过不算通过", file=sys.stderr)
|
||||
return 1
|
||||
print("✅ 版本契约成立:注入 == CHANGELOG 顶部,且断言真的执行了")
|
||||
print(f"-- 负例确认:自称正式版({bogus})⇒ 红 ✓ --")
|
||||
print("✅ 版本契约成立:注入 == CHANGELOG 顶部(没有正式版本时为空),"
|
||||
"开发构建带 dev 标识,且断言真的执行了")
|
||||
return 0
|
||||
|
||||
|
||||
|
||||
@@ -43,6 +43,11 @@
|
||||
"package": "knowledge-governance/internal/version",
|
||||
"test": "TestNumberMatchesChangelog",
|
||||
"reason": "未注入版本号时按设计 SKIP(本地跑全量测试不该被迫先构建);**它的强制点在 contracts 项**:那里带 -ldflags 跑它并断言真的 PASS、且出现 SKIP 就判红"
|
||||
},
|
||||
{
|
||||
"package": "knowledge-governance/internal/version",
|
||||
"test": "TestDevBuildDoesNotClaimRelease",
|
||||
"reason": "构建身份未注入时按设计 SKIP(本地跑全量测试不该被迫先构建);**它的强制点在 contracts 项**:那里带 -ldflags 跑它并断言真的 PASS、且出现 SKIP 就判红"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
+71
-10
@@ -1,22 +1,35 @@
|
||||
#!/usr/bin/env python3
|
||||
"""打印版本号 —— 唯一来源是仓库根的 CHANGELOG.md。
|
||||
"""版本与构建身份 —— 版本号的唯一来源是仓库根的 CHANGELOG.md。
|
||||
|
||||
为什么是它而不是 git tag:CI 检出是 `git fetch --depth 50`,**取不到 tag**,
|
||||
`git describe --tags` 会失败或者给出误导性的结果。仓库里的文件则一定在。
|
||||
为什么是它而不是 git tag:**日常检出不做 `git describe`**(CI 检出是 `git fetch --depth 50`,
|
||||
`git describe --tags` 会失败或给出误导结果)。正式 tag 的**创建**是人工批准的发布动作,
|
||||
CI 只做**核验**(tag 版本 == 它指到那个提交里的版本记录),见 `check_changelog.py --tags`。
|
||||
仓库里的文件则一定在。
|
||||
|
||||
为什么不是另放一个 `VERSION` 文件:那是第二份副本,发版要改两处,忘一处就漂移
|
||||
(正本 §3.1)。CHANGELOG.md 里本来就必须写版本号,让它当源头,副本数为一。
|
||||
为什么不是另放一个 `VERSION` 文件:那是第二份副本,发版要改两处,忘一处就漂移。
|
||||
|
||||
用法:
|
||||
python3 scripts/version.py # 打印版本号;解析不到就以非 0 退出
|
||||
python3 scripts/version.py --check # 同时跑结构自检(等价 check-changelog.py)
|
||||
python3 scripts/version.py # 打印顶部「已发布」版本号;没有就非 0 退出
|
||||
python3 scripts/version.py --identity # 打印构建身份 JSON(**开发构建也能用**)
|
||||
python3 scripts/version.py --identity --release # 声明发布构建;没有已发布版本 ⇒ 拒绝(rc=2)
|
||||
python3 scripts/version.py --check # 打印版本号并跑结构自检(等价 check-changelog.py)
|
||||
|
||||
退出码非 0 表示"CHANGELOG 里没有已发布版本条目" —— 构建应当据此失败,
|
||||
而不是回落成一个看起来正常的假版本号。
|
||||
构建身份字段(`--identity`):
|
||||
release_version 正式版本基线;本仓还没有正式发布过 ⇒ `null`
|
||||
build_kind development | release(**只有显式声明**才是 release,普通 main CI 永远不是)
|
||||
commit_sha 完整 40 位提交 SHA(取不到 ⇒ `unknown`)
|
||||
display_version 用户可见标识:`X.Y.Z` / `X.Y.Z-dev+g<短SHA>` / `dev+g<短SHA>` / `dev`
|
||||
built_at 构建时间(`BUILT_AT` 环境变量,缺省取当前 UTC)
|
||||
|
||||
⚠️ 开发构建**不能**只显示上一正式版本号(那正是要修的问题),也不许自称正式版。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import datetime as dt
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
@@ -25,6 +38,8 @@ CHANGELOG = ROOT / "CHANGELOG.md"
|
||||
|
||||
# 已发布版本标题:`## [0.1.0] - 2026-10-10` / `## [0.1.0]`;`## [Unreleased]` 不算
|
||||
RELEASE_HEADING = re.compile(r"^##\s*\[(\d+\.\d+\.\d+)\]", re.MULTILINE)
|
||||
SEMVER = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$")
|
||||
FULL_SHA = re.compile(r"^[0-9a-f]{40}$")
|
||||
|
||||
|
||||
def current_version(path: Path = CHANGELOG) -> str | None:
|
||||
@@ -35,12 +50,58 @@ def current_version(path: Path = CHANGELOG) -> str | None:
|
||||
return m.group(1) if m else None
|
||||
|
||||
|
||||
def git_sha(root: Path = ROOT) -> str:
|
||||
p = subprocess.run(["git", "rev-parse", "HEAD"], cwd=root, capture_output=True, text=True)
|
||||
s = p.stdout.strip()
|
||||
return s if FULL_SHA.match(s) else "unknown"
|
||||
|
||||
|
||||
def display_version(release_version: str | None, kind: str, sha: str) -> str:
|
||||
short = sha[:12] if FULL_SHA.match(sha) else ""
|
||||
if kind == "release" and release_version:
|
||||
return release_version
|
||||
if release_version and short:
|
||||
return f"{release_version}-dev+g{short}"
|
||||
if release_version:
|
||||
return f"{release_version}-dev"
|
||||
return f"dev+g{short}" if short else "dev"
|
||||
|
||||
|
||||
def identity(*, release: bool = False, built_at: str | None = None,
|
||||
root: Path = ROOT, sha: str | None = None) -> dict:
|
||||
"""构建身份。`release=True` 但没有已发布版本 ⇒ 由调用方拒绝(见 main)。"""
|
||||
rel = current_version(root / "CHANGELOG.md")
|
||||
sha = sha if sha is not None else git_sha(root)
|
||||
kind = "release" if (release and rel) else "development"
|
||||
return {
|
||||
"release_version": rel,
|
||||
"build_kind": kind,
|
||||
"commit_sha": sha,
|
||||
"display_version": display_version(rel, kind, sha),
|
||||
"built_at": built_at or os.environ.get("BUILT_AT") or os.environ.get("BUILD_TIME")
|
||||
or dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
|
||||
}
|
||||
|
||||
|
||||
def main(argv: list[str]) -> int:
|
||||
release = "--release" in argv or os.environ.get("BUILD_KIND") == "release"
|
||||
if "--identity" in argv:
|
||||
if release and current_version() is None:
|
||||
print("❌ 声明了发布构建(--release / BUILD_KIND=release),但 CHANGELOG.md 里没有已发布版本条目。\n"
|
||||
" 发布构建必须基于一个已发布的版本记录(`## [x.y.z] - YYYY-MM-DD`)——\n"
|
||||
" 本仓还没有正式发布过,所以现在只能产出开发构建身份(dev+g<短SHA>)。",
|
||||
file=sys.stderr)
|
||||
return 2
|
||||
print(json.dumps(identity(release=release), ensure_ascii=False, indent=2))
|
||||
return 0
|
||||
|
||||
v = current_version()
|
||||
if v is None:
|
||||
print(
|
||||
"❌ CHANGELOG.md 里找不到已发布版本条目(形如 `## [0.1.0] - 2026-10-10`)。\n"
|
||||
" 版本号解析不到 ⇒ 构建应当失败,而不是回落成假版本号。",
|
||||
" 本仓还没有正式发布过 ⇒ 没有正式版本号可用。\n"
|
||||
" 要构建身份(开发构建也能用)请跑 `python3 scripts/version.py --identity`;\n"
|
||||
" 发布构建必须先在 CHANGELOG.md 写下正式版本条目。",
|
||||
file=sys.stderr,
|
||||
)
|
||||
return 1
|
||||
|
||||
Reference in New Issue
Block a user