From b8596041d78a75dabae47c0c8746b18753380292 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Mon, 10 Aug 2026 16:37:21 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=8F=91=E5=B8=83=E9=97=A8=E7=A6=81?= =?UTF-8?q?=E7=A1=AC=E8=A7=84=E5=88=99=E2=80=94=E2=80=94=E7=BB=99=E5=89=8D?= =?UTF-8?q?=E7=AB=AF=E6=8E=A8=E9=80=81=E7=9A=84=E5=BF=85=E9=A1=BB=E6=98=AF?= =?UTF-8?q?=E6=B5=8B=E8=AF=95=E7=8E=AF=E5=A2=83=E5=B7=B2=E5=AD=98=E5=9C=A8?= =?UTF-8?q?=E5=8F=AF=E5=AE=9E=E6=B5=8B=E7=9A=84+pre-push=20=E9=92=A9?= =?UTF-8?q?=E5=AD=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - guide §2.1: 接口类条目推送前必须走完 PR 合并→部署测试服→测试服真实 API 验证,backend_status=deployed 才许 push;预告式推送一律禁止(2026-08-10 wx 定,前端投诉实证 #5599/#5567/#5633) - .githooks/pre-push: push 前自动跑文件名+frontmatter 校验,违规拦截;启用 git config core.hooksPath .githooks - 文件名类型枚举文档同步(7 类+frontend 字面量) Co-Authored-By: Claude Fable 5 --- .githooks/pre-push | 25 +++++++++++++++++++++++++ BACKEND_CHANGELOG_DELIVERY_GUIDE.md | 19 ++++++++++++++++++- 2 files changed, 43 insertions(+), 1 deletion(-) create mode 100644 .githooks/pre-push diff --git a/.githooks/pre-push b/.githooks/pre-push new file mode 100644 index 0000000..b719d0b --- /dev/null +++ b/.githooks/pre-push @@ -0,0 +1,25 @@ +#!/bin/sh +# changelog 发布门禁(推送前强制校验) +# 启用(每台机一次): git config core.hooksPath .githooks +# 拦截目标: 接口类 changelog 未部署测试服(backend_status != deployed)就推送给前端, +# 以及文件名/frontmatter 结构违规。规则实现见 scripts/validate-changelog-*.mjs。 +zero=0000000000000000000000000000000000000000 +status=0 +while read local_ref local_sha remote_ref remote_sha; do + # 删除远端分支的推送没有本地内容可校验 + [ "$local_sha" = "$zero" ] && continue + if [ "$remote_sha" = "$zero" ]; then + base=$(git rev-parse --verify origin/main 2>/dev/null) || continue + else + base=$remote_sha + fi + [ "$base" = "$local_sha" ] && continue + node scripts/validate-changelog-filenames.mjs --base "$base" --head "$local_sha" || status=1 + node scripts/validate-changelog-frontmatter.mjs --base "$base" --head "$local_sha" || status=1 +done +if [ "$status" -ne 0 ]; then + echo "" >&2 + echo "推送被 changelog 发布门禁拦截:接口类条目必须测试服已部署+实测(backend_status=deployed)后才能推送给前端。" >&2 + echo "修正文件后重试;规则详见 BACKEND_CHANGELOG_DELIVERY_GUIDE.md §2.1。" >&2 +fi +exit $status diff --git a/BACKEND_CHANGELOG_DELIVERY_GUIDE.md b/BACKEND_CHANGELOG_DELIVERY_GUIDE.md index ced468b..1fdf713 100644 --- a/BACKEND_CHANGELOG_DELIVERY_GUIDE.md +++ b/BACKEND_CHANGELOG_DELIVERY_GUIDE.md @@ -10,9 +10,11 @@ 文件名： ```text -DD_issue_业务标题-{新增接口|修改接口|删除接口}-{管理后台|小程序端}.md +DD_issue_业务标题-{新增接口|修改接口|删除接口|修复|前端缺陷|前端优化|前端修复}-{管理后台|小程序端}.md ``` +纯前端条目（无后端工单）issue 段写字面量 `frontend`，如 `10_frontend_标题-前端缺陷-管理后台.md`。 + 例如： ```text @@ -48,6 +50,21 @@ verified_at: "" - 不需要前端修改：`frontend_status: "not_required"` - 后端不要代替前端填写 `implemented`、`released` 或 `verified` +## 2.1 发布门禁（硬规则，2026-08-10 wx 定） + +**给前端推送的 changelog，内容必须是测试环境已经存在、可实测到的。** + +- 接口类条目（新增接口/修改接口/删除接口）：推送前必须走完「PR 合并 → 部署测试服 → 测试服真实 API 验证」，frontmatter 必须 `backend_status: "deployed"`，并在正文「验证证据」章节贴实测结果。 +- `backend_status` 为 `merged` / `pending` / `implemented` 等未部署状态的条目**禁止 push**（校验规则 E_BACKEND_PENDING 会拦）。「先给前端契约、部署随后」的预告式推送一律禁止——前端拿到 changelog 会立刻联调，接口不在等于空耗与误判。 +- 纯前端条目（前端缺陷/前端优化/前端修复）：`backend_status: "not_required"`，change_type 用对应前端类型；`frontend_status: "not_required"` 时不得残留 frontend_owner / frontend_ref / target_release / verified_at。 +- 背景：2026-08-06~08-07 三条未部署即推送的条目（#5599/#5567/#5633）导致前端在测试环境验不到字段（2026-08-10 投诉属实）；当时仓库 CI 因校验规则假阳性长期常红被忽略，规则已于 2026-08-10 修正（前端条目类型合法化、`{orderId}` 路径参数不再误判为占位符），此后 **CI 红 = 真违规，必须当场修复回填**。 + +**推送校验（强制）**： + +- 推荐一次性启用本地钩子，之后 push 自动拦截：`git config core.hooksPath .githooks` +- 未启用钩子则每次 push 前手动跑 §3 的两条校验命令，红了不许推。 +- 仓库 CI（changelog-filename-gate）对每次 push 复检；push 后请回看 Gitea Actions 状态，红 X 必须当场处理。 + ## 2.5 写作方法论（对齐 yst 团队 changelog-conventions SKILL，2026-08-04 起执行） **受众优先**：触达 `/admin/*` `/mp/*` `/v3/admin/*` `/v3/mp/*` 等对外前缀的改动**一律**写前端 changelog，哪怕"前端代码零改动"（前端 AI 可能有 workaround 需清理信号）。`/v3/internal/*` Feign 接口**必须拆出去**单独走后端 changelog，不许和 admin/mp 接口塞同一份（反例：# traveler 11 接口事故）。