fix(version): 正式构建核证据 + 预检分"建议/就绪" + CI 就绪按必需 context

按要求补三项(本轮不推、不打真实 tag、不部署;全部用临时仓库与假对象验):

1) 正式构建身份不能只认 --release:
   - 新增 release_evidence():核①完整 40 位 SHA ②**指向该提交的注释 tag** v<版本号>
     ③该提交里 CHANGELOG 顶部版本一致。缺任一条 ⇒ rc=2,身份退回 development 并把
     release_blocked 的原因写进 JSON(给机器读,也给人看)。
   - version.py --self-test:六条负例(有版本无 tag / unknown SHA / 短 SHA / tag 指错提交 /
     轻量 tag / 版本不一致)+ 证据齐正例,**tag 全部在 mktemp 临时仓库里创建**。
   - Go 侧新增 TestReleaseBuildRequiresEvidence:release 构建必须 CommitSHA 完整且
     v<ReleaseVersion> 是**注释 tag** 并指向该提交(独立于 Python 的二次复核)。

2) 发布预检区分"准备建议"与"发布就绪":
   - 新增纯函数 readiness(facts) → (是否就绪, 阻塞项, 建议);输出分两段。
   - **就绪要求候选版本已写进目标提交**(version_in_commit:查 git show <sha>:CHANGELOG.md,
     工作区写了没提交不算);首发按**显式指定版本**处理,**不把"记录里有这个版本"当已发布**
     (已发布的证据是 tag,不是记录条目)。
   - 预检**不执行、也不在输出里推荐自动发布路径**(正式发版由人按 docs/RELEASE_RUNBOOK.md)。

3) CI 就绪判据:必需 context 集合来自 .gitea/required-contexts.txt(缺失/为空 ⇒ 没有策略 ⇒
   阻断,不用观察到的状态顶替);**全部 success 才通过**,失败/缺项/pending/查询异常一律阻断。
   Release 查询加 release_state():**只有 HTTP 404 才算不存在**,403/5xx/超时算查询异常 ⇒ 阻断。

验证:version.py --self-test 绿;release_preflight --self-test 绿(就绪判定 19 个分支 +
临时仓库验证 git show 语义 + 五个 HTTP 码语义);go test 三态(未注入 SKIP / 开发 PASS /
自称正式 RED);反向夹具 83/0(含临时仓库 go test 六例、预检"记录未进提交"两态);
make verify 15/15 success。
This commit is contained in:
姚章浩
2026-10-13 15:26:49 +08:00
parent 05144309c3
commit 7a9d51cc70
6 changed files with 615 additions and 60 deletions
+21 -5
View File
@@ -11,9 +11,23 @@
2. **写记录**:把这次要发的东西从 `[Unreleased]` 提到一个正式版本条目
`## [x.y.z] - YYYY-MM-DD`(四类小节,无空栏目;破坏性变化写在 `### Changed` 里并链接本文)。
版本号**只增不减**(回退走部署层,不改这个文件);每个项目只有本文件这一个版本来源。
3. **跑预检(只读)**:`python3 scripts/release_preflight.py`
—— 它只列事实(候选版本 / 完整 SHA / 该提交的 CI 证据 / `[Unreleased]` 原文 / 远端同名 tag 与
Release 是否已存在 / 遗留风险),有阻塞项就**不给**"可以发"的结论。
3. **跑预检(只读)**:`python3 scripts/release_preflight.py --version X.Y.Z`
—— 输出**两段**:`准备建议`(还差什么)与 `发布就绪判定`(是否就绪)。
⚠️ 预检**不执行、也不推荐自动发布路径**;正式发版动作由人按本文执行。
**就绪 = 证据齐(缺一条都不算)**:
| 判据 | 说明 |
|---|---|
| 候选版本**已写进目标提交** | 查 `git show <sha>:CHANGELOG.md`;只在工作区写了、没提交 ⇒ 不就绪 |
| 完整 40 位 SHA 指向准确提交 | 目标提交 == HEAD,或 `--sha` 逐字符一致 |
| 记录检查通过 | 结构与 tag 一致性(真查远端) |
| **必需 context 集合全部 success** | 集合来自 `.gitea/required-contexts.txt`;缺失/为空 ⇒ 没有策略 ⇒ 阻断;失败 / 缺项 / pending / 查询异常一律阻断 |
| 远端 tag 已核对且未被占用 | 查不到远端 ⇒ 阻断 |
| Release 不存在 | **只有 HTTP 404 才算「不存在」**;403/5xx/超时 ⇒ 查询异常 ⇒ 阻断 |
| 首发版本号 | 还没有已发布版本 ⇒ 必须**显式指定**;**不把「记录里有这个版本」当作已发布** |
自查(不依赖网络、不打真 tag):`python3 scripts/release_preflight.py --self-test`、
`python3 scripts/version.py --self-test`。
4. **批准后执行**:`python3 scripts/release_preflight.py --execute --version X.Y.Z
--approve-version X.Y.Z --approve-sha <完整SHA>`(两个批准参数必须逐字符等于预检结果)。
它创建**注释 tag** `vX.Y.Z`(指向验收过的那个提交)并建关联 Release,正文取自 `CHANGELOG.md`。
@@ -34,8 +48,10 @@ python3 scripts/version.py --identity # JSON:release_version / build_kind
| 普通开发构建(**还没有正式版本**) | `development` | `null` | `dev+g<短SHA>` |
| 发布构建(显式给出发布上下文) | `release` | 顶部已发布版本 | `X.Y.Z`(另带完整 SHA) |
- `build_kind=release` **只能**来自显式的发布上下文(`BUILD_KIND=release`);普通 `main` CI 永远是
`development`,**不得**因为"CHANGELOG 顶部有版本号"就自称正式版。
- `build_kind=release` **只能**来自显式的发布上下文(`BUILD_KIND=release`),并且**要核证据**:
完整 40 位 SHA + **指向该提交的注释 tag** `v<版本号>` + 该提交里 CHANGELOG 顶部版本一致;
缺任何一条 ⇒ **拒绝标为正式版**(`--identity --release` 以 rc=2 退出、身份退回 `development`
并列出缺什么)。普通 `main` CI 永远是 `development`,**不得**因为"CHANGELOG 顶部有版本号"就自称正式版。
- 二进制里的注入字段(`internal/version`)与上表一一对应;契约测试断言:
注入 == CHANGELOG 顶部(发布构建)、开发构建必须是 `dev` 形状(**不许声称正式版**),且**跳过不算通过**。
+35
View File
@@ -2,6 +2,7 @@ package version
import (
"os"
"os/exec"
"path/filepath"
"regexp"
"strings"
@@ -98,3 +99,37 @@ func TestDevBuildDoesNotClaimRelease(t *testing.T) {
}
}
}
// 正式构建必须**有证据**:完整提交 SHA + 一个指向该提交的**注释 tag** `v<ReleaseVersion>`。
// 光有"CHANGELOG 顶部有版本号"不算 —— 那会把每个开发构建都说成正式版。
func TestReleaseBuildRequiresEvidence(t *testing.T) {
if !HasInjection() {
t.Skip("构建身份未注入(没有 -ldflags);CI 会带 -ldflags 跑它,并断言它没有 Skip")
}
if BuildKind != "release" {
return // 开发构建由 TestDevBuildDoesNotClaimRelease 管
}
if !fullSHA.MatchString(CommitSHA) {
t.Fatalf("标成了正式构建,但 CommitSHA=%q 不是完整 40 位 —— 没有准确提交就谈不上正式版", CommitSHA)
}
name := "v" + ReleaseVersion
out, err := exec.Command("git", "tag", "--points-at", CommitSHA).Output()
if err != nil {
t.Fatalf("跑 `git tag --points-at %s` 失败:%v(正式构建必须能核到 tag 证据)", CommitSHA[:12], err)
}
tags := strings.Fields(string(out))
found := false
for _, x := range tags {
if x == name {
found = true
}
}
if !found {
t.Fatalf("标成了正式构建(%s),但提交 %s 上没有 tag %s(现有指向该提交的 tag:%v)—— "+
"正式构建必须有指向该提交的合规 tag", ReleaseVersion, CommitSHA[:12], name, tags)
}
kind, err := exec.Command("git", "cat-file", "-t", "refs/tags/"+name).Output()
if err != nil || strings.TrimSpace(string(kind)) != "tag" {
t.Fatalf("tag %s 不是**注释 tag**(`git tag -a`)—— 轻量 tag 不算发布证据", name)
}
}
+129 -1
View File
@@ -107,11 +107,80 @@ PY
pycheck "没有已发布版本时不许声明发布构建(--identity --release ⇒ rc=2)" <<'PY'
import subprocess
p = subprocess.run(["python3", "scripts/version.py", "--identity", "--release"], capture_output=True, text=True)
okv = p.returncode == 2 and "发布构建" in (p.stderr or "")
okv = (p.returncode == 2 and "不标为正式版" in (p.stderr or "")
and '"build_kind": "development"' in (p.stdout or ""))
print(("✅ " if okv else "❌ ") + f"退出码 {p.returncode}|{(p.stderr or '').strip().splitlines()[:1]}")
raise SystemExit(0 if okv else 1)
PY
pycheck "构建身份自检:证据齐(注释 tag + 完整 SHA + 提交内版本一致)才叫正式构建" <<'PY'
import subprocess
p = subprocess.run(["python3", "scripts/version.py", "--self-test"], capture_output=True, text=True)
print(((p.stdout or "") + (p.stderr or "")).strip().splitlines()[-1][:200])
raise SystemExit(p.returncode)
PY
pycheck "正式构建要核证据:无 tag/tag 名不符/unknown SHA ⇒ 红;注释 tag 指向该提交 ⇒ 绿(临时仓库 + go test)" <<'PY'
import os, pathlib, shutil, subprocess, tempfile
GO = shutil.which("go") or "/home/zheromiku/.local/go/bin/go"
SRC = pathlib.Path("internal/version")
def seed(d):
(d / "internal" / "version").mkdir(parents=True)
for f in SRC.glob("*.go"):
shutil.copy(f, d / "internal" / "version" / f.name)
(d / "go.mod").write_text("module knowledge-governance\n\ngo 1.21\n", encoding="utf-8")
(d / "CHANGELOG.md").write_text(
"# Changelog\n\n## [Unreleased]\n\n### Added\n\n- x\n\n"
"## [0.2.0] - 2026-02-01\n\n### Fixed\n\n- y\n", encoding="utf-8")
(d / "no-hooks").mkdir(exist_ok=True)
os.environ.update({"GIT_AUTHOR_NAME": "f", "GIT_AUTHOR_EMAIL": "f@f",
"GIT_COMMITTER_NAME": "f", "GIT_COMMITTER_EMAIL": "f@f",
"GIT_CONFIG_COUNT": "1", "GIT_CONFIG_KEY_0": "core.hooksPath",
"GIT_CONFIG_VALUE_0": str(d / "no-hooks"), "GOFLAGS": "-mod=mod"})
for args in (["init", "-q", "-b", "main"], ["add", "-A"], ["commit", "-q", "-m", "chore: 夹具"]):
subprocess.run(["git", *args], cwd=d, check=True, capture_output=True)
return subprocess.run(["git", "rev-parse", "HEAD"], cwd=d, capture_output=True,
text=True).stdout.strip()
def run(d, kind, rel, sha):
ld = (f"-X knowledge-governance/internal/version.Number={rel or 'dev'} "
f"-X knowledge-governance/internal/version.ReleaseVersion={rel} "
f"-X knowledge-governance/internal/version.BuildKind={kind} "
f"-X knowledge-governance/internal/version.CommitSHA={sha}")
return subprocess.run([GO, "test", "-count=1", "-run", "Test", f"-ldflags={ld}",
"./internal/version/..."], cwd=d, capture_output=True, text=True)
cases = []
with tempfile.TemporaryDirectory() as tmp:
d = pathlib.Path(tmp) / "r"; d.mkdir(); sha = seed(d)
p = run(d, "release", "0.2.0", sha)
cases.append(("有版本但**没有 tag** ⇒ 正式构建必须红", p.returncode != 0, (p.stdout + p.stderr)))
subprocess.run(["git", "tag", "-a", "v0.2.0", "-m", "release 0.2.0"], cwd=d, check=True,
capture_output=True)
p = run(d, "release", "0.2.0", sha)
cases.append(("注释 tag 指向该提交 + 版本一致 ⇒ 正式构建绿", p.returncode == 0, (p.stdout + p.stderr)))
p = run(d, "release", "0.2.0", sha[:12])
cases.append(("短 SHA ⇒ 红(正式构建要完整 40 位)", p.returncode != 0, (p.stdout + p.stderr)))
subprocess.run(["git", "tag", "-d", "v0.2.0"], cwd=d, check=True, capture_output=True)
subprocess.run(["git", "tag", "-a", "v9.9.9", "-m", "x"], cwd=d, check=True, capture_output=True)
p = run(d, "release", "0.2.0", sha)
cases.append(("只有别的 tag ⇒ 红", p.returncode != 0, (p.stdout + p.stderr)))
subprocess.run(["git", "tag", "-d", "v9.9.9"], cwd=d, check=True, capture_output=True)
subprocess.run(["git", "tag", "v0.2.0"], cwd=d, check=True, capture_output=True) # 轻量 tag
p = run(d, "release", "0.2.0", sha)
cases.append(("轻量 tag ⇒ 红(不算发布证据)", p.returncode != 0, (p.stdout + p.stderr)))
# 开发构建:ReleaseVersion 要等于该提交里 CHANGELOG 顶部的版本(注入口径),显示带 dev 标识
p = run(d, "development", "0.2.0", sha)
cases.append(("开发构建(有基线、带完整 SHA)⇒ 绿(显示 X.Y.Z-dev+g<短SHA>,不是只显示正式号)",
p.returncode == 0, (p.stdout + p.stderr)))
bad = [n for n, okv, _ in cases if not okv]
for n, okv, tail in cases:
print(("✅ " if okv else "❌ ") + n + ("" if okv else "|" + tail.strip()[-200:]))
raise SystemExit(1 if bad else 0)
PY
# 变异测试①:把契约那一处的注入**整个拿掉** ⇒ 版本用例会 SKIP ⇒ 契约必须红(跳过不算通过)
cp scripts/ci_checks.py /tmp/kg-cichecks.bak
python3 - <<'PY'
@@ -594,6 +663,65 @@ if [ "$rc" -ne 0 ] && grep -q "未核对" /tmp/kg-pf-noapi.log; then
else
no "不核对远端却给了可发结论(退出码 $rc)"; tail -6 /tmp/kg-pf-noapi.log | sed 's/^/ /'
fi
pycheck "预检:候选版本**没进目标提交** ⇒ 不就绪;写进提交后该条阻塞消失(临时仓库,不打 tag、不推送、不查远端)" <<'PY'
import os, pathlib, subprocess, tempfile
def seed(d):
(d / "scripts").mkdir(parents=True)
(d / "docs").mkdir()
(d / ".gitea").mkdir()
for n in ("check_changelog.py", "release_preflight.py"):
(d / "scripts" / n).write_text(pathlib.Path("scripts") / n and
pathlib.Path("scripts", n).read_text(encoding="utf-8"),
encoding="utf-8")
(d / "docs" / "RELEASE_RUNBOOK.md").write_text("# 发布说明\n", encoding="utf-8")
(d / ".gitea" / "required-contexts.txt").write_text("build / build (push)\n", encoding="utf-8")
(d / "CHANGELOG.md").write_text(
"# Changelog\n\n## [Unreleased]\n\n### Added\n\n- 待发的东西\n", encoding="utf-8")
(d / "no-hooks").mkdir(exist_ok=True)
os.environ.update({"GIT_AUTHOR_NAME": "f", "GIT_AUTHOR_EMAIL": "f@f",
"GIT_COMMITTER_NAME": "f", "GIT_COMMITTER_EMAIL": "f@f",
"GIT_CONFIG_COUNT": "1", "GIT_CONFIG_KEY_0": "core.hooksPath",
"GIT_CONFIG_VALUE_0": str(d / "no-hooks")})
for args in (["init", "-q", "-b", "main"], ["add", "-A"], ["commit", "-q", "-m", "chore: 夹具"]):
subprocess.run(["git", *args], cwd=d, check=True, capture_output=True)
def pre(d):
p = subprocess.run(["python3", "scripts/release_preflight.py", "--version", "0.2.0", "--no-api"],
cwd=d, capture_output=True, text=True)
return p.returncode, (p.stdout + p.stderr)
cases = []
with tempfile.TemporaryDirectory() as tmp:
d = pathlib.Path(tmp) / "r"; d.mkdir(); seed(d)
rc1, t1 = pre(d)
cases.append(("记录只在工作区(没提交)⇒ 明说『还没写进目标提交』且不就绪",
rc1 == 1 and "还没写进目标提交" in t1 and "现在**不能**发" in t1))
cases.append(("就绪判定里含『准备建议』与『发布就绪判定』两段(不是混在一起)",
"── 准备建议" in t1 and "── 发布就绪判定 ──" in t1))
cases.append(("不推荐自动发布路径(输出里没有 --execute 的建议行)",
"--execute" not in t1))
cases.append(("首发未显式指定版本时,把建议值当已发布是禁止的 —— 这里显式给了 --version,"
"所以不该报『首个正式版本号必须由人显式指定』", "首个正式版本号必须由人显式指定" not in t1))
# 把版本记录**写进提交**(首发:显式版本号 + 记录进提交)
(d / "CHANGELOG.md").write_text(
"# Changelog\n\n## [0.2.0] - 2026-02-01\n\n### Added\n\n- 待发的东西\n", encoding="utf-8")
subprocess.run(["git", "add", "-A"], cwd=d, check=True, capture_output=True)
subprocess.run(["git", "commit", "-q", "-m", "chore(release): 0.2.0 记录"], cwd=d, check=True,
capture_output=True)
rc2, t2 = pre(d)
cases.append(("记录进了提交 ⇒ 『还没写进目标提交』这条阻塞**消失**",
"还没写进目标提交" not in t2))
cases.append(("仍然不就绪(没核对远端 / 没有 CI 证据)⇒ 不许给可发结论",
rc2 == 1 and "现在**不能**发" in t2))
cases.append(("候选记录存在 ≠ 已发布:不该出现『已存在』类误判",
"已存在" not in t2.replace("不存在(可发)", "")))
bad = [n for n, okv in cases if not okv]
for n, okv in cases:
print(("✅ " if okv else "❌ ") + n)
raise SystemExit(1 if bad else 0)
PY
if grep -qE "git tag -a|--data-binary|POST" /tmp/kg-pf.log; then
no "预检输出里出现了写操作迹象"
else
+241 -45
View File
@@ -9,6 +9,11 @@
三个都给齐、且预检没有阻塞项,才会 `git tag -a` + `git push <tag>` + 建 Release;
执行后**读回**(远端 tag SHA == 本地打的那个提交、Release 的 tag_name/version 一致)才算成功。
3. **拿不到证据就说拿不到**:没有凭据、查不到 CI 状态时打印"未核对",不写成"已通过"。
4. **输出分两段**:`准备建议`(还差什么)与 `发布就绪判定`(是否就绪);**就绪才算可发**。
5. **就绪 = 证据齐**:候选版本**已写进目标提交**、完整 SHA 指向准确提交、
**必需 context 集合全部 success**(集合来自 `.gitea/required-contexts.txt`,缺项/待定/失败/查询异常都阻断)、
远端 tag 已核对且未占用、**Release 查询只有 HTTP 404 才算「不存在」**。
6. **本预检不执行、也不推荐自动发布路径**:正式发版动作由人按 `docs/RELEASE_RUNBOOK.md` 执行。
用法:
python3 scripts/release_preflight.py # 建议 patch(默认)
@@ -138,6 +143,107 @@ def server_base() -> str:
return f"{u.scheme}://{u.netloc}"
REQUIRED_CONTEXTS_FILE = ROOT / ".gitea" / "required-contexts.txt"
def required_contexts(root: Path = ROOT) -> tuple[list[str], str]:
"""明确的必需 context 集合(一行一个,`#` 之后是注释)。
⚠️ 这份文件是"要求哪些检查"的**唯一来源**:缺失或只有注释 ⇒ **没有策略**
⇒ 就绪判定直接阻断(不许拿"体检时观察到哪些状态"顶替)。
"""
f = root / ".gitea" / "required-contexts.txt"
if not f.is_file():
return [], f"没有 {f.name}"
out = [l.split("#", 1)[0].strip() for l in f.read_text(encoding="utf-8").splitlines()]
out = [x for x in out if x]
return out, (f"{f.name}({len(out)} 条)" if out else f"{f.name} 只有注释 / 是空的")
def version_in_commit(sha: str, version: str, *, root: Path = ROOT) -> bool:
"""候选版本是否**已经写进那个提交**(查该提交里的 CHANGELOG.md,不看工作区)。
⚠️ 这是"准备 vs 就绪"的分界线:工作区里写了、没提交 ⇒ 还不是就绪。
"""
rc, blob = _git_read("show", f"{sha}:CHANGELOG.md", cwd=root)
if rc != 0:
return False
return bool(re.search(rf"^##\s*\[{re.escape(version)}\]", blob, re.MULTILINE))
def release_state(status: int) -> str:
"""Release 查询结果的语义:**只有 HTTP 404 代表「不存在」**,其余非 200 一律算查询异常。"""
if status == 200:
return "exists"
if status == 404:
return "absent"
return "error"
def readiness(f: dict) -> tuple[bool, list[str], list[str]]:
"""把**事实**翻成(是否就绪, 阻塞项, 准备建议)——纯函数,可用假事实直接自检。
就绪 = 证据齐:候选版本已写进目标提交、工作区干净、完整 SHA 指向准确提交、
记录检查通过、远端 tag 已核对且未占用、**必需 context 集合全部 success**、
Release 不存在(查询异常也不算就绪)。
"""
blockers: list[str] = []
advice: list[str] = []
cand = f.get("candidate") or "?"
if f.get("first_release") and not f.get("explicit_version"):
blockers.append(f"还没有已发布版本:首个正式版本号必须由人显式指定(--version X.Y.Z);"
f"{cand} 只是建议值,**不当作已发布**")
if not f.get("in_target_commit"):
blockers.append(f"候选版本 {cand} 还没写进目标提交(该提交的 CHANGELOG.md 里没有 `## [{cand}]`)"
f"—— 版本记录要先提交,再发版")
advice.append(f"把 `## [Unreleased]` 改成 `## [{cand}] - YYYY-MM-DD`(四类小节、"
f"破坏性变化带发布文档链接)并**提交**,然后重跑预检")
if f.get("candidate_tagged"):
blockers.append(f"远端已经有 tag v{cand} ⇒ 不能覆盖已发布的 tag(版本号只增不减)")
if f.get("dirty"):
blockers.append(f"工作区有 {f['dirty']} 处未提交")
if not f.get("head_full"):
blockers.append("HEAD 不是完整 40 位 SHA")
if not f.get("sha_is_head"):
blockers.append("目标提交 != HEAD(发版必须指向准确提交)")
if not f.get("checker_ok"):
blockers.append("CHANGELOG / 版本记录检查不通过")
if not f.get("unreleased_present"):
advice.append("CHANGELOG 里没有 `[Unreleased]` 段:发版前把这次改动写进记录")
if not f.get("remote_tags_checked"):
blockers.append("没有核对远端 tag 信息(查不到远端)—— 未核验不等于可以发")
if f.get("contexts_error"):
blockers.append(f"查不到该提交的 CI 状态({f['contexts_error']})")
req = f.get("required_contexts") or []
ctx = f.get("contexts")
if not req:
blockers.append("没有明确的必需 context 集合(`.gitea/required-contexts.txt` 缺失或为空)"
"—— 不许拿「体检时观察到的状态」顶替")
advice.append("把本仓真正必需的 status context 一行一个写进 `.gitea/required-contexts.txt`"
"(字符串要与 `GET /commits/<sha>/status` 里的 `context` 逐字符相同)")
elif not f.get("contexts_error"):
if ctx is None:
blockers.append("没有取到该提交的 status context")
else:
missing = [c for c in req if c not in ctx]
bad = [(c, ctx[c]) for c in req if c in ctx and ctx[c] != "success"]
if missing:
blockers.append(f"必需 context 缺项(该提交上没有这些状态):{missing}")
if bad:
blockers.append("必需 context 未全部 success:" + "、".join(f"{c}={v}" for c, v in bad))
if f.get("release_query_error"):
blockers.append(f"Release 查询异常({f['release_query_error']})—— 只有 HTTP 404 才算「不存在」,"
f"查询异常不得当作可发")
elif f.get("release_exists"):
blockers.append(f"Gitea Release {f.get('tag') or cand} 已存在")
if f.get("no_api"):
blockers.append("没有核对远端 Release / CI 状态(缺凭据或显式 --no-api)")
if not blockers:
advice.append("证据齐了:正式发版动作由人按 docs/RELEASE_RUNBOOK.md 执行(本预检只读、不执行)")
return (not blockers), blockers, advice
def main(argv: list[str]) -> int:
ap = argparse.ArgumentParser(add_help=True)
ap.add_argument("--bump", default="patch", choices=["major", "minor", "patch"])
@@ -207,83 +313,93 @@ def main(argv: list[str]) -> int:
if not checker_ok:
print(" " + (chk.stdout + chk.stderr).strip().replace("\n", "\n ")[-800:])
# 远端 tag / Release / CI 证据
# ── 事实收集(只读)──────────────────────────────────────────────
tag = f"v{candidate}"
blockers: list[str] = []
if first_release:
blockers.append(f"还没有已发布版本:首个正式版本号必须由人显式指定(--version X.Y.Z);"
f"{candidate} 只是建议值")
if dirty_lines:
blockers.append(f"工作区有 {len(dirty_lines)} 处未提交")
if not FULL_SHA.match(head):
blockers.append("HEAD 不是完整 40 位 SHA")
if want_sha != head:
blockers.append(f"--sha {want_sha[:12]} != HEAD {head[:12]}(发版必须指向准确提交)")
if not checker_ok:
blockers.append("CHANGELOG/版本记录检查不通过")
if not unreleased.strip():
blockers.append("没有 Unreleased 段:发版前要把这次改动写进 CHANGELOG")
if candidate in rel:
blockers.append(f"版本 {candidate} 已经在 CHANGELOG 里出现过(版本号只增不减)")
required, policy_src = required_contexts()
in_target = version_in_commit(want_sha, candidate)
mark = "✅ 已有" if in_target else "❌ 没有"
print(f"\n 目标提交内记录: {mark} `## [{candidate}]`"
f"(版本记录要先提交,再发版;查的是 {want_sha[:12]})")
print(f" 必需 context : {len(required)} 条({policy_src})"
+ (":" + "、".join(required) if required else ""))
token = "" if args.no_api else _cred(urllib.parse.urlparse(base).hostname or "")
rc, tags_out = _git_read("ls-remote", "--tags", "origin")
remote_tags = [l.split("refs/tags/")[-1] for l in tags_out.splitlines() if "refs/tags/" in l]
if f"{tag}^{{}}" in remote_tags:
remote_tags.remove(f"{tag}^{{}}")
if rc != 0 or args.no_api:
remote_tags_checked = rc == 0 and not args.no_api
if not remote_tags_checked:
why = "显式 --no-api" if args.no_api else "`git ls-remote --tags origin` 失败"
print(f"\n 远端 tag : **未核对**({why})—— 不能声称 tag 已核验")
blockers.append("没有核对远端 tag 信息(查不到远端)—— 未核验不等于可以发")
print(f" 远端 tag : **未核对**({why})—— 不能声称 tag 已核验")
else:
print(f"\n 远端 tag : {tag} {'已存在 ⛔ 不能覆盖已发布的 tag' if tag in remote_tags else '不存在(可发)'}"
f"|已存在的正式 tag: {[t for t in remote_tags if re.match(r'^v\\d', t)] or '(无)'}")
print(f" 远端 tag : {tag} {'已存在 ⛔ 不能覆盖已发布的 tag' if tag in remote_tags else '不存在(可发)'}"
f"|已存在的正式 tag: {[t for t in remote_tags if re.match(r'^v\d', t)] or '(无)'}")
contexts = None
contexts_error = ""
release_exists = False
release_query_error = ""
run_line = "(未查询)"
ctx_line = "(未查询)"
if token and base and slug:
st, body = _api_read(base, f"/repos/{slug}/releases/tags/{urllib.parse.quote(tag)}", token)
rel_exists = st == 200
print(f" Gitea Release: {tag} {'已存在 ⛔' if rel_exists else '不存在(可发)'}")
if rel_exists:
blockers.append(f"Gitea Release {tag} 已存在")
st, _ = _api_read(base, f"/repos/{slug}/releases/tags/{urllib.parse.quote(tag)}", token)
state = release_state(st)
note = {"exists": "已存在 ⛔ 不能覆盖", "absent": "不存在(可发)"}.get(
state, f"查询异常(HTTP {st})⛔ 只有 404 才算「不存在」,不得当作可发")
print(f" Gitea Release: {tag} {note}")
release_exists = state == "exists"
if state == "error":
release_query_error = f"HTTP {st}"
st, stt = _api_read(base, f"/repos/{slug}/commits/{head}/status", token)
if st == 200:
ctxs = [(s.get("context"), s.get("status")) for s in stt.get("statuses") or []]
ctx_line = "、".join(f"{c}={v}" for c, v in ctxs) or "(这个提交上一个状态都没有)"
if not any(v == "success" for _, v in ctxs):
blockers.append(f"提交 {head[:12]} 上没有成功的 status context(CI 证据不足)")
contexts = {x.get("context"): x.get("status") for x in stt.get("statuses") or []}
ctx_line = "、".join(f"{c}={v}" for c, v in contexts.items()) or "(这个提交上一个状态都没有)"
else:
contexts_error = f"HTTP {st}"
ctx_line = f"(查不到:HTTP {st})"
blockers.append("查不到该提交的 CI 状态")
st, runs = _api_read(base, f"/repos/{slug}/actions/runs?limit=20", token)
if st == 200:
mine = [r for r in (runs.get("workflow_runs") or [])
if (r.get("head_sha") or "") == head]
if mine:
r0 = mine[0]
run_line = (f"run #{r0.get('run_number')} {r0.get('status')} "
f"{r0.get('url') or ''}".strip())
run_line = (f"run #{mine[0].get('run_number')} {mine[0].get('status')} "
f"{mine[0].get('url') or ''}".strip())
else:
run_line = "(这个提交上没有运行记录)"
else:
print(f" Gitea Release: **未核对**({'显式 --no-api' if args.no_api else '没有取到凭据'})")
blockers.append("没有核对远端 Release/CI 状态(缺凭据)")
print(f" CI 状态 : {ctx_line}")
print(f" 最近运行 : {run_line}")
print(" 遗留风险/未验证: 见 docs/BACKLOG.md 与本次 Unreleased 里写明的未验证项"
"(预检不替你判断它们的可接受性)")
print("\n── 结论 ──")
if blockers:
facts = {
"candidate": candidate, "tag": tag, "first_release": first_release,
"explicit_version": bool(args.version), "in_target_commit": in_target,
"dirty": len(dirty_lines), "head_full": bool(FULL_SHA.match(head)),
"sha_is_head": want_sha == head, "checker_ok": checker_ok,
"unreleased_present": bool(unreleased.strip()),
"candidate_tagged": bool(remote_tags_checked and tag in remote_tags),
"remote_tags_checked": remote_tags_checked,
"required_contexts": required, "contexts": contexts, "contexts_error": contexts_error,
"release_exists": release_exists, "release_query_error": release_query_error,
"no_api": bool(args.no_api),
}
ready, blockers, advice = readiness(facts)
print("\n── 准备建议(先做完这些,才有「就绪」可言)──")
for a in (advice or ["(没有额外建议)"]):
print(f" · {a}")
print("\n── 发布就绪判定 ──")
if ready:
print(f" ✅ 发布就绪:{candidate}(tag {tag} → 提交 {head[:12]})")
print(" ⚠️ 正式发版动作**不在本预检里执行、也不推荐自动路径**:"
"步骤与读回判据见 docs/RELEASE_RUNBOOK.md,由人按批准执行。")
else:
for b in blockers:
print(f" ⛔ {b}")
print(f" ⇒ 现在**不能**发 {candidate}")
else:
print(f" ✅ 预检通过:可以发 {candidate}(tag {tag} → 提交 {head[:12]})")
print(" 批准后执行(本轮不执行):")
print(f" python3 scripts/release_preflight.py --execute --version {candidate} "
f"--approve-version {candidate} --approve-sha {head}")
print(f" ⇒ 现在**不能**发 {candidate}(未就绪)")
if not args.execute:
return 1 if blockers else 0
@@ -356,12 +472,92 @@ def self_test() -> int:
# 版本号推进
if bump("1.2.3", "patch") != "1.2.4" or bump("1.2.3", "minor") != "1.3.0" or bump("1.2.3", "major") != "2.0.0":
problems.append("版本推进算错了")
# ── 就绪判定:全部用**假事实**驱动纯函数(不打真 tag、不碰网络)──
base_facts = {
"candidate": "0.2.0", "tag": "v0.2.0", "first_release": False,
"explicit_version": True, "in_target_commit": True, "dirty": 0,
"head_full": True, "sha_is_head": True, "checker_ok": True,
"unreleased_present": True, "candidate_tagged": False,
"remote_tags_checked": True, "required_contexts": ["build / build (push)"],
"contexts": {"build / build (push)": "success"}, "contexts_error": "",
"release_exists": False, "release_query_error": "", "no_api": False,
}
def rd(name: str, ready_want: bool, needle: str = "", **over) -> None:
f = {**base_facts, **over}
ready, blockers, _ = readiness(f)
joined = " / ".join(blockers)
if ready != ready_want or (needle and needle not in joined):
problems.append(f"就绪判定[{name}]:ready={ready}(期望 {ready_want})blockers={joined[:160]}")
rd("证据齐 ⇒ 就绪", True)
rd("必需 context pending ⇒ 不就绪", False, "未全部 success", contexts={"build / build (push)": "pending"})
rd("必需 context failure ⇒ 不就绪", False, "未全部 success", contexts={"build / build (push)": "failure"})
rd("必需 context 没被报出来(缺项)⇒ 不就绪", False, "缺项", contexts={"other / other (push)": "success"})
rd("有别的 context 成功但必需项没报 ⇒ 仍不就绪", False, "缺项",
required_contexts=["build / build (push)", "lint / lint (push)"])
rd("status 查询异常 ⇒ 不就绪", False, "查不到该提交的 CI 状态", contexts_error="HTTP 500")
rd("没有必需 context 策略 ⇒ 不就绪", False, "没有明确的必需 context 集合", required_contexts=[])
rd("Release 查询异常 ⇒ 不就绪", False, "Release 查询异常", release_query_error="HTTP 500")
rd("Release 已存在 ⇒ 不就绪", False, "已存在", release_exists=True)
rd("远端 tag 已被占用 ⇒ 不就绪", False, "不能覆盖已发布的 tag", candidate_tagged=True)
rd("没核对远端 tag ⇒ 不就绪", False, "没有核对远端 tag", remote_tags_checked=False)
rd("首发未显式指定版本 ⇒ 不就绪", False, "首个正式版本号必须由人显式指定",
first_release=True, explicit_version=False)
rd("首发**显式**指定且记录已进提交 ⇒ 就绪", True,
first_release=True, explicit_version=True, contexts={"build / build (push)": "success"})
rd("候选版本没进目标提交 ⇒ 不就绪", False, "还没写进目标提交", in_target_commit=False)
rd("工作区脏 ⇒ 不就绪", False, "未提交", dirty=3)
rd("目标提交 != HEAD ⇒ 不就绪", False, "目标提交 != HEAD", sha_is_head=False)
rd("记录检查不通过 ⇒ 不就绪", False, "检查不通过", checker_ok=False)
rd("缺凭据/--no-api ⇒ 不就绪", False, "没有核对远端 Release", no_api=True)
# 候选记录存在 ≠ 已发布:三种证据都齐时应当就绪,且阻塞项里不该出现"已发布"
_, bl, _ = readiness(base_facts)
if any("已发布" in b for b in bl):
problems.append(f"把『记录里有这个版本』误当成『已发布』:{bl}")
for st, want in ((200, "exists"), (404, "absent"), (500, "error"), (403, "error"), (0, "error")):
if release_state(st) != want:
problems.append(f"Release 查询语义错:HTTP {st} 判成了 {release_state(st)}(期望 {want})")
# ── 临时仓库:候选版本"写进提交才算数" ──
import tempfile as _tf
with _tf.TemporaryDirectory() as d:
dd = Path(d)
(dd / "no-hooks").mkdir(exist_ok=True)
env = {**dict(**__import__("os").environ), "GIT_AUTHOR_NAME": "t", "GIT_AUTHOR_EMAIL": "t@t",
"GIT_COMMITTER_NAME": "t", "GIT_COMMITTER_EMAIL": "t@t",
"GIT_CONFIG_COUNT": "1", "GIT_CONFIG_KEY_0": "core.hooksPath",
"GIT_CONFIG_VALUE_0": str(dd / "no-hooks")}
(dd / "CHANGELOG.md").write_text("# Changelog\n\n## [Unreleased]\n\n### Added\n\n- x\n",
encoding="utf-8")
subprocess.run(["git", "init", "-q", "-b", "main"], cwd=dd, env=env, check=True)
subprocess.run(["git", "add", "-A"], cwd=dd, env=env, check=True)
subprocess.run(["git", "commit", "-q", "-m", "chore: 夹具"], cwd=dd, env=env, check=True)
sha = subprocess.run(["git", "rev-parse", "HEAD"], cwd=dd, capture_output=True,
text=True).stdout.strip()
if version_in_commit(sha, "0.2.0", root=dd):
problems.append("未提交的版本被当成了『已写进目标提交』")
(dd / "CHANGELOG.md").write_text(
"# Changelog\n\n## [0.2.0] - 2026-02-01\n\n### Fixed\n\n- y\n", encoding="utf-8")
if version_in_commit(sha, "0.2.0", root=dd):
problems.append("工作区改了但没提交,仍被判成『已写进目标提交』")
subprocess.run(["git", "add", "-A"], cwd=dd, env=env, check=True)
subprocess.run(["git", "commit", "-q", "-m", "chore(release): 0.2.0"], cwd=dd, env=env, check=True)
sha2 = subprocess.run(["git", "rev-parse", "HEAD"], cwd=dd, capture_output=True,
text=True).stdout.strip()
if not version_in_commit(sha2, "0.2.0", root=dd):
problems.append("版本写进提交后仍判成『没有』")
if problems:
print("❌ 预检自检失败:", file=sys.stderr)
for p in problems:
print(f" · {p}", file=sys.stderr)
return 1
print("✅ 预检自检通过:写类 git 命令与 POST/PUT/DELETE/PATCH 在预检路径上全部被拒;版本推进正确")
print("✅ 预检自检通过:写类 git 命令与 POST/PUT/DELETE/PATCH 在预检路径上全部被拒;版本推进正确;"
"就绪判定 19 个分支(context 缺项/pending/failure/查询异常、无策略、Release 非 404、"
"tag 占用、未核对远端、首发未显式指定、记录未进提交…逐条阻断;证据齐才就绪);"
"『写进提交才算数』用临时仓库验证")
return 0
+5
View File
@@ -48,6 +48,11 @@
"package": "knowledge-governance/internal/version",
"test": "TestDevBuildDoesNotClaimRelease",
"reason": "构建身份未注入时按设计 SKIP(本地跑全量测试不该被迫先构建);**它的强制点在 contracts 项**:那里带 -ldflags 跑它并断言真的 PASS、且出现 SKIP 就判红"
},
{
"package": "knowledge-governance/internal/version",
"test": "TestReleaseBuildRequiresEvidence",
"reason": "构建身份未注入时按设计 SKIP(本地跑全量测试不该被迫先构建);**它的强制点在 contracts 项**:那里带 -ldflags 跑它并断言真的 PASS、且出现 SKIP 就判红"
}
]
}
+184 -9
View File
@@ -14,6 +14,10 @@ CI 只做**核验**(tag 版本 == 它指到那个提交里的版本记录)
python3 scripts/version.py --identity --release # 声明发布构建;没有已发布版本 ⇒ 拒绝(rc=2)
python3 scripts/version.py --check # 打印版本号并跑结构自检(等价 check-changelog.py)
**正式构建身份不是"加个 --release 标志"就算**:`--identity --release` 会**核证据**——
完整 40 位 SHA + 一个**指向该提交的合规注释 tag** `v<版本号>` + 该提交里 CHANGELOG 顶部版本一致;
缺任何一条 ⇒ **拒绝标为正式版**(rc=2,JSON 里带 `release_blocked` 说明缺什么)。
构建身份字段(`--identity`):
release_version 正式版本基线;本仓还没有正式发布过 ⇒ `null`
build_kind development | release(**只有显式声明**才是 release,普通 main CI 永远不是)
@@ -31,6 +35,7 @@ import os
import re
import subprocess
import sys
import tempfile
from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent
@@ -67,13 +72,60 @@ def display_version(release_version: str | None, kind: str, sha: str) -> str:
return f"dev+g{short}" if short else "dev"
def _git(*args, cwd: Path = ROOT) -> tuple[int, str]:
p = subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True)
return p.returncode, (p.stdout if p.returncode == 0 else p.stderr)
def release_evidence(version: str | None, sha: str, root: Path = ROOT) -> list[str]:
"""正式构建要核的证据;返回缺失项(空列表 = 证据齐)。
三条都必需(缺一条就**不许**把产物标成正式版):
1. 完整 40 位提交 SHA —— 没有准确提交就谈不上"正式版";
2. 该提交上有**注释 tag** `v<版本号>`(`git tag --points-at <sha>` + `cat-file -t` 判类型);
3. 该提交里的 `CHANGELOG.md` 顶部已发布版本 == 这个版本号(版本一致性)。
"""
problems: list[str] = []
if not version:
problems.append("CHANGELOG.md 里没有已发布版本条目(没有正式版本基线)")
if not FULL_SHA.match(sha or ""):
problems.append(f"提交 SHA 不是完整 40 位({sha!r})—— 没有准确提交就不能标为正式版")
if version and FULL_SHA.match(sha or ""):
name = f"v{version}"
rc, out = _git("tag", "--points-at", sha, cwd=root)
tags = out.split() if rc == 0 else []
if name not in tags:
problems.append(f"提交 {sha[:12]} 上没有 tag {name}"
f"(正式构建必须有一个指向该提交的合规 tag;现有指向该提交的 tag:{tags or '无'})")
else:
rc, kind = _git("cat-file", "-t", f"refs/tags/{name}", cwd=root)
if rc != 0 or kind.strip() != "tag":
problems.append(f"tag {name} 不是**注释 tag**(`git tag -a`)—— 轻量 tag 不算发布证据")
rc, blob = _git("show", f"{sha}:CHANGELOG.md", cwd=root)
if rc != 0:
problems.append(f"取不到该提交里的 CHANGELOG.md({sha[:12]})—— 没法核对版本一致性")
else:
m = RELEASE_HEADING.search(blob)
top = m.group(1) if m else None
if top != version:
problems.append(f"该提交里 CHANGELOG 顶部的已发布版本是 {top!r},与 {version!r} 不一致")
return problems
def identity(*, release: bool = False, built_at: str | None = None,
root: Path = ROOT, sha: str | None = None) -> dict:
"""构建身份。`release=True` 但没有已发布版本 ⇒ 由调用方拒绝(见 main)。"""
"""构建身份(不含证据核验,供 `--identity` 的非发布路径与测试使用)。"""
return build_identity(release=release, built_at=built_at, root=root, sha=sha)[0]
def build_identity(*, release: bool = False, built_at: str | None = None,
root: Path = ROOT, sha: str | None = None) -> tuple[dict, list[str]]:
"""构建身份 + 证据缺失项。`release=True` 但证据不齐 ⇒ 身份退回 development 并给出原因。"""
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 {
problems = release_evidence(rel, sha, root) if release else []
kind = "release" if (release and not problems) else "development"
ident = {
"release_version": rel,
"build_kind": kind,
"commit_sha": sha,
@@ -81,18 +133,141 @@ def identity(*, release: bool = False, built_at: str | None = None,
"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"),
}
if problems:
ident["release_blocked"] = problems
return ident, problems
# ── 反向自检:**全部在临时仓库里造 tag**,不给真仓造任何 tag ─────────────────
_SAMPLE = """# Changelog
## [Unreleased]
### Added
- 还没发布
## [0.2.0] - 2026-02-01
### Fixed
- y
"""
def _tmp_repo(changelog: str = _SAMPLE) -> tuple[Path, str, dict]:
"""造一个临时仓库(一个提交),返回 (目录, HEAD, git 环境)。"""
d = Path(tempfile.mkdtemp(prefix="kg-ver-"))
(d / "no-hooks").mkdir(exist_ok=True)
env = {**os.environ, "GIT_AUTHOR_NAME": "t", "GIT_AUTHOR_EMAIL": "t@t",
"GIT_COMMITTER_NAME": "t", "GIT_COMMITTER_EMAIL": "t@t",
"GIT_CONFIG_COUNT": "1", "GIT_CONFIG_KEY_0": "core.hooksPath",
"GIT_CONFIG_VALUE_0": str(d / "no-hooks")}
(d / "CHANGELOG.md").write_text(changelog, encoding="utf-8")
for args in (["init", "-q", "-b", "main"], ["add", "-A"],
["commit", "-q", "-m", "chore: 夹具提交"]):
subprocess.run(["git", *args], cwd=d, env=env, check=True)
sha = subprocess.run(["git", "rev-parse", "HEAD"], cwd=d, capture_output=True,
text=True).stdout.strip()
return d, sha, env
def self_test() -> int:
problems: list[str] = []
dirs: list[Path] = []
def case(name: str, cond: bool, detail: str = "") -> None:
if not cond:
problems.append(f"{name} —— {detail}")
# ① 证据齐:注释 tag 指向该提交 + 提交内 CHANGELOG 一致 ⇒ 正式构建
d, sha, env = _tmp_repo(); dirs.append(d)
subprocess.run(["git", "tag", "-a", "v0.2.0", "-m", "release 0.2.0"], cwd=d, env=env, check=True)
ident, blocked = build_identity(release=True, root=d, sha=sha, built_at="t")
case("证据齐 ⇒ build_kind=release", ident["build_kind"] == "release" and not blocked, f"{ident}")
case("证据齐 ⇒ display_version=0.2.0", ident["display_version"] == "0.2.0", f"{ident['display_version']!r}")
# ② 有版本但**没有 tag** ⇒ 不许标正式
d2, sha2, _ = _tmp_repo(); dirs.append(d2)
ident2, blocked2 = build_identity(release=True, root=d2, sha=sha2, built_at="t")
case("有版本但无 tag ⇒ 不标正式",
ident2["build_kind"] == "development" and any("没有 tag" in x for x in blocked2), f"{blocked2}")
# ③ SHA 不是完整 40 位 ⇒ 不许标正式
ident3, blocked3 = build_identity(release=True, root=d, sha="unknown", built_at="t")
case("unknown SHA ⇒ 不标正式",
ident3["build_kind"] == "development" and any("不是完整 40 位" in x for x in blocked3), f"{blocked3}")
ident3b, blocked3b = build_identity(release=True, root=d, sha=sha[:12], built_at="t")
case("短 SHA ⇒ 不标正式",
ident3b["build_kind"] == "development" and any("不是完整 40 位" in x for x in blocked3b), f"{blocked3b}")
# ④ tag 指错提交 ⇒ 不许标正式(tag 打在**后一个**提交上,却按前一个提交去问)
d4, first4, env4 = _tmp_repo(); dirs.append(d4)
(d4 / "extra.txt").write_text("x", encoding="utf-8")
subprocess.run(["git", "add", "-A"], cwd=d4, env=env4, check=True)
subprocess.run(["git", "commit", "-q", "-m", "chore: 第二个提交"], cwd=d4, env=env4, check=True)
second4 = subprocess.run(["git", "rev-parse", "HEAD"], cwd=d4, capture_output=True,
text=True).stdout.strip()
subprocess.run(["git", "tag", "-a", "v0.2.0", "-m", "release", second4], cwd=d4, env=env4, check=True)
ident4, blocked4 = build_identity(release=True, root=d4, sha=first4, built_at="t")
case("tag 指错提交 ⇒ 不标正式",
ident4["build_kind"] == "development" and any("没有 tag v0.2.0" in x for x in blocked4), f"{blocked4}")
# ⑤ 轻量 tag ⇒ 不许标正式(注释 tag 才是发布证据)
d5, sha5, env5 = _tmp_repo(); dirs.append(d5)
subprocess.run(["git", "tag", "v0.2.0"], cwd=d5, env=env5, check=True)
ident5, blocked5 = build_identity(release=True, root=d5, sha=sha5, built_at="t")
case("轻量 tag ⇒ 不标正式",
ident5["build_kind"] == "development" and any("注释 tag" in x for x in blocked5), f"{blocked5}")
# ⑥ 提交内 CHANGELOG 顶部版本与"声称的版本"不一致 ⇒ 不许标正式
# 做法:提交里的记录是 0.2.0,tag 却叫 v0.3.0(指向该提交),工作区又写着 0.3.0 ⇒ 三条中
# "版本一致性"这一条会红(tag 存在、注释、SHA 也完整,问题只出在版本对不上)。
d6, sha6, env6 = _tmp_repo(); dirs.append(d6)
subprocess.run(["git", "tag", "-a", "v0.3.0", "-m", "release 0.3.0"], cwd=d6, env=env6, check=True)
(d6 / "CHANGELOG.md").write_text(_SAMPLE.replace("0.2.0", "0.3.0"), encoding="utf-8")
ident6, blocked6 = build_identity(release=True, root=d6, sha=sha6, built_at="t")
case("声称版本与提交内记录不一致 ⇒ 不标正式",
ident6["build_kind"] == "development" and any("不一致" in x for x in blocked6), f"{blocked6}")
# ⑦ 开发构建:有基线 ⇒ X.Y.Z-dev+g<短SHA>;无基线 ⇒ dev+g<短SHA>
dev, _ = build_identity(root=d, sha=sha, built_at="t")
case("开发构建(有基线)= 0.2.0-dev+g<短SHA>",
dev["build_kind"] == "development" and dev["display_version"] == f"0.2.0-dev+g{sha[:12]}",
f"{dev['display_version']!r}")
d7, sha7, _ = _tmp_repo("# Changelog\n\n## [Unreleased]\n\n### Added\n\n- x\n"); dirs.append(d7)
dev7, _ = build_identity(root=d7, sha=sha7, built_at="t")
case("开发构建(无基线)= dev+g<短SHA>",
dev7["release_version"] is None and dev7["display_version"] == f"dev+g{sha7[:12]}",
f"{dev7}")
for x in dirs:
subprocess.run(["rm", "-rf", str(x)], capture_output=True)
if problems:
print("❌ 构建身份自检失败:", file=sys.stderr)
for x in problems:
print(f" · {x}", file=sys.stderr)
return 1
print("✅ 构建身份自检通过:证据齐(注释 tag + 完整 SHA + 提交内版本一致)才是正式构建;"
"无 tag / unknown 或短 SHA / tag 指错提交 / 轻量 tag / 版本不一致 逐条拒绝;"
"开发构建带显式 dev 标识")
return 0
def main(argv: list[str]) -> int:
if "--self-test" in argv:
return self_test()
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)
ident, problems = build_identity(release=release)
print(json.dumps(ident, ensure_ascii=False, indent=2))
if release and problems:
print("❌ 声明了正式构建(--release / BUILD_KIND=release),但发布证据不齐 —— "
"**不标为正式版**(身份已退回 development):", file=sys.stderr)
for x in problems:
print(f" · {x}", file=sys.stderr)
return 2
print(json.dumps(identity(release=release), ensure_ascii=False, indent=2))
return 0
v = current_version()