Files
knowledge-governance/internal/version/version.go
T
姚章浩 05144309c3 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。
2026-10-13 14:59:36 +08:00

97 lines
3.8 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 承载"这个二进制是什么"的构建期身份。
//
// 字段由构建期注入(正本 §6.1:版本号只有一个来源,且要能从产物读回来):
//
// 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. **不要**给这些变量设"看起来正常的默认值"。未注入时保持零值,
// 好让"忘了注入"表现成一个显眼的 dev,而不是一个假的正经版本号。
// 3. **开发构建不许自称正式版**:`BuildKind` 只能来自显式的发布上下文
// (`BUILD_KIND=release`);普通 main CI 永远是 development,
// DisplayVersion() 必须带 `-dev+g<短SHA>`,**不允许只显示上一正式版本号**。
// 4. 契约由本包的测试兜底:发布构建的 ReleaseVersion 必须等于 CHANGELOG.md 顶部的
// 已发布版本,开发构建必须是 dev 形状;CI 带 -ldflags 跑它并断言**没有 SKIP**
// (被跳过的断言等于没有断言)。
package version
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")
}