05144309c3
解决"开发构建沿用已发布版本号,分不清开发版与正式版": - 新增 `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。
97 lines
3.8 KiB
Go
97 lines
3.8 KiB
Go
// 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")
|
||
}
|