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:
+7
-3
@@ -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 \
|
||||
|
||||
@@ -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
@@ -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")
|
||||
}
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user