| name | pr-workflow |
| description | Use for ALL code changes — every modification to pkgs/, tests/, or scripts/ MUST go through a PR with CI verification before merging. No direct pushes to main. Covers branch creation, PR submission, CI monitoring, and merge rules. |
PR 工作流规范
核心原则
所有代码变更必须通过 PR + CI 验证后才能合并到 main。禁止直接 push 到 main。
这条规则没有例外——无论是新增包、版本升级、bug 修复、测试变更还是 skill 文件修改。
为什么
- main 分支是 xlings 用户直接拉取的包索引，直接 push 的错误会立即影响所有用户
- CI 包含 static analysis、isolation compliance、index registration、多平台 install/uninstall 测试
- 跳过 CI 意味着跳过这些保护，一个坏的 lua 语法就能让所有用户安装失败
标准流程
1. 创建分支
git fetch origin main
git checkout -b <type>/<scope> origin/main
分支命名规范：
feat/<pkg-name> — 新增包feat/<pkg-name>-<version> — 版本升级fix/<pkg-name>-<description> — 修复feat/spec-<name> — 规范/测试变更
2. 提交变更
git add <specific-files>
git commit -m "<type>(<scope>): <description>"
commit message 规范：
feat(mcpp): bump to 0.0.20 for all platformsfix(vc6): fix uninstall, register package.namefeat(spec): add D1 spec check
不要 git add .，只添加相关文件。
3. 推送并创建 PR
git push -u origin <branch>
gh pr create --title "<commit-style title>" --body "..." --base main
PR body 必须包含：
- Summary：改了什么、为什么
- Test plan：本地验证了什么、CI 需要验证什么
4. 等待 CI 通过
gh pr checks <pr-number>
CI 必须全部通过才能合并。包含：
static-and-isolation — 静态分析 + 隔离合规（pytest）index-registration — 包索引注册测试linux-test / windows-test / macos-install-test — 多平台测试
5. CI 失败处理
CI 失败时：
- 读取失败 job 的日志
- 分析根因并修复
- push 新 commit（不要 force push）
- 等待新一轮 CI
- 重复直到全部通过
6. 合并
CI 全绿后，通过 GitHub UI 或 CLI 合并：
gh pr merge <pr-number> --squash
禁止事项
| 操作 | 为什么禁止 |
|---|
git push origin main | 绕过 CI 验证 |
gh pr merge 时 CI 未通过 | 引入未验证的变更 |
| 一个 PR 混合不相关的变更 | 难以 review、难以 revert |
| force push 到已有 review 的 PR | 丢失 review 上下文 |
多个变更的处理
如果一次工作涉及多个不相关的变更（例如：版本升级 + spec 检测 + bug 修复），拆成多个 PR：
feat/mcpp-0.0.20 → PR #1: mcpp 版本升级
feat/vc6-chinese → PR #2: vc6 中文版 + 卸载修复
feat/xpkg-spec-d1 → PR #3: spec 检测规则
每个 PR 独立基于最新 main，独立通过 CI，独立合并。
紧急修复
即使是紧急修复也必须走 PR：
git checkout -b hotfix/<description> origin/main
git push -u origin hotfix/<description>
gh pr create --title "fix: ..." --base main
如果 CI 环境本身有问题导致无法通过，需要在 PR 中记录证据（日志截图/链接），经 maintainer 确认后才能合并。
与其他 skill 的关系
xpkg-updater: 更新包版本时，自动走本 PR 流程（见其 references/pr-ci-loop.md）xpkg-creater: 新增包时，同样必须通过 PR- 本 skill 是所有变更的底线规范，其他 skill 的流程都建立在此基础上
