commit-work

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Commit work

提交工作

Goal

目标

Make commits that are easy to review and safe to ship:

only intended changes are included
commits are logically scoped (split when needed)
commit messages describe what changed and why

创建易于审阅且可安全发布的提交：

仅包含目标更改
提交具有合理的范围划分（必要时拆分）
提交信息说明更改内容及原因

Inputs to ask for (if missing)

需要询问的输入信息（若缺失）

Single commit or multiple commits? (If unsure: default to multiple small commits when there are unrelated changes.)
Commit style: Conventional Commits are required.
Any rules: max subject length, required scopes.

单次提交还是多次提交？（若不确定：当存在不相关更改时，默认拆分为多个小型提交。）
提交风格：必须遵循Conventional Commits规范。
任何规则：主题最大长度、必填范围等。

Workflow (checklist)

工作流程（检查清单）

Inspect the working tree before staging
- ```
git status
```
- ```
git diff
```
  (unstaged)
- If many changes:
```
git diff --stat
```
Decide commit boundaries (split if needed)
- Split by: feature vs refactor, backend vs frontend, formatting vs logic, tests vs prod code, dependency bumps vs behavior changes.
- If changes are mixed in one file, plan to use patch staging.
Stage only what belongs in the next commit
- Prefer patch staging for mixed changes:
```
git add -p
```
- To unstage a hunk/file:
```
git restore --staged -p
```
  or
```
git restore --staged <path>
```
Review what will actually be committed
- ```
git diff --cached
```
- Sanity checks:
  - no secrets or tokens
  - no accidental debug logging
  - no unrelated formatting churn
Describe the staged change in 1-2 sentences (before writing the message)
- "What changed?" + "Why?"
- If you cannot describe it cleanly, the commit is probably too big or mixed; go back to step 2.
Write the commit message
- Use Conventional Commits (required):
  - ```
  type(scope): short summary
```
- blank line
- body (what/why, not implementation diary)
- footer (BREAKING CHANGE) if needed
- Prefer an editor for multi-line messages:
```
git commit -v
```
- Use
```
references/commit-message-template.md
```
  if helpful.
Run the smallest relevant verification
- Run the repo's fastest meaningful check (unit tests, lint, or build) before moving on.
Repeat for the next commit until the working tree is clean

暂存前检查工作区
- ```
git status
```
- ```
git diff
```
  （查看未暂存更改）
- 若更改较多：
```
git diff --stat
```
确定提交边界（必要时拆分）
- 拆分依据：功能开发 vs 重构、后端 vs 前端、格式调整 vs 逻辑修改、测试代码 vs 生产代码、依赖更新 vs 行为变更。
- 若单个文件中存在混合更改，计划使用补丁暂存方式。
仅暂存属于下一次提交的内容
- 对于混合更改，优先使用补丁暂存：
```
git add -p
```
- 取消暂存某个代码块/文件：
```
git restore --staged -p
```
  或
```
git restore --staged <path>
```
审阅即将提交的内容
- ```
git diff --cached
```
- 合理性检查：
  - 无密钥或令牌
  - 无意外遗留的调试日志
  - 无不相关的格式混乱内容
用1-2句话描述暂存的更改（撰写提交信息前）
- 说明“更改了什么？” + “为什么更改？”
- 若无法清晰描述，说明提交可能过大或内容混杂；回到步骤2重新处理。
撰写提交信息
- 必须遵循Conventional Commits规范：
  - ```
  type(scope): 简短摘要
```
- 空行
- 正文（说明更改内容及原因，而非实现过程记录）
- 若有需要，添加页脚（BREAKING CHANGE）
- 多行信息优先使用编辑器：
```
git commit -v
```
- 如有帮助，可使用
```
references/commit-message-template.md
```
  模板。
运行最小相关验证
- 在继续之前，运行仓库中最快的有效检查（单元测试、代码检查或构建）。
重复上述步骤直到工作区干净

Deliverable

交付内容

Provide:

the final commit message(s)
a short summary per commit (what/why)
the commands used to stage/review (at minimum:
```
git diff --cached
```
, plus any tests run)

提供：

最终的提交信息
每个提交的简短摘要（更改内容及原因）
用于暂存/审阅的命令（至少包含
```
git diff --cached
```
，以及运行的任何测试命令）