docs: 新增提交规范（Conventional Commits）并链接至 README

明确 type/scope/subject/body/footer 规则与提交拆分约定；README 文档索引加入链接。
2026-09-08 17:32:44 +08:00
parent 27ec9badf2
commit a885b52f18
2 changed files with 76 additions and 1 deletions
@@ -3,7 +3,7 @@
 极简高安全私人笔记 + 博客。最终交付 = **一个二进制程序 + 一个数据文件（目录）**：
 无数据库服务、无缓存服务、无 Node 运行时、无外部依赖。

-> 设计文档：[docs/design.md](docs/design.md)（v1.1）；实施决策记录：[docs/decisions.md](docs/decisions.md)
+> 设计文档：[docs/design.md](docs/design.md)（v1.1）；实施决策记录：[docs/decisions.md](docs/decisions.md)；提交规范：[docs/contributing.md](docs/contributing.md)

 ## 功能

@@ -0,0 +1,75 @@
+# 提交规范（Conventional Commits）
+
+本仓库提交信息遵循 [Conventional Commits 1.0.0](https://www.conventionalcommits.org/zh-hans/v1.0.0/)，
+格式如下：
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+## type（必填）
+
+| type | 用途 |
+| --- | --- |
+| `feat` | 新功能（用户可感知的行为变化） |
+| `fix` | 缺陷修复（bug、安全漏洞、评审发现的功能缺陷） |
+| `docs` | 仅文档（设计/决策/评审报告/README/注释性文档） |
+| `refactor` | 重构（不改行为、不修缺陷的代码整理） |
+| `perf` | 性能优化 |
+| `test` | 仅测试代码（新增/修正用例与测试基建） |
+| `build` | 构建系统或外部依赖（Makefile、go.mod、npm、打包脚本） |
+| `ci` | 持续集成配置 |
+| `chore` | 其他杂项（不触及 src 与 test） |
+| `revert` | 回滚某次提交（subject 为被回滚提交的摘要，footer 注明 hash） |
+
+## scope（可选）
+
+按模块/目录取值，多个模块的横切改动可省略 scope 或在 body 中说明：
+
+`cmd` / `config` / `store` / `auth` / `markdown` / `middleware` / `httpapi` / `webui` / `web` / `deploy` / `docs`
+
+## subject 规则
+
+- 中文，动词开头（如「修正」「新增」「移除」「收尾」）；
+- 不超过 50 字；
+- 不加句号；描述「做了什么」，而非「做了什么活」。
+
+## body（可选）
+
+- 一行一要点，说明「为什么改」与「影响范围」；
+- 引用来源：评审条目（如 `round2 P1-2`）、设计章节（如 `§9.2`）、issue 编号。
+
+## footer（可选）
+
+- `BREAKING CHANGE:` 开头（或 type 后加 `!`）注明破坏性变更；
+- 回滚注明被回滚提交的 hash。
+
+## 示例
+
+```
+fix(store): 修正上一篇/下一篇邻接查询 tie-break 与 pinned 排序键
+
+同秒多篇更新时 id 比较方向与列表序相反导致漏链/错链；
+邻接语义纳入 pinned，与 ListPublicNotes 排序键一致。
+round2 P1-1
+```
+
+```
+feat(cmd): 新增 passwd 子命令免旧口令重设管理员口令
+
+重设成功后吊销全部会话；口令经 PN_ADMIN_PASSWORD 或交互输入。
+```
+
+```
+docs: 新增提交规范并链接至 README
+```
+
+## 提交拆分
+
+- 一个提交只做一件事（文档、功能、修复、测试分开）；
+- 修复缺陷时**同提交**附带其回归测试；
+- 不提交构建产物、密钥与本地配置（`pn` 二进制、`data/`、`.env` 等已在 `.gitignore`）。