PubFetch 代码提交与 Pull Request 规范

这份规范参考 GitHub 官方文档整理，目标只有两个：

• 让提交历史更清晰，便于回滚和排查
• 让 Pull Request 更容易被理解、评审和合并

适用范围：

• pubfetch-client/
• pubfetch-server/
• 仓库根目录下的共享文档与配置

1. 工作流

本项目默认采用 GitHub 官方推荐的 GitHub flow：

1. 从默认分支 main 拉出一个短小、描述明确的分支
2. 在这个分支上完成一组单一目标的改动
3. 以小而完整的提交逐步推进
4. 创建 Pull Request，请求评审
5. 根据评审意见继续提交修正
6. 通过检查后合并到 main
7. 合并后删除分支

不建议直接在 main 上堆积未评审改动。

2. 分支命名

GitHub 官方建议使用简短且有描述性的分支名。本项目统一使用小写英文和短横线，必要时用前缀标明意图。

推荐格式：

• feature/<topic>
• fix/<topic>
• refactor/<topic>
• docs/<topic>
• test/<topic>
• chore/<topic>

示例：

• feature/batch-zip-export
• fix/wechat-code-block-newlines
• docs/update-extension-sop

要求：

• 一个分支只解决一类问题
• 不要把无关改动混到同一个分支
• 分支名要能让评审者一眼看出目标

3. Commit 原则

GitHub 官方文档强调：提交应该是“小而有意义的一组改动”，并且理想状态下每个提交都应当是“独立、完整、可理解”的。

本项目采用以下规则：

1. 每个 commit 只做一件事，或者只完成一个清晰的小步骤
2. 每个 commit 都应该可以独立解释“为什么改”和“改了什么”
3. 不要把重构、修复、文档、格式化、构建产物混成一个 commit
4. 能拆开的改动就拆开，这样更容易 review 和 revert

反例：

• 同一个 commit 里同时修改导出逻辑、重写样式、补测试、改 README
• 一个变量重命名横跨多个 commit，导致后续很难单独回滚

正例：

• 一个 commit 只修复 Markdown 导出中的代码块换行
• 一个 commit 只补充该修复对应的测试
• 一个 commit 只更新相关说明文档

4. Commit Message 规范

GitHub 官方要求 commit message 至少要“简要描述改动”。在本项目里，除了“简要”，还要求“可扫描、可检索、可回滚”。

推荐格式：

<type>: <summary>

可用的 type：

• feat: 新功能
• fix: 缺陷修复
• refactor: 重构，不改变外部功能
• docs: 文档修改
• test: 测试新增或调整
• chore: 构建、脚本、仓库维护

示例：

• feat: add zip packaging for batch markdown export
• fix: preserve line breaks in wechat code blocks
• refactor: split activation logic into dedicated module
• docs: document chrome extension reload workflow
• test: cover conservative language inference for code fences

要求：

• summary 用一句话说清主要改动
• 用祈使式、现在时描述动作即可
• 不要写成 update, modify, change 这种几乎没有信息量的泛词，除非后面有明确对象
• 不要在一个 commit message 里塞多件无关事情

如果需要补充背景，正文可使用：

<type>: <summary>

Why:
- 背景 / 问题

What:
- 关键改动

Risk:
- 兼容性 / 风险点

5. Pull Request 规范

GitHub 官方建议 PR 尽量小、聚焦、上下文清晰。本项目按以下结构写 PR：

标题

标题直接说明这次 PR 的核心目的，不要写模糊标题。

示例：

• Fix missing line breaks in exported markdown code blocks
• Add GitHub-style contribution guide and docs index

描述模板

建议使用以下结构：

## Why
- 为什么要做这次改动

## What Changed
- 改了哪些内容

## Validation
- 做了哪些验证

## Risk / Notes
- 风险点、兼容性、需要评审重点关注的地方

## Related
- 关联 issue / 文档 / 上下文链接

内容要求

PR 描述至少应包含：

• 这次改动解决什么问题
• 改动范围是什么
• 如何验证
• 是否有兼容性影响
• 如果改动较大，建议说明 review 顺序

如果关联 issue，使用 GitHub 关键字：

• Closes #123
• Fixes #123
• Resolves #123

6. 发起评审前自检

GitHub 官方建议在请求别人评审前先自己 review、build、test。本项目发起 PR 或准备合并前，至少完成以下检查：

1. 自己先看一遍 diff，去掉无关噪音
2. 运行相关测试或构建命令
3. 确认没有误提交临时文件、日志、缓存、构建垃圾
4. 确认文档是否需要同步更新
5. 如果改动影响 UI 或导出结果，准备截图、示例文件或复现路径

7. 哪些内容不要提交

除非有明确原因，不要提交以下内容：

• node_modules/
• 临时 Chrome profile
• 自动化验证日志
• 本地缓存目录
• 无关格式化噪音
• 未说明用途的生成产物

本项目当前默认忽略规则见仓库根目录：

• .gitignore

8. 合并标准

满足以下条件再合并：

1. 改动目标单一且边界清晰
2. commit 历史可读
3. PR 描述完整
4. 相关验证已完成
5. 风险点已在 PR 中说明
6. 文档已同步

9. 本项目的额外约定

• pubfetch-client/pubfetch/ 是扩展构建产物，默认不纳入版本控制
• 真正要修改的扩展源码在 pubfetch-client/src/
• 服务端源码在 pubfetch-server/src/
• 涉及浏览器加载、登录态、扩展重载的改动，必须同步检查：
  • pubfetch-client/docs/2026-05-14-extension-load-sop.md
• 涉及架构、模块边界、导出逻辑的改动，优先补充或更新：
  • pubfetch-client/docs/superpowers/memory/index.md

10. 参考来源

这份规范主要依据以下 GitHub 官方文档整理：

• GitHub flow
  https://docs.github.com/en/get-started/using-github/github-flow
• About commits
  https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits
• Helping others review your changes
  https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/helping-others-review-your-changes