feat(version): 构建身份(release_version/build_kind/display_version),无基线也放行

解决"开发构建沿用已发布版本号,分不清开发版与正式版":

- 新增 `scripts/version.py --identity`:release_version(无基线即空)/ build_kind /
  commit_sha(完整 40 位)/ display_version / built_at。显示规则:发布 `X.Y.Z`、
  开发 `X.Y.Z-dev+g<短SHA>`、无基线 `dev+g<短SHA>`、什么都拿不到 `dev`。
- `build_kind=release` 只认**显式发布上下文**(`BUILD_KIND=release` / `--release`);
  声明发布构建却没有已发布版本 ⇒ 拒绝(rc=2)。普通 main 构建永远是 development,
  **不许只显示上一正式版本号、不许自称正式版**。
- Go 侧 `internal/version` 加 ReleaseVersion/BuildKind/DisplayVersion()/IsRelease()/Info(),
  原 Number/CommitSHA/BuildTime 语义不变(向后兼容);契约测试改成:发布构建必须等于
  CHANGELOG 顶部、开发构建必须是 dev 形状;`make verify` 的 contracts 项新增
  **负例**「自称正式版 ⇒ 必须红」(只有正例的契约会被静默掏空)。
- 构建接线:Makefile/Dockerfile/ci_checks `--internal-build` 统一走 identity;
  Makefile 的 `make version` 打印身份 JSON;Dockerfile 新增 RELEASE_VERSION/BUILD_KIND。
- `tests-go` 的"按设计跳过"声明补上 `TestDevBuildDoesNotClaimRelease`(它的强制点在 contracts)。

验证:go test 三态实测(未注入 SKIP、开发身份 PASS、自称正式版 FAIL);
--internal-build 产出并打印 dev+g<sha>;--internal-identity 契约项 rc=0;
make verify 15/15 success;反向夹具 80/0。
This commit is contained in:
姚章浩
2026-10-13 14:59:36 +08:00
parent 4f8ee0a8c5
commit 05144309c3
7 changed files with 348 additions and 97 deletions
+7 -3
View File
@@ -4,15 +4,19 @@ COPY go.mod go.sum ./
RUN go mod download
COPY cmd ./cmd
COPY internal ./internal
# 构建期身份:由调用方 --build-arg 传入。来源是仓库根 CHANGELOG.md 顶部的已发布版本
# (`python3 scripts/version.py`),**不要手填**。不传就落成 dev / unknown —— 那是故意的:
# 构建期身份:由调用方 --build-arg 传入。依据是仓库根 CHANGELOG.md 顶部的已发布版本
# (`python3 scripts/version.py --identity`),**不要手填**。不传就落成 dev / unknown —— 那是故意的:
# 一个显眼的 dev 好过一个看起来正常的假版本号(正本 §6.1)。
# BUILD_KIND 只有**显式的发布上下文**才传 release;普通构建一律 development,
# 产物的 DisplayVersion() 会是 dev+g<短SHA>(开发构建不许只显示上一正式版本号)。
# ⚠️ TODO:compose.yaml 还没把这三个 args 透传进来(改动会与在审的 PR #2 冲突),
# 所以当前由 compose 构建出的镜像会报 dev;透传后即报真实版本。
ARG VERSION=dev
ARG RELEASE_VERSION=
ARG BUILD_KIND=development
ARG COMMIT_SHA=unknown
ARG BUILD_TIME=unknown
RUN LDFLAGS="-X knowledge-governance/internal/version.Number=${VERSION} -X knowledge-governance/internal/version.CommitSHA=${COMMIT_SHA} -X knowledge-governance/internal/version.BuildTime=${BUILD_TIME}" \
RUN LDFLAGS="-X knowledge-governance/internal/version.Number=${VERSION} -X knowledge-governance/internal/version.ReleaseVersion=${RELEASE_VERSION} -X knowledge-governance/internal/version.BuildKind=${BUILD_KIND} -X knowledge-governance/internal/version.CommitSHA=${COMMIT_SHA} -X knowledge-governance/internal/version.BuildTime=${BUILD_TIME}" \
&& CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags "$LDFLAGS" -o /out/api ./cmd/api \
&& CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags "$LDFLAGS" -o /out/worker ./cmd/worker \
&& CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags "$LDFLAGS" -o /out/release-worker ./cmd/release-worker \
+24 -14
View File
@@ -2,11 +2,15 @@ GO ?= go
PY ?= python3
# 版本号的唯一来源是仓库根的 CHANGELOG.md(正本 §6.1:版本号只有一个来源)。
# 刻意**不用** `git describe --tags`:CI 检出是 `git fetch --depth 50`,取不到 tag,
# 刻意**不**在构建时跑 `git describe --tags`:日常检出是浅克隆、拿不到 tag,
# 那会让版本号在本地正常、在 CI 上静默退化(见 docs/agents/traps.md trap-5)。
VERSION ?= $(shell $(PY) scripts/version.py 2>/dev/null || echo dev)
COMMIT_SHA ?= $(shell git rev-parse --short=12 HEAD 2>/dev/null || echo unknown)
BUILD_TIME ?= $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
# **正式 tag** 由人批准后创建(注释 tag `vX.Y.Z`),CI 只核验「tag 版本 == 该提交里的版本记录」。
VERSION ?= $(shell $(PY) scripts/version.py 2>/dev/null || echo dev)
RELEASE_VERSION ?= $(shell $(PY) scripts/version.py 2>/dev/null || echo)
BUILD_KIND ?= development
COMMIT_SHA ?= $(shell git rev-parse --short=12 HEAD 2>/dev/null || echo unknown)
FULL_SHA ?= $(shell git rev-parse HEAD 2>/dev/null || echo unknown)
BUILD_TIME ?= $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
.PHONY: verify checks list \
format static-go static-web deps-install build-go build-web \
@@ -63,23 +67,29 @@ web-test: tests-web
web-typecheck: static-web
web-build: build-web
# 打印当前版本号(唯一来源:CHANGELOG.md 顶部那个已发布版本)
# 构建身份(JSON):release_version / build_kind / commit_sha / display_version / built_at
# 开发构建也能用:没有正式版本时是 dev+g<短SHA>,不会退化成"上一正式版本号"。
version:
@$(PY) scripts/version.py
@$(PY) scripts/version.py --identity
# 变更记录结构自检:每个已发布版本都必须有「改了什么」「怎么验收」两节
# 变更记录结构自检:小节只认 Added/Changed/Fixed/Security(分类可省略、不许空栏目),
# 破坏性变化必须在 Changed 里带发布文档链接。加 --tags 再核「tag 版本 == 该提交里的版本记录」。
changelog-check:
@$(PY) scripts/check_changelog.py
# 版本契约:注入进二进制的号必须等于 CHANGELOG 顶部。
# ⚠️ 不注入时该用例会 SKIP —— 那是"本地不想被迫先构建"的便利,但**CI 必须断言它真的 PASS**
# (门禁的 contracts 项就是这么做的;被跳过的断言等于没有断言)。
# 版本契约:注入进二进制的身份必须与 CHANGELOG 对账,且**开发构建不许自称正式版**。
# ⚠️ 不注入时这两条用例会 SKIP —— 那是"本地不想被迫先构建"的便利,但**CI 必须断言它们真的 PASS**
# (门禁的 contracts 项就是这么做的,并额外跑一条"自称正式版 ⇒ 必须红"的负例)。
version-contract:
$(GO) test -ldflags "-X knowledge-governance/internal/version.Number=$(VERSION)" \
-count=1 -run TestNumberMatchesChangelog -v ./internal/version/...
$(GO) test -ldflags "-X knowledge-governance/internal/version.Number=$(VERSION) \
-X knowledge-governance/internal/version.ReleaseVersion=$(RELEASE_VERSION) \
-X knowledge-governance/internal/version.BuildKind=$(BUILD_KIND) \
-X knowledge-governance/internal/version.CommitSHA=$(FULL_SHA)" \
-count=1 -run Test -v ./internal/version/...
# 构建镜像。三个 build-arg 必须显式传入 —— 不传就落成 dev/unknown(故意的:
# 构建镜像。build-arg 必须显式传入 —— 不传就落成 dev/unknown(故意的:
# 一个显眼的 dev 好过一个看起来正常的假版本号)。compose.yaml 的 args 透传见 PR TODO。
image:
docker build --build-arg VERSION=$(VERSION) --build-arg COMMIT_SHA=$(COMMIT_SHA) \
docker build --build-arg VERSION=$(VERSION) --build-arg RELEASE_VERSION=$(RELEASE_VERSION) \
--build-arg BUILD_KIND=$(BUILD_KIND) --build-arg COMMIT_SHA=$(COMMIT_SHA) \
--build-arg BUILD_TIME=$(BUILD_TIME) -t knowledge-governance-p1:$(VERSION)-$(COMMIT_SHA) .
+85 -17
View File
@@ -1,28 +1,96 @@
// Package version 承载"这个二进制是什么"的构建期身份。
//
// 三个值**全部由构建期注入**(正本 §6.1:版本号只有一个来源,且要能从产物读回来):
// 字段由构建期注入(正本 §6.1:版本号只有一个来源,且要能从产物读回来):
//
// go build -trimpath \
// -ldflags "-X knowledge-governance/internal/version.Number=$(python3 scripts/version.py) \
// -X knowledge-governance/internal/version.CommitSHA=$(git rev-parse --short=12 HEAD) \
// -X knowledge-governance/internal/version.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
// ./cmd/api
// VERSION=$(python3 scripts/version.py 2>/dev/null || echo dev)
// go build -trimpath -ldflags "\
// -X knowledge-governance/internal/version.Number=${VERSION} \
// -X knowledge-governance/internal/version.ReleaseVersion=<CHANGELOG 顶部已发布版本,没有就空> \
// -X knowledge-governance/internal/version.BuildKind=development|release \
// -X knowledge-governance/internal/version.CommitSHA=$(git rev-parse HEAD) \
// -X knowledge-governance/internal/version.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" ./cmd/api
//
// 三条纪律:
// 四条纪律:
//
// 1. **不要**把它们改成编译期常量,也**不要**另建仓库根的 VERSION 文件 ——
// 版本号的唯一来源是 CHANGELOG.md,由 scripts/version.py 解析。
// 放第二份副本的结果是发版要改两处,忘一处就漂移。
// 2. **不要**给这些变量设"看起来正常的默认值"。未注入时保持下面的零值,
// 2. **不要**给这些变量设"看起来正常的默认值"。未注入时保持零值,
// 好让"忘了注入"表现成一个显眼的 dev,而不是一个假的正经版本号。
// 3. `Number` 的正确性由 internal/version 的契约测试兜底:注入进去的号
// 必须等于 CHANGELOG.md 顶部的已发布版本(CI 会带 -ldflags 跑它,
// 并额外断言"没有 SKIP" —— 被跳过的断言等于没有断言)。
// 3. **开发构建不许自称正式版**:`BuildKind` 只能来自显式的发布上下文
// (`BUILD_KIND=release`);普通 main CI 永远是 development,
// DisplayVersion() 必须带 `-dev+g<短SHA>`,**不允许只显示上一正式版本号**。
// 4. 契约由本包的测试兜底:发布构建的 ReleaseVersion 必须等于 CHANGELOG.md 顶部的
// 已发布版本,开发构建必须是 dev 形状;CI 带 -ldflags 跑它并断言**没有 SKIP**
// (被跳过的断言等于没有断言)。
package version
// Number / CommitSHA / BuildTime 由 -ldflags -X 注入;未注入时保持下面的值。
var (
Number = "dev"
CommitSHA = "unknown"
BuildTime = "unknown"
import (
"fmt"
"regexp"
)
// Number / ReleaseVersion / BuildKind / CommitSHA / BuildTime 由 -ldflags -X 注入;
// 未注入时保持下面的值。
var (
Number = "dev" // 已发布版本号或 dev(= ReleaseVersion,或 dev)
ReleaseVersion = "" // 正式版本基线;还没有正式发布过 ⇒ 空
BuildKind = "development" // development | release
CommitSHA = "unknown" // 完整 40 位提交 SHA
BuildTime = "unknown" // 构建时间(built_at)
)
var (
fullSHA = regexp.MustCompile(`^[0-9a-f]{40}$`)
semver = regexp.MustCompile(`^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$`)
)
// IsRelease 只在**显式声明**且确实有正式版本基线时为真。
func IsRelease() bool { return BuildKind == "release" && semver.MatchString(ReleaseVersion) }
// ShortSHA 返回 12 位短 SHA;没有注入有效 SHA 时返回空串。
func ShortSHA() string {
if !fullSHA.MatchString(CommitSHA) {
return ""
}
return CommitSHA[:12]
}
// DisplayVersion 是**用户可见标识**,规则与 scripts/version.py 一致:
//
// 发布构建 → 0.1.0
// 开发构建(有基线) → 0.1.0-dev+g<短SHA>
// 开发构建(无基线) → dev+g<短SHA>
// 什么都拿不到 → dev
//
// ⚠️ 开发构建**不会**退化成"只显示上一正式版本号"——那正是要修的问题。
func DisplayVersion() string {
if IsRelease() {
return ReleaseVersion
}
short := ShortSHA()
switch {
case ReleaseVersion != "" && short != "":
return ReleaseVersion + "-dev+g" + short
case ReleaseVersion != "":
return ReleaseVersion + "-dev"
case short != "":
return "dev+g" + short
default:
return "dev"
}
}
// Info 是给人看的一行摘要(不含密钥,可安全打印进日志)。
func Info() string {
sha := CommitSHA
if len(sha) > 12 {
sha = sha[:12]
}
return fmt.Sprintf("%s(%s,提交 %s,构建于 %s)", DisplayVersion(), BuildKind, sha, BuildTime)
}
// HasInjection 判断构建期是否真的注入了身份:未注入时契约测试应当 Skip,
// 而 CI 必须断言它**没有** Skip。
func HasInjection() bool {
return !(Number == "dev" && ReleaseVersion == "" && CommitSHA == "unknown")
}
+80 -20
View File
@@ -4,23 +4,13 @@ import (
"os"
"path/filepath"
"regexp"
"strings"
"testing"
)
// 版本契约:注入进二进制的号,必须等于仓库根 CHANGELOG.md 顶部的已发布版本。
//
// 为什么要有这条断言:CHANGELOG.md 是版本号的**唯一来源**,而注入是构建期动作。
// 两者只要没人对账,就会出现"改了 CHANGELOG 没重新构建"(产物报旧号)或
// "构建时手填了一个号"(产物报的号 CHANGELOG 里根本没有)—— 两种都让
// "线上跑的是哪个提交/版本"这个问题失去答案,而症状是静默的。
//
// 未注入时(普通 `go test ./...`)本用例 Skip:本地跑全量测试不必先构建。
// 但 CI 必须带 -ldflags 跑它,**并断言没有 SKIP**(.gitea/workflows/build.yml
// 的「版本与变更记录契约」步;被跳过的断言等于没有断言)。
func TestNumberMatchesChangelog(t *testing.T) {
if Number == "dev" {
t.Skip("版本号未注入(没有 -ldflags);CI 会注入后跑这条断言")
}
// changelogTopVersion 返回仓库根 CHANGELOG.md 顶部的已发布版本号;还没有正式版本时返回 ""。
func changelogTopVersion(t *testing.T) string {
t.Helper()
path := filepath.Join("..", "..", "CHANGELOG.md")
raw, err := os.ReadFile(path)
if err != nil {
@@ -28,13 +18,83 @@ func TestNumberMatchesChangelog(t *testing.T) {
}
m := regexp.MustCompile(`(?m)^##\s*\[(\d+\.\d+\.\d+)\]`).FindSubmatch(raw)
if m == nil {
t.Fatalf("%s 里没有已发布版本条目(形如 `## [0.1.0] - 2026-01-01`);"+
"没有条目就没有版本号,不该回落到一个假版本", path)
return ""
}
want := string(m[1])
if Number != want {
t.Fatalf("注入的版本 %q != CHANGELOG 顶部 %q。"+
return string(m[1])
}
// 版本契约:注入进二进制的**正式版本基线**,必须等于仓库根 CHANGELOG.md 顶部的已发布版本。
//
// 为什么要有这条断言:CHANGELOG.md 是版本号的**唯一来源**,而注入是构建期动作。
// 两者只要没人对账,就会出现"改了 CHANGELOG 没重新构建"(产物报旧号)或
// "构建时手填了一个号"(产物报的号 CHANGELOG 里根本没有)—— 两种都让
// "线上跑的是哪个提交/版本"这个问题失去答案,而症状是静默的。
//
// ⚠️ "还没有正式版本"不等于出错:那时 ReleaseVersion 必须是空,**不许**编一个基线出来。
//
// 未注入时(普通 `go test ./...`)本用例 Skip:本地跑全量测试不必先构建。
// 但 CI 必须带 -ldflags 跑它,**并断言没有 SKIP**(被跳过的断言等于没有断言)。
func TestNumberMatchesChangelog(t *testing.T) {
if !HasInjection() {
t.Skip("构建身份未注入(没有 -ldflags);CI 会注入后跑这条断言,并断言它没有 Skip")
}
want := changelogTopVersion(t)
if want == "" {
if ReleaseVersion != "" {
t.Fatalf("CHANGELOG.md 里还没有已发布版本,ReleaseVersion 却是 %q —— 不许编一个版本基线出来", ReleaseVersion)
}
} else if ReleaseVersion != want {
t.Fatalf("注入的 ReleaseVersion %q != CHANGELOG 顶部 %q。"+
"常见原因:改了 CHANGELOG 却没重新构建(产物还报旧号),"+
"或者构建时手填了一个 CHANGELOG 里没有的号", Number, want)
"或者构建时手填了一个 CHANGELOG 里没有的号", ReleaseVersion, want)
}
if Number != ReleaseVersion && Number != "dev" {
t.Fatalf("Number %q 既不是 ReleaseVersion %q 也不是 dev —— 注入口径不一致", Number, ReleaseVersion)
}
}
// 开发构建不许自称正式版:这是"用正式版号代表开发版"那个问题的守门断言。
//
// - `BuildKind=release` 只允许出现在**确实有正式版本基线**的构建上,且显示就是那个版本;
// - 开发构建的 DisplayVersion 必须带 `dev` 形状,**不允许**退化成只显示上一正式版本号。
func TestDevBuildDoesNotClaimRelease(t *testing.T) {
if !HasInjection() {
t.Skip("构建身份未注入(没有 -ldflags);CI 会带 -ldflags 跑它,并断言它没有 Skip")
}
want := changelogTopVersion(t)
disp := DisplayVersion()
if BuildKind == "release" {
if want == "" {
t.Fatalf("标成了发布构建(BuildKind=release),但 CHANGELOG.md 里没有任何已发布版本条目 —— "+
"发布构建必须基于正式版本记录(现在显示 %q)", disp)
}
if ReleaseVersion != want || !semver.MatchString(ReleaseVersion) {
t.Fatalf("发布构建的 ReleaseVersion %q 不是 CHANGELOG 顶部的正式版本 %q", ReleaseVersion, want)
}
if disp != ReleaseVersion {
t.Fatalf("发布构建 DisplayVersion %q 应等于 ReleaseVersion %q", disp, ReleaseVersion)
}
return
}
if BuildKind != "development" {
t.Fatalf("BuildKind %q 既不是 development 也不是 release", BuildKind)
}
if !strings.Contains(disp, "dev") {
t.Fatalf("开发构建的 DisplayVersion %q 没有 dev 标识 —— 开发构建不能只显示正式版本号", disp)
}
if strings.Contains(disp, "+g") && ShortSHA() == "" {
t.Fatalf("DisplayVersion %q 带了 +g 但 CommitSHA %q 不是有效 SHA", disp, CommitSHA)
}
switch {
case want != "" && ShortSHA() != "":
if want := want + "-dev+g" + ShortSHA(); disp != want {
t.Fatalf("开发构建 DisplayVersion %q,期望 %q", disp, want)
}
case want == "" && ShortSHA() != "":
if want := "dev+g" + ShortSHA(); disp != want {
t.Fatalf("无正式基线的开发构建 DisplayVersion %q,期望 %q", disp, want)
}
}
}
+75 -32
View File
@@ -37,7 +37,7 @@ from typing import Callable
ROOT = Path(__file__).resolve().parent.parent
WEB = ROOT / "web"
REPORT_DEFAULT = ROOT / "ci-report.json"
POLICY_REVISION = "ci-checks/2" # 判据变更时改这里,报告里跟着变
POLICY_REVISION = "ci-checks/3" # 判据变更时改这里,报告里跟着变
MANIFESTS = ["go.mod", "go.sum", "web/package.json", "web/package-lock.json"]
SUCCESS, FAILURE, SKIPPED, NOT_RUN = "success", "failure", "skipped", "not_run"
@@ -249,9 +249,9 @@ def checks() -> list[Check]:
[g, "test", "-count=1", "-json", "./..."], env=env, judge=judge_go_tests),
Check("tests-web", "前端测试(vitest,必须真跑)",
[py3, "scripts/ci_checks.py", "--internal-web-test"], env=env),
Check("contracts", "版本与变更记录契约(不许 SKIP 后算过)",
Check("contracts", "版本与变更记录契约(不许 SKIP;开发构建不许自称正式版)",
[py3, "scripts/ci_checks.py", "--internal-contracts", g], env=env),
Check("version", "CHANGELOG 与版本记录(四节齐备 + 正式 tag 与提交内版本一致)",
Check("version", "CHANGELOG 与版本记录(四类小节无空栏目 + 正式 tag 与提交内版本一致)",
[py3, "scripts/check_changelog.py", "--tags"]),
Check("security-secrets", "密钥泄漏扫描(含扫描器自检)",
[py3, "scripts/check_secrets.py"]),
@@ -287,22 +287,47 @@ def cmd_internal_deps(out_dir: str) -> int:
return 0
def build_identity() -> tuple[dict | None, str]:
"""构建身份(`scripts/version.py --identity`)。
⚠️ 刻意**不**跑裸的 `scripts/version.py`:那个在"还没有正式版本"时会非 0 退出,
而开发构建**必须**能正常产出身份(release_version=null / display_version=dev+g<短SHA>)。
"""
p = subprocess.run(py("scripts/version.py", "--identity"), cwd=ROOT, capture_output=True, text=True)
if p.returncode:
return None, ((p.stderr or p.stdout).strip().splitlines() or [f"退出码 {p.returncode}"])[0][:400]
try:
return json.loads(p.stdout), ""
except ValueError as e:
return None, f"--identity 的输出不是 JSON:{e}"
def ldflags_for(ident: dict, *, build_kind: str | None = None,
release_version: str | None = None) -> str:
"""把构建身份编成 -ldflags(负例可以覆盖 kind / release_version)。"""
kind = build_kind or str(ident.get("build_kind") or "development")
rel = ident.get("release_version") if release_version is None else release_version
return " ".join([
f"-X knowledge-governance/internal/version.Number={rel or 'dev'}",
f"-X knowledge-governance/internal/version.ReleaseVersion={rel or ''}",
f"-X knowledge-governance/internal/version.BuildKind={kind}",
f"-X knowledge-governance/internal/version.CommitSHA={ident.get('commit_sha') or 'unknown'}",
f"-X knowledge-governance/internal/version.BuildTime={ident.get('built_at') or 'unknown'}",
])
def cmd_internal_build(out_dir: str) -> int:
out = Path(out_dir)
out.mkdir(parents=True, exist_ok=True)
version = subprocess.run(py("scripts/version.py"), cwd=ROOT, capture_output=True,
text=True).stdout.strip() or "dev"
sha = subprocess.run(["git", "rev-parse", "--short=12", "HEAD"], cwd=ROOT,
capture_output=True, text=True).stdout.strip() or "unknown"
ts = dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
ldflags = " ".join([
f"-X knowledge-governance/internal/version.Number={version}",
f"-X knowledge-governance/internal/version.CommitSHA={sha}",
f"-X knowledge-governance/internal/version.BuildTime={ts}",
])
ident, err = build_identity()
if ident is None:
print(f"❌ 拿不到构建身份:{err}", file=sys.stderr)
return 1
ldflags = ldflags_for(ident)
p = subprocess.run([go_bin(), "build", "-trimpath", "-ldflags", ldflags, "-o", f"{out}/", "./cmd/..."],
cwd=ROOT, env=go_env(), capture_output=True, text=True)
print(f"-- go build(版本 {version} / 提交 {sha})--")
print(f"-- go build(显示版本 {ident['display_version']}|{ident['build_kind']}|"
f"提交 {str(ident['commit_sha'])[:12]})--")
print(p.stdout[-2000:] if p.stdout else "", end="")
if p.returncode:
print(f"❌ 构建失败:{(p.stderr or '')[:2000]}", file=sys.stderr)
@@ -327,31 +352,49 @@ def cmd_internal_web_test() -> int:
def cmd_internal_contracts(go: str) -> int:
"""版本契约:注入进二进制的号必须等于 CHANGELOG 顶部,而且**必须真的 PASS**。"""
"""版本契约:结构 + 注入身份必须**真 PASS**(SKIP 判红),
并且**开发构建不许自称正式版**(负例:标成 release ⇒ 必须红)。"""
rc = subprocess.run(py("scripts/check_changelog.py"), cwd=ROOT).returncode
if rc:
return 1
v = subprocess.run(py("scripts/version.py"), cwd=ROOT, capture_output=True, text=True)
version = v.stdout.strip()
if v.returncode or not version:
print("❌ CHANGELOG 顶部解析不到版本号:没有条目就没有版本号,不许回落成假版本", file=sys.stderr)
ident, err = build_identity()
if ident is None:
print(f"❌ 拿不到构建身份:{err}", file=sys.stderr)
return 1
print(f"-- 版本契约:CHANGELOG 顶部 = {version} --")
p = subprocess.run([go, "test", f"-ldflags=-X knowledge-governance/internal/version.Number={version}",
"-count=1", "-run", "TestNumberMatchesChangelog", "-v", "-json",
"./internal/version/..."],
cwd=ROOT, env=go_env(), capture_output=True, text=True)
text = p.stdout + p.stderr
print(text[-3000:], end="")
print(f"-- 版本契约:显示版本 {ident['display_version']}({ident['build_kind']}"
f"|release_version={ident['release_version']!r})--")
tests = ("TestNumberMatchesChangelog", "TestDevBuildDoesNotClaimRelease")
def run(ld: str) -> tuple[int, str]:
p = subprocess.run([go, "test", f"-ldflags={ld}", "-count=1", "-run", "Test", "-v", "-json",
"./internal/version/..."], cwd=ROOT, env=go_env(),
capture_output=True, text=True)
return p.returncode, (p.stdout + p.stderr).replace("\\n", "\n")
rc1, text = run(ldflags_for(ident))
print(text[-2000:], end="")
# ⚠️ 被跳过的断言等于没有断言:必须看到 PASS,SKIP 一律判红。
# 用 in 而不是 `| grep -q`:pipefail 下 grep -q 会因 SIGPIPE 谎报失败(trap-7)。
if '--- PASS: TestNumberMatchesChangelog' not in text.replace("\\n", "\n"):
print("❌ 版本契约没有真正 PASS(被 SKIP 或没跑到)—— 缺 -ldflags,或 CHANGELOG 解析失败", file=sys.stderr)
for name in tests:
if f"--- PASS: {name}" not in text:
print(f"❌ 版本契约 {name} 没有真正 PASS(被 SKIP 或没跑到)—— "
f"缺 -ldflags,或 CHANGELOG / 构建身份有问题", file=sys.stderr)
return 1
if f"--- SKIP: {name}" in text:
print(f"❌ 版本契约 {name} 被跳过(构建身份没注入)—— 跳过不算通过", file=sys.stderr)
return 1
# 负例:把开发构建标成正式版(ReleaseVersion 指向 CHANGELOG 里没有的号)⇒ **必须红**。
# 没有这条,"开发版沿用正式版号"这个病会静默回归。
bogus = "9.9.9" if ident.get("release_version") != "9.9.9" else "8.8.8"
rc2, _ = run(ldflags_for(ident, build_kind="release", release_version=bogus))
if rc2 == 0:
print(f"❌ 把构建标成正式版(BuildKind=release / ReleaseVersion={bogus})竟然还是绿的 —— "
f"这条断言是死的", file=sys.stderr)
return 1
if "--- SKIP: TestNumberMatchesChangelog" in text:
print("❌ 版本契约被跳过(未注入版本号)—— 跳过不算通过", file=sys.stderr)
return 1
print("✅ 版本契约成立:注入 == CHANGELOG 顶部,且断言真的执行了")
print(f"-- 负例确认:自称正式版({bogus})⇒ 红 ✓ --")
print("✅ 版本契约成立:注入 == CHANGELOG 顶部(没有正式版本时为空),"
"开发构建带 dev 标识,且断言真的执行了")
return 0
+6 -1
View File
@@ -43,6 +43,11 @@
"package": "knowledge-governance/internal/version",
"test": "TestNumberMatchesChangelog",
"reason": "未注入版本号时按设计 SKIP(本地跑全量测试不该被迫先构建);**它的强制点在 contracts 项**:那里带 -ldflags 跑它并断言真的 PASS、且出现 SKIP 就判红"
},
{
"package": "knowledge-governance/internal/version",
"test": "TestDevBuildDoesNotClaimRelease",
"reason": "构建身份未注入时按设计 SKIP(本地跑全量测试不该被迫先构建);**它的强制点在 contracts 项**:那里带 -ldflags 跑它并断言真的 PASS、且出现 SKIP 就判红"
}
]
}
}
+71 -10
View File
@@ -1,22 +1,35 @@
#!/usr/bin/env python3
"""打印版本号 —— 唯一来源是仓库根的 CHANGELOG.md。
"""版本与构建身份 —— 版本号的唯一来源是仓库根的 CHANGELOG.md。
为什么是它而不是 git tag:CI 检出是 `git fetch --depth 50`,**取不到 tag**,
`git describe --tags` 会失败或者给出误导性的结果。仓库里的文件则一定在。
为什么是它而不是 git tag:**日常检出不做 `git describe`**(CI 检出是 `git fetch --depth 50`,
`git describe --tags` 会失败或给出误导结果)。正式 tag 的**创建**是人工批准的发布动作,
CI 只做**核验**(tag 版本 == 它指到那个提交里的版本记录),见 `check_changelog.py --tags`。
仓库里的文件则一定在。
为什么不是另放一个 `VERSION` 文件:那是第二份副本,发版要改两处,忘一处就漂移
(正本 §3.1)。CHANGELOG.md 里本来就必须写版本号,让它当源头,副本数为一。
为什么不是另放一个 `VERSION` 文件:那是第二份副本,发版要改两处,忘一处就漂移。
用法:
python3 scripts/version.py # 打印版本号;解析不到就以非 0 退出
python3 scripts/version.py --check # 同时跑结构自检(等价 check-changelog.py)
python3 scripts/version.py # 打印顶部「已发布」版本号;没有就非 0 退出
python3 scripts/version.py --identity # 打印构建身份 JSON(**开发构建也能用**)
python3 scripts/version.py --identity --release # 声明发布构建;没有已发布版本 ⇒ 拒绝(rc=2)
python3 scripts/version.py --check # 打印版本号并跑结构自检(等价 check-changelog.py)
退出码非 0 表示"CHANGELOG 里没有已发布版本条目" —— 构建应当据此失败,
而不是回落成一个看起来正常的假版本号。
构建身份字段(`--identity`):
release_version 正式版本基线;本仓还没有正式发布过 ⇒ `null`
build_kind development | release(**只有显式声明**才是 release,普通 main CI 永远不是)
commit_sha 完整 40 位提交 SHA(取不到 ⇒ `unknown`)
display_version 用户可见标识:`X.Y.Z` / `X.Y.Z-dev+g<短SHA>` / `dev+g<短SHA>` / `dev`
built_at 构建时间(`BUILT_AT` 环境变量,缺省取当前 UTC)
⚠️ 开发构建**不能**只显示上一正式版本号(那正是要修的问题),也不许自称正式版。
"""
from __future__ import annotations
import datetime as dt
import json
import os
import re
import subprocess
import sys
from pathlib import Path
@@ -25,6 +38,8 @@ CHANGELOG = ROOT / "CHANGELOG.md"
# 已发布版本标题:`## [0.1.0] - 2026-10-10` / `## [0.1.0]`;`## [Unreleased]` 不算
RELEASE_HEADING = re.compile(r"^##\s*\[(\d+\.\d+\.\d+)\]", re.MULTILINE)
SEMVER = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$")
FULL_SHA = re.compile(r"^[0-9a-f]{40}$")
def current_version(path: Path = CHANGELOG) -> str | None:
@@ -35,12 +50,58 @@ def current_version(path: Path = CHANGELOG) -> str | None:
return m.group(1) if m else None
def git_sha(root: Path = ROOT) -> str:
p = subprocess.run(["git", "rev-parse", "HEAD"], cwd=root, capture_output=True, text=True)
s = p.stdout.strip()
return s if FULL_SHA.match(s) else "unknown"
def display_version(release_version: str | None, kind: str, sha: str) -> str:
short = sha[:12] if FULL_SHA.match(sha) else ""
if kind == "release" and release_version:
return release_version
if release_version and short:
return f"{release_version}-dev+g{short}"
if release_version:
return f"{release_version}-dev"
return f"dev+g{short}" if short else "dev"
def identity(*, release: bool = False, built_at: str | None = None,
root: Path = ROOT, sha: str | None = None) -> dict:
"""构建身份。`release=True` 但没有已发布版本 ⇒ 由调用方拒绝(见 main)。"""
rel = current_version(root / "CHANGELOG.md")
sha = sha if sha is not None else git_sha(root)
kind = "release" if (release and rel) else "development"
return {
"release_version": rel,
"build_kind": kind,
"commit_sha": sha,
"display_version": display_version(rel, kind, sha),
"built_at": built_at or os.environ.get("BUILT_AT") or os.environ.get("BUILD_TIME")
or dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
}
def main(argv: list[str]) -> int:
release = "--release" in argv or os.environ.get("BUILD_KIND") == "release"
if "--identity" in argv:
if release and current_version() is None:
print("❌ 声明了发布构建(--release / BUILD_KIND=release),但 CHANGELOG.md 里没有已发布版本条目。\n"
" 发布构建必须基于一个已发布的版本记录(`## [x.y.z] - YYYY-MM-DD`)——\n"
" 本仓还没有正式发布过,所以现在只能产出开发构建身份(dev+g<短SHA>)。",
file=sys.stderr)
return 2
print(json.dumps(identity(release=release), ensure_ascii=False, indent=2))
return 0
v = current_version()
if v is None:
print(
"❌ CHANGELOG.md 里找不到已发布版本条目(形如 `## [0.1.0] - 2026-10-10`)。\n"
" 版本号解析不到 ⇒ 构建应当失败,而不是回落成假版本号。",
" 本仓还没有正式发布过 ⇒ 没有正式版本号可用。\n"
" 要构建身份(开发构建也能用)请跑 `python3 scripts/version.py --identity`;\n"
" 发布构建必须先在 CHANGELOG.md 写下正式版本条目。",
file=sys.stderr,
)
return 1