Files
knowledge-governance/CHANGELOG.md
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

3.7 KiB
Raw Blame History

变更记录

这个文件就是版本号的唯一来源。 正本 §3.1 要求"版本号只有一个来源",所以这里不放 VERSION 文件, 也不靠 git tag(CI 是 git fetch --depth 50,取不到 tag ⇒ git describe 会失败)。

用法与断言(都可复现,别手抄版本号):

python3 scripts/version.py            # 打印顶部那个「已发布」版本号
python3 scripts/check-changelog.py    # 结构自检:每个版本都要有「改了什么」「怎么验收」

构建时用 -ldflags "-X knowledge-governance/internal/version.Number=<号>" 注入, CI 断言"二进制报出的版本 == 本文件顶部"。没有条目 ⇒ 解析失败 ⇒ 构建红, 所以"忘了记变更"这件事过不去。

每个已发布版本必须有两节:### 改了什么 与 ### 怎么验收。 缺任一节 check-changelog.py 报红(CI 会跑它)。

纪律:最新版本在最上面;版本号只增不减(回退走部署层,不改这个文件); 日期写 YYYY-MM-DD;## [Unreleased] 段可以只有「改了什么」。

[Unreleased]

改了什么

  • 待合并:PR #2 —— 批量发布 / 建批即锁定 / 需下架逐条移除 / 数据源勾选改造(23 个提交,80 个文件)
  • 待合并:仓库卫生 —— 撤出误入库的 node_modules/.vite/.../results.json 与 8 个历史 scripts/__pycache__/*.pyc

[0.1.0] - 2026-10-10

改了什么

初始基线(补记):本仓此前既没有版本号、也没有变更记录,本次首次建立。 下面按已上线能力归纳,不逐条追溯历史提交。

  • 来源与目录:列出可选的钉钉知识库 → 勾选 → 变成来源;快照与变更集
  • 发布管理:计划 → 建批 → 锁定 → 授权发布(落 WeKnora 生产)
  • 监控 + 需下架车道:测试库知识逐条下架
  • 钉钉侧:知识库发现 / 注册、取件走 dws;登录与系统设置
  • 运行形态:knowledge-governance-p1-* —— api / web / worker / release-worker / dingtalk-login / postgres 共 6 个容器;web 发布在 :8088

怎么验收

冒烟(约 2 分钟;下面每条都是本机运行栈的实测结果,不是设计意图)

# 1) 容器都在(期望 6 个:api / web / worker / release-worker / dingtalk-login / postgres)
docker ps --format '{{.Names}}' | grep knowledge-governance-p1-

# 2) 存活与就绪(web 的 nginx 反代 /health 与 /api/ 到 api 容器)
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8088/health   # 期望 200
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8088/livez    # 期望 200
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8088/readyz   # 期望 200
curl -fsS http://127.0.0.1:8088/readyz | head -c 400                       # 期望 postgres / queue 非 blocked

# 3) 控制台能打开
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8088/          # 期望 200

# 4) api 容器自带 healthcheck 的状态
docker inspect knowledge-governance-p1-api-1 --format '{{.State.Health.Status}}'   # 期望 healthy

业务流程(逐条走,每条都写了"操作 → 期望现象")

  • docs/USER_FLOWS_ACCEPTANCE.md —— C1 ~ C9
  • docs/OPERATIONS_RUNBOOK.md —— 现行用户操作流程与运维步骤

⚠️ 冒烟通过 ≠ 验收通过。面向上线的那一次验收必须走完 C1~C9,由人确认并留下记录; "服务健康"只是可继续验收的前提,不是验收本身。

⚠️ 上面的端口(8088)与容器名前缀(knowledge-governance-p1-)是本机运行栈的实测值; 换环境(测试机 / 生产)要按那边的运行栈改,别无脑照抄。