必须用Conventional Commits，因semantic-release等工具依赖feat:、fix:、chore:等前缀自动判定变更类型并生成CHANGELOG和版本号；Python项目需小写前缀+英文冒号空格，范围用具体技术如poetry、black，避免模糊词与废话。
commit message 为什么必须用 Conventional Commits？
因为 Git 工具链（比如 semantic-release、conventional-changelog）只认 feat:、fix:、chore: 这类前缀来自动判断变更类型和生成 CHANGELOG。不用它，自动化版本号 bump 和发布就直接失效——不是“推荐”，是工具链的硬性输入格式。
Python 项目里怎么写才合规？
说明：Conventional Commits 本身语言中立，但 Python 项目常因依赖管理、测试、打包等场景产生特殊提交，需注意语义对齐。
实操建议：
- 前缀必须小写，后跟英文冒号和空格，例如：feat(python): add pyproject.toml support
- 范围（括号内）建议用技术上下文，比如 test、poetry、black、setup.py，而不是模糊的 ci 或 infra
- 如果改的是纯文档或 .gitignore，用 docs 或 chore，别硬套 feat
- 避免在 message 里写“修复 bug”这种废话，直接说清影响，比如：fix(setuptools): pin setuptools <h3>哪些错误会让 CI 拒绝提交？
常见现象：<code>npm ERR! commit-msg hook failed 或 GitHub Actions 报 invalid commit format
原因和应对：
- 前缀拼错，比如写成 Feat:（首字母大写）、feature:（规范不认这个词）→ 只能用官方列表里的：feat、fix、docs、style、refactor、test、chore、revert
- 冒号后没空格，例如：fix:remove unused import → 必须是 fix: remove unused import
- 提交多于一行时，body 没空行分隔 header → 第二行开始算 body，header 和 body 之间必须有空行
- 使用中文标点或全角空格 → 全部用 ASCII 字符
Python 开发者最容易忽略的细节
- chore 不等于“杂活”，它特指不影响源码逻辑的维护操作，比如升级 pre-commit 配置、更新 .pre-commit-config.yaml，但修改 pyproject.toml 中的 [tool.black] 属于 chore；而加一个新 black 插件并调整代码风格，则属于 feat
- refactor 不能用于重命名变量或函数——那属于 chore 或 style；只有当重构改变了模块职责、拆分/合并类、替换算法实现时，才算 refactor
- 如果一次提交同时含功能新增和文档更新，优先按主要意图定前缀，次要内容写进 body，并用 Co-authored-by 标注协作者（如果适用）
实操建议：
- 前缀必须小写，后跟英文冒号和空格，例如：
feat(python): add pyproject.toml support- 范围（括号内）建议用技术上下文，比如
test、poetry、black、setup.py，而不是模糊的 ci 或 infra- 如果改的是纯文档或 .gitignore，用
docs 或 chore，别硬套 feat- 避免在 message 里写“修复 bug”这种废话，直接说清影响，比如：
fix(setuptools): pin setuptools <h3>哪些错误会让 CI 拒绝提交？
常见现象：<code>npm ERR! commit-msg hook failed 或 GitHub Actions 报 invalid commit format原因和应对：
- 前缀拼错，比如写成
Feat:（首字母大写）、feature:（规范不认这个词）→ 只能用官方列表里的：feat、fix、docs、style、refactor、test、chore、revert- 冒号后没空格，例如：
fix:remove unused import → 必须是 fix: remove unused import- 提交多于一行时，body 没空行分隔 header → 第二行开始算 body，header 和 body 之间必须有空行
- 使用中文标点或全角空格 → 全部用 ASCII 字符
Python 开发者最容易忽略的细节
- chore 不等于“杂活”，它特指不影响源码逻辑的维护操作，比如升级 pre-commit 配置、更新 .pre-commit-config.yaml，但修改 pyproject.toml 中的 [tool.black] 属于 chore；而加一个新 black 插件并调整代码风格，则属于 feat
- refactor 不能用于重命名变量或函数——那属于 chore 或 style；只有当重构改变了模块职责、拆分/合并类、替换算法实现时，才算 refactor
- 如果一次提交同时含功能新增和文档更新，优先按主要意图定前缀，次要内容写进 body，并用 Co-authored-by 标注协作者（如果适用）
Conventional Commits 的复杂性不在语法，而在每次提交前得想清楚：这次改的到底算什么“变更类型”。很多人卡在这一步，不是不会写，是不敢判。
Claw Code Suite (Python-Only Edition)
下载
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
