GitHub 提交 SOP

本文档说明本项目如何把本地变更提交到 GitHub。日常协作默认走分支提交，不直接在 main 上推送业务变更。

1、提交前确认

提交前先确认本次变更范围：

git status -sb
git diff --stat

需要看清楚三件事：

• 本次改动是否都属于同一个目标。
• 是否有别人或自己未完成的无关改动。
• 是否包含生成产物、临时文件、敏感截图或账号信息。

如果工作区混有无关改动，只暂存本次目标相关文件，不使用 git add -A。

2、分支规则

如果当前在 main，先创建功能分支：

git switch -c codex/<short-description>

分支命名使用：

codex/<英文短描述>

示例：

codex/wiki-bilingual-docs
codex/github-submit-sop

如果当前已经在明确的功能分支上，可以继续使用当前分支。

3、提交前检查

文档、Wiki、Web 配置或脚本有变更时，必须运行：

cd web
npm run check
npm run build

npm run check 会检查：

• Markdown 本地链接和图片引用。
• 中文源 wiki/cn/ 与英文版 wiki/en/ 的覆盖关系。
• 英文页是否保留 Chinese source:。
• 英文侧边栏是否残留中文标签。

检查失败时先修复，再提交。

4、暂存和提交

推荐先查看变更摘要：

git diff --stat

确认全部属于本次任务后暂存：

git add -A

如果工作区混有无关改动，改为逐个暂存：

git add <path-1> <path-2>

提交信息使用简短祈使句或名词短语：

git commit -m "Add bilingual wiki docs"

5、推送到 GitHub

首次推送新分支：

git push -u origin "$(git branch --show-current)"

已经设置 upstream 的分支：

git push

推送完成后，在 GitHub 上确认分支和提交已经出现。

6、Pull Request 规则

团队协作建议通过 Pull Request 合并到 main。

如果本机安装并登录了 GitHub CLI，可以创建 PR：

gh auth status
gh pr create --draft --fill --head "$(git branch --show-current)"

如果没有安装 gh，推送分支后到 GitHub 页面创建 Draft PR。

PR 标题建议使用：

[codex] <change summary>

PR 描述至少写清楚：

• 改了什么。
• 为什么改。
• 对维护流程或阅读体验有什么影响。
• 已运行哪些检查。

7、提交后记录

提交完成后，在沟通中说明：

• 分支名。
• commit hash。
• 是否已推送。
• 是否创建 PR。
• 检查结果。