hl-api-changelog/CONTRIBUTING.md

Changelog 贡献规则

二期文件名

/v3/admin/* 接口写入 changelogs-v2/：

changelogs-v2/YYYY-MM/DD_issue_业务标题-{新增接口|修改接口|删除接口}-管理后台.md

/v3/mp/* 接口写入 changelogs-v2-mp/：

changelogs-v2-mp/YYYY-MM/DD_issue_业务标题-{新增接口|修改接口|删除接口}-小程序端.md

其中：

• YYYY-MM 和 DD 必须是校验运行时 Asia/Shanghai 的真实年月日，且均须补齐两位。跨越上海零点后仍未合并的 PR，需要把新文件重命名为当天日期。
• issue 必须是不带 # 的十进制正整数，不允许 0、负数或前缀符号。
• 业务标题不能为空。
• 变更类型只能是 新增接口、修改接口 或 删除接口。
• 端类型由目录唯一决定：changelogs-v2/ 固定为 管理后台，changelogs-v2-mp/ 固定为 小程序端。
• 同一改动同时影响 /v3/admin/* 和 /v3/mp/* 时，应按目录拆成两份。

一期 changelogs/ 沿用现行格式，不套用上述强制模板。

校验范围

检测器读取 git diff --name-status -z --find-renames 的结果，只校验本次 diff 新出现的目标路径：

• A（新增）、C（复制）和 R（重命名）的目标路径必须通过规则。
• M（修改历史文件）和 D（删除）豁免，不会因存量错误命名阻断。
• 重命名到受控目录时，新目标路径必须使用校验当天的上海日期。

本地校验：

npm test
npm run check:filenames -- --base origin/main --head HEAD

生产 CLI 故意不提供 --date 或日期环境变量；测试只通过导出的纯函数注入 Date。规则失败返回退出码 1，Git/事件/参数等基础设施错误返回 2。

前端消费状态

新增二期 changelog 必须使用 hl-changelog/v2 YAML Front Matter。状态只写在元数据中，不写入文件名：

backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
updated_at: "2026-07-24"

前端状态正常流转为：

pending → claimed → implemented → released → verified

不需要前端修改时使用 not_required。字段一致性、必填证据和新增文档 frontmatter 由 check:frontmatter 校验。

完整职责和命令见：

• FRONTEND_CONSUMPTION_STATUS_GUIDE.md
• BACKEND_CHANGELOG_DELIVERY_GUIDE.md

本地校验：

npm test
npm run check:filenames -- --base origin/main --head HEAD
npm run check:frontmatter -- --base origin/main --head HEAD

CI 与服务端阻断边界

Gitea Actions 会在指向 main 的 PR 和 main 的 push 上运行回归测试与文件名检测。该 workflow 是检测器：

• 在 main 未开启分支保护和 required status 时，失败状态不能硬性阻止合并。
• push 事件发生在写入之后，只能检测/报警，不能撤销直推。
• 只有管理员另行保护 main、关闭直推，并在 workflow 首次成功运行后，从 Gitea 最近上报的 status context 列表中选择实际值作为 required status，才能宣称服务端 hard gate 已激活。激活记录必须保存首次运行链接和 status API/分支保护回读证据；不得预设 job id/name validate 就是 Gitea 实际上报的 context。

因此，本仓库文件交付的准确表述是：detector 已安装；在 main 未保护时，服务端 hard gate 尚未激活。