Files
knowledge-governance/internal/version/version_test.go
T
姚章浩 5f3a71cade
build / build (push) Successful in 26s
feat(version): 版本号唯一来源 = CHANGELOG.md,并要求写清改了什么与怎么验收
背景:本仓此前没有任何版本/构建元信息 —— 没有 ldflags 注入、也没有产物可读的
版本号,"线上跑的是哪个提交"答不出来;"这次改了什么、怎么验收"也没有载体。

落地:
- CHANGELOG.md:**版本号的唯一来源**(正本 §6.1:版本号只准有一处)。刻意不放
  VERSION 文件、也不靠 git tag —— CI 是 `git fetch --depth 50`,取不到 tag,
  `git describe` 会静默退化。每个已发布版本必须有两节:### 改了什么 与 ### 怎么验收。
- scripts/version.py:从 CHANGELOG 顶部解析版本号;解析不到即非 0 退出(构建据此失败)。
- scripts/check_changelog.py:结构自检(两节齐、带日期、版本号不重复且严格递减、
  小节不为空),带 --self-test 反向自检。
- internal/version:三个构建期注入变量 + 契约测试(注入的号必须等于 CHANGELOG 顶部)。
- Makefile:build 带 -ldflags 注入;verify 增加 changelog-check 与 version-contract。
- Dockerfile:ARG VERSION/COMMIT_SHA/BUILD_TIME + ldflags(未透传时落 dev —— 故意显眼,
  好过看起来正常的假版本号)。
- CI:新增「版本与变更记录契约」步,并显式断言契约测试真的 PASS(被跳过的断言等于没有断言)。
- docs/提交规范.md(ci_gate.py 的报错文案一直在指它)、docs/agents/traps.md(7 条实测陷阱)。

验证(都真跑过):
- make version → 0.1.0;make changelog-check → 合规
- make version-contract → PASS;注入 9.9.9(CHANGELOG 里没有)→ FAIL(反向自检)
- 删掉真实 CHANGELOG 的「怎么验收」小节 → 报红(对真实文件做,不只是夹具)
- go build ./... 与 go vet ./internal/version/... 通过

未做(会与在审 PR #2 冲突,待其合并后在 main 上补):
- GET /version 端点(internal/httpapi/server.go)与 cmd/api 的 -version 开关
- compose.yaml 透传 build args(当前由 compose 构建的镜像会报 dev)

⚠️ 未跑 make verify 全量(含 go test ./... 与前端),CI 是本次的测试证据。
2026-10-10 18:13:24 +08:00

40 lines
1.7 KiB
Go
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.
package version
import (
"os"
"path/filepath"
"regexp"
"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 会注入后跑这条断言")
}
path := filepath.Join("..", "..", "CHANGELOG.md")
raw, err := os.ReadFile(path)
if err != nil {
t.Fatalf("读不到 %s:%v(版本号的唯一来源就在这里)", path, err)
}
m := regexp.MustCompile(`(?m)^##\s*\[(\d+\.\d+\.\d+)\]`).FindSubmatch(raw)
if m == nil {
t.Fatalf("%s 里没有已发布版本条目(形如 `## [0.1.0] - 2026-01-01`);"+
"没有条目就没有版本号,不该回落到一个假版本", path)
}
want := string(m[1])
if Number != want {
t.Fatalf("注入的版本 %q != CHANGELOG 顶部 %q。"+
"常见原因:改了 CHANGELOG 却没重新构建(产物还报旧号),"+
"或者构建时手填了一个 CHANGELOG 里没有的号", Number, want)
}
}