Skip to content

Latest commit

 

History

History
94 lines (69 loc) · 4.64 KB

pre-commit.md

File metadata and controls

94 lines (69 loc) · 4.64 KB

后端 pre-commit 开发规范

后端以 src/backend/.pre-commit-config.yaml 作为唯一检查规则,项目开发依赖固定使用 pre-commit==4.2.0。本地提交检查暂存文件,CI 检查全部受管文件。

首次安装

在 src/backend 目录安装项目开发依赖后执行:

make install-hooks

该命令使用项目 .venv/bin/pre-commit 安装 Git 的 pre-commit 和 commit-msg hook。 每个 clone 需要安装一次;标准 Git worktree 与主 checkout 共用 hook。 更新 .pre-commit-config.yaml 后可再次执行,不需要重复维护本机 .git/hooks 内容。

不建议使用 --allow-missing-config。它会允许配置文件不存在时跳过检查,适合通用模板, 不适合已经强制维护配置的本项目。

提交标题检查通过后端配置中的 local hook 运行 ../../agent/backend/tools/commit-message/commit_message.sh,只依赖 sh、awk 和 Git。 校验器不使用 .venv 路径,也不要求启动 Django。pre-commit 本身仍需要安装环境, 它生成的 Git 入口会记录当前安装器的 Python 路径;迁移虚拟环境后重新运行安装命令即可。

后端 hook 在暂存区含 src/backend 或 agent/backend 改动时校验标题,混合前后端提交也会校验; 纯前端及其他非后端改动跳过。无暂存差异的 amend/reword 等仍校验,避免通过改标题漏检。 worktree 共用入口,但会读取当前 worktree 的配置和暂存区;尚未接入的旧分支不会自动获得规则。

如果本机设置了 core.hooksPath(例如前端 Husky 安装设置),pre-commit 会拒绝安装。 先检查配置来源和现有 hook,再明确选择使用哪套入口;不要静默覆盖、自动 unset 或修改前端配置。

提交标题规则

普通标题使用 <type>: <summary> #<issue> 或 <type>: <summary> --<TAPD key>=<数字>, tracker 位于标题末尾。允许 feat fix docs style refactor perf test chore,摘要不能为空。 常用 TAPD key 是 story 和 bug;格式合法不代表需求存在或归属正确。 合并标题 Merge ... 允许不带 tracker。

正文可选,推荐空行后写概括性的 - bullet。hook 不额外强制正文格式。 单独验证已有 message 或检查指定历史范围,可在后端目录执行:

sh ../../agent/backend/tools/commit-message/commit_message.sh validate --message-file /tmp/commit-message.txt
sh ../../agent/backend/tools/commit-message/commit_message.sh check-range <base>..HEAD

手动验证合并标题时加 --allow-merge。历史检查不会补写需求号或改写提交。 本地 hook 不扫描既有历史;修改历史提交后应使用明确的范围检查,而非只检查最新提交。

日常开发

只暂存本次改动,不要执行 git add .:

git add path/to/changed_file.py
make quality
git commit

make quality 和提交 hook 默认只检查 Git 暂存区。格式器修改文件时,本次检查会失败;请 review 修改、重新暂存,再次提交。禁止使用 git commit --no-verify 绕过检查。

常用入口:

make quality      # 只检查暂存文件,等价于提交 hook
make quality-all  # 检查全部文件,本地复现 CI
make test         # 运行后端常规测试,不含 special
make check        # 检查暂存文件并运行常规测试
make test-all     # 顺序运行常规与 special 测试

CI 与合并约束

GitHub Actions 的 Backend pre-commit job 会对所有 PR 上报结果,不能在 PR 事件上用 paths 跳过整个 workflow,否则 required check 会一直等待状态。job 先分页读取 PR 文件列表, 涉及 src/backend/、agent/backend/、该 workflow 或其路径检测脚本及测试时,才执行 pre-commit run --all-files --show-diff-on-failure;纯前端和其他无关改动跳过后端安装与检查步骤, 在 summary 说明后正常通过。重命名同时检查新旧路径,文件列表不完整时保守执行后端检查。 路径检测、回归测试或后端检查失败都会使同一个 job 失败,不会被后续成功步骤覆盖。

main 推送仍按后端及 CI 相关路径触发;手动执行始终运行完整检查。路径检测回归测试可在仓库根执行:

node --test .github/scripts/backend-pre-commit.test.cjs

仓库管理员应在 main 分支保护规则中将 Backend pre-commit 和现有单测 job 设为 required checks。该 job 检查文件质量, 不会因新增本地 commit-msg hook 自动扫描提交历史;历史标题仍需使用明确范围检查或 对应的上游提交门禁。 本地 hook 可以被人为绕过, 分支保护才是最终强制门禁。