Files
knowledge-governance/scripts/check_changelog.py
T
姚章浩 40d84994cb feat(ci): 版本记录检查(四节 + 正式 tag 一致性)+ 只读发版预检
check_changelog.py:正式版本条目必须四节齐备且非空(改了什么/兼容性与迁移影响/怎么验收/已知问题)、版本号三段无前导零、[Unreleased] 在最上面;新增 --tags 核对正式 tag(必须注释 tag)与它指到那个提交里的版本记录一致。只有 Unreleased 的新工程放行;没有正式 tag 不判红(开发版本不打 tag 是常态)。ci_checks.py:新增必需检查 version(门禁 15 项),策略版本 ci-checks/2。ci_checkout.sh:记录远端 tag 清单并取 tag 对象供核对。release_preflight.py:只读预检(版本建议/完整 SHA/CI 证据/CHANGELOG/远端 tag 与 Release/遗留项),写类 git 命令与 POST 在预检路径上被拒(--self-test 证明);批准后 --execute 才打注释 tag、推 tag、建 Release 并读回。CHANGELOG 0.1.0 补上原本缺的两节。
2026-10-12 17:57:43 +08:00

364 lines
16 KiB
Python
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/usr/bin/env python3
"""CHANGELOG / 版本记录检查 —— 把"版本规则"变成退出码(正本 §6)。
判据(每条都能被 --self-test 证明会红):
A. 结构(默认就跑)
1. 至少一个已发布版本条目;`[Unreleased]` 段若有,必须在最上面、可以只有 `改了什么`;
2. 已发布版本标题 `## [x.y.z] - YYYY-MM-DD`:三段数字、**不许前导零**、日期必备;
3. 每个已发布版本块必须有**四节**:`改了什么`、`兼容性与迁移影响`、`怎么验收`、`已知问题`
("已知问题"可以写“无”,但不能整节空着 —— 空节等于没写);
4. 版本号不重复、按出现顺序严格递减(最新在最上面);
5. 已发布版本块本身不为空。
B. tag 一致性(`--tags` / CI 里跑)
6. 正式 tag 形如 `v<版本号>`,且必须是**注释 tag**(轻量 tag 不合格);
7. 每个正式 tag 指到的那个提交里,`CHANGELOG.md` 顶部的已发布版本 == 该 tag 的版本
(防止"tag 指着的提交从没被记进变更记录");
8. **没有 tag 是正常的**:开发版本不打 tag 绝不能让日常 CI 变红;
看不到远端 tag 时(缺 `.ci-remote-tags`)明说"没核对远端",不假绿。
用法:
python3 scripts/check_changelog.py # 只查结构
python3 scripts/check_changelog.py --tags # 结构 + 本地 tag 一致性
python3 scripts/check_changelog.py --self-test # 反向自检(含造 tag 的夹具)
"""
from __future__ import annotations
import re
import subprocess
import sys
import tempfile
from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent
HEADING = re.compile(r"^##\s*\[([^\]]+)\](\s*-\s*(\d{4}-\d{2}-\d{2}))?\s*$", re.MULTILINE)
SEMVER = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$") # 不许前导零(01.2.3 不合格)
TAG_RE = re.compile(r"^v(\d+\.\d+\.\d+)$")
SEC_CHANGE = "### 改了什么"
SEC_COMPAT = "### 兼容性与迁移影响"
SEC_ACCEPT = "### 怎么验收"
SEC_KNOWN = "### 已知问题"
REQUIRED_SECS = (SEC_CHANGE, SEC_COMPAT, SEC_ACCEPT, SEC_KNOWN)
REMOTE_TAGS = ROOT / ".ci-remote-tags"
def _blocks(text: str):
out = []
matches = list(HEADING.finditer(text))
for i, m in enumerate(matches):
end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
out.append((m.group(0), m.group(1), m.group(3), text[m.end():end]))
return out
def _sec_body(body: str, sec: str) -> str:
tail = body.split(sec, 1)[1]
return re.split(r"^###\s", tail, maxsplit=1, flags=re.MULTILINE)[0]
def check(path: Path | None = None) -> list[str]:
path = path or (ROOT / "CHANGELOG.md")
if not path.is_file():
return [f"找不到 {path}"]
text = path.read_text(encoding="utf-8")
blocks = _blocks(text)
released = [b for b in blocks if b[1] != "Unreleased"]
if not released:
# ⚠️ "还没有发过版"不是错误:新工程只有 `[Unreleased]` 是正常的 ——
# 首次发版时把 Unreleased 改成 `## [0.1.0] - YYYY-MM-DD` 并补齐四节即可。
# (真一个段都没有,才是"没有版本记录"。)
if any(b[1] == "Unreleased" for b in blocks):
return []
return ["没有已发布版本条目(形如 `## [0.1.0] - 2026-10-10`)—— 也没有 `[Unreleased]` 段"]
problems: list[str] = []
# [Unreleased] 必须在最上面(日常改动先记这里)
if blocks and blocks[0][1] == "Unreleased":
pass
elif any(b[1] == "Unreleased" for b in blocks):
problems.append("[Unreleased] 段必须在最上面(日常改动先记这里,发版时把它改成版本号)")
seen: list[str] = []
for heading, ver, date, body in released:
if ver == "Unreleased":
continue
if not SEMVER.match(ver):
problems.append(f"{heading} 的版本号不合法(要 `主.次.修订` 三段十进制、不许前导零):{ver!r}")
continue
seen.append(ver)
if not date:
problems.append(f"{heading} 缺少日期(要写成 `## [{ver}] - YYYY-MM-DD`)")
for sec in REQUIRED_SECS:
if sec not in body:
problems.append(f"[{ver}] 缺少小节 `{sec}` —— 正式版本必须记录"
f"改了什么 / 兼容性与迁移影响 / 怎么验收 / 已知问题")
continue
if not [l for l in _sec_body(body, sec).splitlines()
if l.strip() and not l.strip().startswith("```")][:1]:
problems.append(f"[{ver}] 的 `{sec}` 下面是空的(不知道就写“无”,但不能空着)")
dupes = {v for v in seen if seen.count(v) > 1}
if dupes:
problems.append(f"版本号重复:{sorted(dupes)}")
nums = [tuple(int(x) for x in v.split(".")) for v in seen]
if nums != sorted(nums, reverse=True):
problems.append(f"版本号没有按出现顺序严格递减(最新应在最上面):{seen}")
return problems
def _git(*args, cwd=None) -> tuple[int, str]:
p = subprocess.run(["git", *args], cwd=cwd or ROOT, capture_output=True, text=True)
return p.returncode, (p.stdout if p.returncode == 0 else p.stderr)
def remote_tag_lines() -> tuple[list[str], str]:
"""tag 清单,每行「对象sha + refs/tags/<名>」。
取数顺序:① 检出步骤写的 `.ci-remote-tags`(CI 用,能证明远端有哪些 tag);
② 本地 `for-each-ref refs/tags`(**没核对远端**,来源里必须写明);③ `git ls-remote`。
"""
if REMOTE_TAGS.is_file():
return [l for l in REMOTE_TAGS.read_text(encoding="utf-8").splitlines() if l.strip()], \
f"远端清单 {REMOTE_TAGS.name}"
import subprocess as _sp
q = _sp.run(["git", "for-each-ref", "--format=%(objectname) %(refname)", "refs/tags"],
cwd=ROOT, capture_output=True, text=True)
if q.returncode == 0 and q.stdout.strip():
return [l for l in q.stdout.splitlines() if l.strip()], "本地 refs/tags(**只看得到本机取到的 tag,没核对远端**)"
rc, out = _git("ls-remote", "--tags", "origin")
if rc == 0:
return [l for l in out.splitlines() if l.strip()], "git ls-remote --tags origin(本机实时查)"
return [], "拿不到任何 tag 信息(本机没有 tag,也查不了远端)"
def check_tags(changelog: Path | None = None) -> list[str]:
"""正式 tag 的版本必须与**它指到的那个提交里**的版本记录一致。没有 tag ⇒ 不是问题。"""
changelog = changelog or (ROOT / "CHANGELOG.md")
problems: list[str] = []
lines, source = remote_tag_lines()
formal, notes = [], []
for line in lines:
parts = line.split()
if len(parts) < 2:
continue
sha, ref = parts[0], parts[-1]
name = ref.split("refs/tags/", 1)[-1]
if name.endswith("^{}"): # annotated tag 的解引用行,跳过
continue
m = TAG_RE.match(name)
(formal if m else notes).append((name, sha, m.group(1) if m else ""))
print(f"-- tag 核对:来源 {source}|正式 tag {len(formal)} 个"
f"{'|非正式(不判版本一致性):' + ', '.join(n for n, _, _ in notes) if notes else ''}")
for name, sha, ver in formal:
rc, commit = _git("rev-parse", sha + "^{commit}")
if rc != 0 or not commit.strip():
problems.append(f"tag {name}({sha[:12]})指向的提交在本机取不到 —— "
f"没法核对它的版本记录(检出步骤应当把 tag 取下来)")
continue
commit = commit.strip()
rc, kind = _git("cat-file", "-t", sha)
if rc == 0 and kind.strip() == "commit":
problems.append(f"tag {name} 是**轻量 tag**(不是注释 tag)—— 正式发布必须用注释 tag")
rc, blob = _git("show", commit + ":CHANGELOG.md")
if rc != 0:
problems.append(f"tag {name} 指到的提交里没有 CHANGELOG.md")
continue
tops = [b[1] for b in _blocks(blob) if b[1] != "Unreleased" and SEMVER.match(b[1])]
if not tops:
problems.append(f"tag {name} 指到的提交里 CHANGELOG.md 没有已发布版本条目")
elif tops[0] != ver:
problems.append(f"tag {name} 的版本 {ver} != 该提交里 CHANGELOG 顶部的版本 {tops[0]}"
f"(tag 指着的提交没有把这次发版记进变更记录)")
else:
print(f" ✅ {name} → {commit[:12]}:提交内顶部版本 {tops[0]} 与 tag 一致")
if not formal:
print(" (没有正式 tag —— 开发版本不打 tag 是正常的,不判红)")
return problems
GOOD = """# 变更记录
## [Unreleased]
### 改了什么
- 还没发布的东西
## [0.2.0] - 2026-02-01
### 改了什么
- 加了 X
### 兼容性与迁移影响
- 无(向后兼容)
### 怎么验收
1. 跑 `curl /health` 期望 200
### 已知问题
- 无
## [0.1.0] - 2026-01-01
### 改了什么
- 初版
### 兼容性与迁移影响
- 首次发布,无迁移
### 怎么验收
1. 起容器,打开首页
### 已知问题
- 集成用例需要 TEST_DATABASE_URL,CI 里跳过(已声明)
"""
BAD = """# 变更记录
## [0.1.0]
### 改了什么
- 没有日期、缺两节、而且版本顺序还倒着
## [0.2.0] - 2026-02-01
### 改了什么
- 上面那条比这条旧,顺序错了(版本号合法,但比上面的大)
"""
def _seed_repo(d: Path, changelog_text: str, tag: str, annotated: bool, tag_ver: str) -> str:
"""造一个最小 git 仓库:一个提交 + 一个 tag(指向该提交,tag 名与提交内版本可刻意不一致)。"""
env = {"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 / "no-hooks").mkdir(exist_ok=True)
for args in (["init", "-q", "-b", "main"],):
subprocess.run(["git", *args], cwd=d, env={**dict(**__import__("os").environ), **env}, check=True)
(d / "CHANGELOG.md").write_text(changelog_text, encoding="utf-8")
for args in (["add", "-A"], ["commit", "-q", "-m", "chore(release): 夹具提交"],
["tag", "-a", tag, "-m", f"release {tag}"] if annotated else ["tag", tag]):
subprocess.run(["git", *args], cwd=d, env={**dict(**__import__("os").environ), **env}, check=True)
return subprocess.run(["git", "rev-parse", "HEAD"], cwd=d, capture_output=True,
text=True).stdout.strip()
def self_test() -> int:
import os
problems: list[str] = []
with tempfile.TemporaryDirectory() as d:
g, b = Path(d) / "good.md", Path(d) / "bad.md"
g.write_text(GOOD, encoding="utf-8")
b.write_text(BAD, encoding="utf-8")
if check(g):
problems.append(f"合规夹具竟然报红:{check(g)}")
# 首次发版前(只有 Unreleased)必须放行 —— 否则每个新工程一开箱就红
(Path(d) / "new.md").write_text(
"# 变更记录\n\n## [Unreleased]\n\n### 改了什么\n\n- 还没发布\n", encoding="utf-8")
if check(Path(d) / "new.md"):
problems.append(f"只有 Unreleased 的新工程竟然报红:{check(Path(d) / 'new.md')}")
(Path(d) / "none.md").write_text("# 变更记录\n\n(什么都没有)\n", encoding="utf-8")
if not check(Path(d) / "none.md"):
problems.append("完全没有版本记录的文件竟然没报红")
joined = " / ".join(check(b))
for want in ["缺少日期", f"缺少小节 `{SEC_COMPAT}`", f"缺少小节 `{SEC_KNOWN}`", "严格递减"]:
if want not in joined:
problems.append(f"违规夹具没有报出 `{want}` —— 这条判据是死的")
# 前导零版本号必须报(B 夹具里已含,单独再钉一次)
(Path(d) / "zero.md").write_text(
"# 变更记录\n\n## [Unreleased]\n\n## [01.0.0] - 2026-01-01\n\n" + "".join(
f"{s}\n\n- x\n\n" for s in REQUIRED_SECS), encoding="utf-8")
if not any("不合法" in p for p in check(Path(d) / "zero.md")):
problems.append("带前导零的版本号没有判红")
# 空节必须报
(Path(d) / "empty.md").write_text(
"# 变更记录\n\n## [Unreleased]\n\n## [0.1.0] - 2026-01-01\n\n"
+ f"{SEC_CHANGE}\n\n- x\n\n{SEC_COMPAT}\n\n- 无\n\n{SEC_ACCEPT}\n\n- 无\n\n{SEC_KNOWN}\n\n",
encoding="utf-8")
if not any("下面是空的" in p for p in check(Path(d) / "empty.md")):
problems.append("空的『已知问题』节没有判红")
# ── tag 一致性(造真仓库)──
with tempfile.TemporaryDirectory() as d:
repo_ok = Path(d) / "ok"
repo_ok.mkdir()
_seed_repo(repo_ok, GOOD, "v0.2.0", annotated=True, tag_ver="0.2.0")
globals()["REMOTE_TAGS"] = repo_ok / "absent" # 走本地 ls-remote 失败 → tag -l 分支
globals()["ROOT"] = repo_ok
try:
if check_tags(repo_ok / "CHANGELOG.md"):
problems.append(f"tag 一致时竟然报红:{check_tags(repo_ok / 'CHANGELOG.md')}")
repo_bad = Path(d) / "bad"
repo_bad.mkdir()
_seed_repo(repo_bad, GOOD, "v9.9.9", annotated=True, tag_ver="9.9.9")
globals()["ROOT"] = repo_bad
if not any("!=" in p for p in check_tags(repo_bad / "CHANGELOG.md")):
problems.append("tag 版本与提交内版本不一致时没有判红")
repo_light = Path(d) / "light"
repo_light.mkdir()
_seed_repo(repo_light, GOOD, "v0.2.0", annotated=False, tag_ver="0.2.0")
globals()["ROOT"] = repo_light
if not any("轻量 tag" in p for p in check_tags(repo_light / "CHANGELOG.md")):
problems.append("轻量 tag 没有判红")
repo_none = Path(d) / "none"
repo_none.mkdir()
_seed_repo(repo_none, GOOD, "v0.2.0", annotated=True, tag_ver="0.2.0")
subprocess.run(["git", "tag", "-d", "v0.2.0"], cwd=repo_none, capture_output=True)
globals()["ROOT"] = repo_none
if check_tags(repo_none / "CHANGELOG.md"):
problems.append("没有 tag 时竟然报红(开发版本不打 tag 是正常的)")
finally:
globals()["REMOTE_TAGS"] = REMOTE_TAGS
globals()["ROOT"] = ROOT
_ = os
if problems:
print("❌ 反向自检失败:", file=sys.stderr)
for p in problems:
print(f" · {p}", file=sys.stderr)
return 1
print("✅ 反向自检通过:合规夹具全绿;缺日期/缺小节/前导零/空节/顺序倒置/tag 版本不符/"
"轻量 tag/无记录逐条报红;无 tag 与「只有 Unreleased」不报红")
return 0
def main(argv: list[str]) -> int:
if "--self-test" in argv:
return self_test()
target = next((a for a in argv if not a.startswith("-")), None)
path = Path(target) if target else None
problems = check(path)
if "--tags" in argv or "--tag-check" in argv:
problems += check_tags(path)
if problems:
print("❌ CHANGELOG / 版本记录不合规:", file=sys.stderr)
for p in problems:
print(f" · {p}", file=sys.stderr)
print("\n正式版本条目写成:\n"
" ## [x.y.z] - YYYY-MM-DD\n\n ### 改了什么\n - …\n\n"
" ### 兼容性与迁移影响\n - …(看不清就写“无”,但不能空着)\n\n"
" ### 怎么验收\n 1. 命令 → 期望现象\n\n ### 已知问题\n - …\n",
file=sys.stderr)
return 1
print("✅ CHANGELOG / 版本记录合规" + ("(含 tag 一致性)" if ("--tags" in argv or "--tag-check" in argv) else ""))
return 0
if __name__ == "__main__":
raise SystemExit(main(sys.argv[1:]))