From 80ff8ab7651667d9267d986be1800d6a9430fd5b Mon Sep 17 00:00:00 2001
From: Yaosanqi137 <zxc18023571263@outlook.com>
Date: Sat, 4 Apr 2026 12:26:32 +0800
Subject: [PATCH] docs(contributing): define commit and branch conventions

---
 CONTRIBUTING.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..728d44f
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,69 @@
+# 贡献指南（Contributing）
+
+本文档定义 TodoList 仓库的协作规范，所有贡献者提交代码前请先阅读。
+
+## 1. 分支模型
+
+- 长期分支：
+  - `main`：生产稳定分支
+  - `develop`：开发集成分支
+- 功能分支：
+  - 命名：`feature/<phase>-<name>`
+  - 示例：`feature/p1-code-quality-hooks`
+- 其他分支：
+  - `release/<version>`
+  - `hotfix/<issue-id>-<short-desc>`
+
+## 2. 提交流程
+
+1. 从目标基线分支切出功能分支。
+2. 每完成一个小功能，提交一个最小 commit。
+3. 完成后推送分支并创建 PR。
+4. 通过 Code Review 后再合并到目标分支。
+
+## 3. Commit 规范
+
+- 使用 Conventional Commits：
+  - `feat(scope): ...`
+  - `fix(scope): ...`
+  - `chore(scope): ...`
+  - `docs(scope): ...`
+  - `test(scope): ...`
+  - `ci(scope): ...`
+- 要求：
+  - commit 粒度最小化，不要把多个不相关改动塞进一个提交。
+  - commit 必须可回滚、可解释。
+  - 默认使用 GPG 签名提交：`git commit -S`。
+
+## 4. PR 规范
+
+- PR 标题简明描述变更目标。
+- PR 描述至少包含：
+  - 变更概述
+  - 具体改动
+  - 测试结果
+  - 风险评估
+  - 回滚方案
+- 一个 PR 只解决一类问题，避免“超大 PR”。
+
+## 5. 代码质量检查
+
+提交前建议至少执行：
+
+```bash
+pnpm install
+pnpm run lint
+pnpm run typecheck
+pnpm run test
+```
+
+说明：
+
+- `pre-commit` 会自动执行 `lint-staged`。
+- `pre-push` 会自动执行 `typecheck + test`。
+
+## 6. 变更边界要求
+
+- 不要提交无关文件（例如本地 IDE 缓存、临时导出文件）。
+- 不要随意修改与当前任务无关的历史代码。
+- 如发现仓库出现非本人预期改动，先暂停并和维护者确认。