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:
+21
-5
@@ -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` 形状(**不许声称正式版**),且**跳过不算通过**。
|
||||
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
|
||||
|
||||
@@ -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
@@ -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()
|
||||
|
||||
Reference in New Issue
Block a user