40d84994cb
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 补上原本缺的两节。
364 lines
16 KiB
Python
Executable File
364 lines
16 KiB
Python
Executable File
#!/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:])) |