背景:本仓此前没有任何版本/构建元信息 —— 没有 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 是本次的测试证据。
This commit is contained in:
@@ -0,0 +1,112 @@
|
||||
# 已知陷阱(全文)
|
||||
|
||||
> 这份文件是 `AGENTS.md` 第 4 节那张索引的**全文**。拆成两份是有原因的:
|
||||
> `AGENTS.md` 作为"工作区指令"会被自动加载,而**指令有字节预算** —— 超出的部分会被
|
||||
> **静默截断**,没有任何报错。索引留在指令文件里(一行一条,一眼扫到),全文放这里。
|
||||
>
|
||||
> 纪律:**只追加、不重排、不复用旧号** —— 编号会被代码注释、测试、文档引用(形如"见 trap-3")。
|
||||
> 新增一条要改两处:这里加全文 + `AGENTS.md` 的索引表加一行。
|
||||
|
||||
## trap-1:`.gitignore` 对**已入库**的文件无效
|
||||
|
||||
**症状**:规则明明写了 `__pycache__/`,`git ls-files` 里却仍有 8 个
|
||||
`scripts/__pycache__/*.pyc`。
|
||||
|
||||
**根因**:`.gitignore` 只影响"未跟踪"的文件。文件一旦进了索引,规则对它就完全不起作用,
|
||||
而且**不会有任何提示**。
|
||||
|
||||
**判据**:`git ls-files | grep -E '__pycache__/|\.pyc$'` 输出非空即是这条。
|
||||
|
||||
**修法**:规则 + `git rm -r --cached <path>`(保留磁盘文件)。
|
||||
规则齐全不等于没被跟踪 —— 断言要查**两件事**:规则在、且 `git ls-files` 里没有。
|
||||
|
||||
**反例**:只加 `.gitignore` 规则就以为修好了。下次 `git add -A` 时它照样进来。
|
||||
|
||||
## trap-2:`git rm --cached` 之后跑 `git add -A`,文件会被搬回索引
|
||||
|
||||
**症状**:执行了 `git rm --cached node_modules`,`git status` 也显示删除了,
|
||||
提交后 `git ls-files` 里那个文件**仍在**,净效果为零。
|
||||
|
||||
**根因**:`--cached` 只从索引移除、**磁盘文件留着**。如果此刻忽略规则**还没生效**
|
||||
(本仓当时只写了 `/web/node_modules/`,管不到根级 `node_modules`),
|
||||
紧接着的 `git add -A` 会把这个"存在且未被忽略"的文件重新加回索引。
|
||||
|
||||
**判据**:`git rm --cached X` 后、提交前,先跑 `git check-ignore -v X` ——
|
||||
必须命中一条规则,否则 `add -A` 会把它捡回来。
|
||||
|
||||
**修法**:**先让忽略规则生效,再撤出索引**,并且此后只 `git add <具体文件>`,
|
||||
不要用 `-A`。
|
||||
|
||||
**反例**:把两步写成一条 `git rm --cached X && git add -A && git commit`。
|
||||
|
||||
## trap-3:用子串判断代替整行判断
|
||||
|
||||
**症状**:脚本判断"规则已存在"时写 `if "/node_modules/" not in 全文`,
|
||||
而文件里已有 `/web/node_modules/` —— **它包含这个子串**,于是误判为"已存在",
|
||||
跳过了追加。结果规则根本没加上,而脚本打印"规则已存在"。
|
||||
|
||||
**根因**:`.gitignore` 的 `/web/node_modules/` 与 `/node_modules/` 语义完全不同
|
||||
(前者只管 `web/` 下),但作为字符串是**包含关系**。
|
||||
|
||||
**判据**:任何"这条规则在不在"的判断,都要对**行集合**做精确比较
|
||||
(`{l.strip() for l in lines}`),不要对全文做 `in`。
|
||||
|
||||
**反例**:`if "xxx" not in text` 这类判断在多条相似规则并存时必然出错。
|
||||
|
||||
## trap-4:Gitea 合并接口成功时返回**空 body**
|
||||
|
||||
**症状**:脚本调用合并接口,HTTP 200,但解析 JSON 抛
|
||||
`json.decoder.JSONDecodeError: Expecting value: line 1 column 1`,
|
||||
看起来像"合并失败",于是重试 —— 而 PR 其实已经合并了。
|
||||
|
||||
**根因**:Gitea 的 `POST /pulls/{n}/merge` 成功时 body 为空(不是 `{"merged":true}`)。
|
||||
把"HTTP 200 + 空 body"当成失败是客户端的问题,不是服务端的问题。
|
||||
|
||||
**判据**:合并后 **不要**信 POST 的返回,改 `GET /pulls/{n}`,
|
||||
要求 `state=closed` + `merged=true` + `merge_commit_sha` 非空。
|
||||
|
||||
**反例**:在合并接口上做重试。**永不重试** —— 会得到"第二次合并失败"的假故障。
|
||||
|
||||
## trap-5:CI 检出是 `git fetch --depth 50`,**取不到 tag**
|
||||
|
||||
**症状**:想让版本号来自 `git describe --tags`,在 CI 上失败或给出误导结果。
|
||||
|
||||
**根因**:工作流里是 `git fetch -q --depth 50 origin "$BR"`,浅克隆不带 tag。
|
||||
`git describe` 要么报 `No names found`,要么退回到一个和预期无关的短 sha。
|
||||
|
||||
**判据**:任何依赖 tag 或完整历史的步骤,必须在 CI 里显式
|
||||
`git fetch --unshallow` 或 `git fetch --tags`;否则就是这条。
|
||||
|
||||
**修法(本仓采用)**:版本号的唯一来源改为仓库里的 `CHANGELOG.md`
|
||||
(`python3 scripts/version.py`),文件一定在,不依赖 tag。
|
||||
|
||||
**反例**:`VERSION=$(git describe --tags --always)` —— 本地看着正常,CI 上静默退化。
|
||||
|
||||
## trap-6:act_runner **不会**自动检出代码
|
||||
|
||||
**症状**:工作流第一步就报找不到文件 / 空工作区。
|
||||
|
||||
**根因**:本仓的 act_runner 不会替作业做 `git clone`,工作区起始为空。
|
||||
|
||||
**判据**:工作流里若没有 `git init` + `git remote add` + `git fetch` + `git checkout`,
|
||||
就是这条。
|
||||
|
||||
**修法**:照 `.gitea/workflows/build.yml` 的「检出代码」步写(带 `x-access-token` 的
|
||||
remote,令牌来自 `secrets.GITHUB_TOKEN`)。
|
||||
|
||||
**反例**:以为 runner 会像 GitHub Actions 那样自动 checkout,直接写业务步骤。
|
||||
|
||||
## trap-7:`grep -q` 在 `pipefail` 下会被 SIGPIPE 谎报失败
|
||||
|
||||
**症状**:`echo "$OUT" | grep -q 'PASS'` 明明匹配上了,整条命令却返回非 0
|
||||
(141),在 `set -o pipefail` 的作业里表现为"检查失败"。
|
||||
|
||||
**根因**:`grep -q` 一命中就退出并关闭管道,上游 `echo` 随即收到 SIGPIPE,
|
||||
整条管道返回 141。
|
||||
|
||||
**判据**:`set -o pipefail` + `... | grep -q ...` 同时出现即是这条。
|
||||
|
||||
**修法**:用 `case "$OUT" in *PASS*) ... ;; esac`,或让 `grep` 直接读文件;
|
||||
非用管道不可时用 `set +e; set +o pipefail` + `${PIPESTATUS[0]}`。
|
||||
|
||||
**反例**:`if echo "$x" | grep -q y; then` —— 时红时绿,且方向完全错。
|
||||
@@ -0,0 +1,75 @@
|
||||
# 提交规范
|
||||
|
||||
正本:**Git / 提交 / CI-CD 规范(Gitea 版)** —— 仓库 `zheromiku/eng-standards-main`,
|
||||
本机工作副本 `~/eng-standards/`。这份文件是本仓的执行版。
|
||||
|
||||
## 格式
|
||||
|
||||
```
|
||||
<类型>(<范围>): 一句话说清"改了什么"
|
||||
|
||||
正文:为什么这么改 / 现象 / 根因 / 怎么验的。
|
||||
```
|
||||
|
||||
- **类型**:`feat` 新功能 | `fix` 修缺陷 | `docs` 文档 | `style` 格式(不改逻辑) |
|
||||
`refactor` 重构 | `perf` 性能 | `test` 测试 | `build` 构建/依赖 | `ci` CI 配置 |
|
||||
`chore` 杂务 | `revert` 回滚
|
||||
- **范围**:可选、小写,取自本仓真实模块名(如 `card`、`release`、`monitor`、
|
||||
`settings`、`source-catalog`、`httpapi`、`deploy`)
|
||||
- 冒号后**一个空格**;描述 **≥3 字符**;标题 **≤72 字符**;**结尾不加句号**
|
||||
- 破坏性变更:类型后加 `!`,并在正文写 `BREAKING CHANGE:` 说明
|
||||
- **一件事一个提交**,且每个提交都要能各自编译/构建通过(否则 `git bisect` 失效)
|
||||
|
||||
放行自动生成的提交:`Merge ` / `Revert "` / `fixup! ` / `squash! ` / `amend! ` 开头。
|
||||
|
||||
## 正文写"为什么",不写"是什么"
|
||||
|
||||
diff 已经写了"是什么"。正文回答:**当时为什么这么改、试过什么、怎么确认它对了**。
|
||||
四种要素(可直接照抄形状):
|
||||
|
||||
| 要素 | 作用 |
|
||||
|---|---|
|
||||
| 现象(用户原话 / 报错原文) | 让后来的人对上号:我遇到的是不是同一件事 |
|
||||
| 根因(具体到文件·行·机制) | 正文核心;"没渲染"和"按纯文本渲染"是两回事 |
|
||||
| 取舍(为什么不用那个更自然的写法) | 防止下一个人"顺手现代化"改回去 |
|
||||
| 证据(跑了什么、量到了什么) | 把结论钉在可复现的命令上 |
|
||||
|
||||
## 两条闸门(都在这条链上)
|
||||
|
||||
1. **本机 hook** `~/.githooks/commit-msg`(由 `core.hooksPath` 全局生效)—— 快速反馈
|
||||
2. **CI 权威闸门** `.gitea/scripts/ci_gate.py` —— 在**编译之前**执行,非法提交**不编译**
|
||||
|
||||
⚠️ `git commit --no-verify` 只骗得过第一条。CI 会校验本次推送的**每一条**提交,
|
||||
有一条不合规整条流水线红。
|
||||
|
||||
## 写法禁忌
|
||||
|
||||
**不要在提交信息里用反引号与 `$()`**:shell 会先做命令替换,重则**执行**了里面的东西,
|
||||
而且**退出码仍是 0、没有任何报错**。一律用带引号的 heredoc:
|
||||
|
||||
```bash
|
||||
git commit -F - <<'EOF'
|
||||
fix(parser): 修复表格解析越界导致的 500
|
||||
|
||||
根因:……
|
||||
EOF
|
||||
```
|
||||
|
||||
`<<'EOF'` 的单引号是"里面的字符都是字面量"的唯一保证。
|
||||
|
||||
## 分支与推送
|
||||
|
||||
`main` **已启用分支保护**:禁止直接推送,一切改动走短命分支 + PR。
|
||||
|
||||
```bash
|
||||
git switch -c <type>/<slug> # 短命分支,合完即删
|
||||
# … 改动 …
|
||||
make verify # 本仓门禁;跳过项会显式警告"不算全绿"
|
||||
git commit -F - <<'EOF'
|
||||
<类型>(<范围>): 标题
|
||||
EOF
|
||||
git push -u origin HEAD
|
||||
```
|
||||
|
||||
单条规则与 CI 闸门完全一致的判据见 `.gitea/scripts/ci_gate.py`(两处必须同步改,
|
||||
不一致的表现是"本地绿、CI 红"或反之)。
|
||||
Reference in New Issue
Block a user