964ab090b9
Two hard rules derived from reviewing real PRs: - Rule 1: one PR = one atomic change (feature or bug fix that cannot be further decomposed). Split multi-feat / multi-bug PRs before submitting. - Rule 2: every PR must include a verifiable validation method in the description: officecli command sequence / shell or python script / authoritative spec reference / screenshot. Bug fixes prefer command sequences; features prefer screenshots. Plus an explicit enforcement policy — either reject + ask for resubmission (preferred, preserves the "Merged" badge) or cherry-pick the valuable parts with a Co-authored-by trailer — so the maintainer can handle non-compliant PRs without ad-hoc reconcile workflows. English file is the canonical version; the Chinese file is a full translation linked from the header of both files.
4.3 KiB
为 OfficeCLI 贡献代码
English / 英文主文件: CONTRIBUTING.md
你必须遵守下面两条规则。代码风格、依赖、测试、文档由维护者在 merge 之后通过 follow-up commit 处理 —— 不用操心。
Rule 1: 一个 PR 只做一件不可再拆的事
一个 PR 必须包含且仅包含一个 feature 或一个 bug 修复,而且这个单元不能再被拆分。 如果你的改动可以被拆成多个每个都有独立价值的部分,就拆成多个 PR 分别提交。
自检
提交前,先让你的 AI 做一次拆分分析:
"分析下面这一坨 diff,它能不能拆成多个独立的 PR,每个都可以独立 merge 或独立 revert?如果可以,列出来。"
如果回答是"可以,N 个 PR",就先拆再提。
Examples
✅ 可以作为一个 PR 的 bug —— 单一根因,单一修复
图片只指定 width 时 height fallback 错了body 级 find: 锚点抛 ArgumentExceptionAddParagraph --index N 在 body 含 table 时偏移
✅ 可以作为一个 PR 的 feature —— 单一 coherent 能力
query ole: 列出所有嵌入的 OLE 对象及其 ProgID 和尺寸set wrap/hposition/vposition on floating pictures
❌ 必须拆 —— 多个独立改动被打包
修图片索引 bug + 加 OLE 检测 + 加 HTML heading 编号→ 3 个 PR,零共享代码加 OLE 对象检测 + 加 EMF→PNG 转换→ 2 个 PR,两个独立 layer加自动宽高比 + 修索引 off-by-one + 修行距裁剪→ 3 个 PR,三个不相关的根因
🤔 可拆可不拆 —— 默认选拆
加一个 helper 函数 + 第一处调用者→ 1 或 2 个 PR;helper 有独立复用价值就拆加 read 支持 + 加 write 支持(同一属性)→ 1 或 2 个 PR;希望 read 先被 vet 就拆
Rule 2: 每个 PR 必须附带可验证的验证方法
在 PR description 或关联 issue 里写清楚:reviewer 怎么才能验证你的改动真的有效。
Bug 修复 PR —— 至少给出一种(按优先顺序)
- officecli 命令序列,展示改动前的错误输出和改动后的正确输出
- shell 或 python 脚本,能复现 bug、在修复后干净退出
- 权威文档引用,说明正确行为应该是什么样(OOXML spec、Microsoft / ECMA 文档等)
- 截图 —— 仅当 bug 纯粹是视觉问题时
Feature PR —— 至少包含
- 一张截图,展示 feature 实际效果(Word / Excel / PowerPoint 窗口、HTML 预览、或终端输出)
- 可选:一段 shell 命令序列说明如何触发这个 feature
Examples
Bug 修复 —— 命令序列格式(最理想):
# Before my fix:
officecli blank test.docx
officecli add test.docx picture --prop "path=photo-2x1.png" --prop "width=10cm"
officecli query test.docx picture
# → height: "10.2cm" ❌ 错(硬编码 4 英寸 fallback)
# After my fix:
officecli blank test.docx
officecli add test.docx picture --prop "path=photo-2x1.png" --prop "width=10cm"
officecli query test.docx picture
# → height: "5.0cm" ✓ 对(根据 2:1 像素比例自动计算)
Feature —— 截图格式(最理想):
标题自动编号(从 style chain 解析)
Before: ![heading-before.png] (纯 "Chapter One",无编号) After: ![heading-after.png] ("1. Chapter One",带自动编号 span)
如何触发:
officecli blank demo.docx officecli add demo.docx paragraph --prop "style=Heading1" --prop "text=Chapter One" officecli watch demo.docx
如果你不遵守这两条规则
维护者保留以下两种处理方式。
Option A —— 拒绝并要求重新提交(首选)
维护者关闭 PR,留一条指向本 guide 的 comment,请你按规则拆分后重新提交。
你的 credit: PR 完全归你,重新提交成功后仍然拿 "Merged" badge。
Option B —— Cherry-pick 有价值的部分(最后手段)
如果你的 PR 里有一部分明显有价值、值得保留,维护者会用 git cherry-pick 直接把
这些 commit 摘到 main,然后关闭原 PR。
你的 credit:
git cherry-pick保留原作者,所以git log和git blame里那些代码行仍然 显示你是作者。- 维护者创建的 reconcile commit message 会附带
Co-authored-by: <you> <your-email>trailer,GitHub 贡献图会把它算进你的 contribution。 - 但原 PR 会显示为 "Closed" 而不是 "Merged"。