diff --git a/.agents/skills/mcpp-contributing/SKILL.md b/.agents/skills/mcpp-contributing/SKILL.md index 0880518..7dd58b6 100644 --- a/.agents/skills/mcpp-contributing/SKILL.md +++ b/.agents/skills/mcpp-contributing/SKILL.md @@ -3,17 +3,48 @@ name: mcpp-contributing description: Use when contributing to the mcpp project — submitting bug fixes, new features, code optimizations, documentation improvements, or any PR. Covers issue creation, branch conventions, build verification, CI requirements, and PR workflow using gh and git. --- -# mcpp 项目开发贡献 +# mcpp 项目开发贡献规范 ## Overview -mcpp 项目的贡献流程：先创建 Issue → 实现改动 → 提交 PR → CI 通过 → Review 合入。 +mcpp 项目的贡献流程：先创建 Issue → 切分支 → 实现改动 → 提交 PR → CI 通过 → Review 合入。 - 仓库：https://github.com/mcpp-community/mcpp - 构建：`mcpp build`（C++23 模块自举） - 测试：`tests/e2e/` 下的 bash 脚本 - CI：GitHub Actions，base 为 `main` 的 PR 自动触发 +## 核心原则 + +### 禁止直接 push main + +**所有改动必须通过 PR 合入 main**，无论改动大小。这包括： +- 代码改动（feat / fix / refactor） +- 文档改动（docs / skills / .agents/） +- 配置改动（mcpp.toml / .xlings.json / CI workflow） +- 版本号 bump（必须通过 PR，不能直接 push） + +**唯一例外**：紧急 hotfix 需要 `--admin` 合入，但也必须先创建 PR。 + +违规示例（不允许）： +```bash +# ✗ 直接 push 到 main +git commit -m "docs: add skill" && git push origin main + +# ✗ 绕过分支保护 +git push origin feature:main +``` + +正确做法： +```bash +# ✓ 始终走 PR 流程 +git checkout -b docs/add-release-skill +git commit -m "docs: add release skill" +git push -u origin docs/add-release-skill +gh pr create --title "docs: add release skill" --body "..." +# 等 CI 通过后合入 +``` + ## 贡献流程 ### 1. 创建 Issue（必须） @@ -66,20 +97,31 @@ gh issue create \ ..." ``` -### 2. 实现改动 +### 2. 创建分支 -**分支** +**必须从最新 main 创建分支，禁止在 main 上直接开发。** ```bash git checkout main && git pull origin main git checkout -b / -# type: feat / fix / refactor / test / docs +# type: feat / fix / refactor / test / docs / chore ``` +分支命名规范： +- `feat/xxx` — 新功能 +- `fix/xxx` — Bug 修复 +- `refactor/xxx` — 重构 +- `test/xxx` — 测试 +- `docs/xxx` — 文档 +- `chore/xxx` — 版本 bump、配置、依赖更新 + +### 3. 实现改动 + **开发要求** - 遵循现有代码风格（查看相邻代码） - 模块导入用 `import std;` 和 `import mcpp.xxx;` - 只改需要改的，不顺手重构不相关代码 +- 平台相关代码放在 `src/platform/` 目录下 **构建验证** @@ -98,9 +140,9 @@ bash tests/e2e/.sh # 相关测试 # 新功能应创建对应 E2E 测试 ``` -### 3. 提交 PR +### 4. 提交 PR -**提交信息**：`feat:` / `fix:` / `refactor:` / `test:` / `docs:` 前缀 +**提交信息前缀**：`feat:` / `fix:` / `refactor:` / `test:` / `docs:` / `chore:` ```bash git push -u origin @@ -116,7 +158,13 @@ Closes # - [ ] E2E 测试通过" ``` -### 4. CI 必须通过 +**PR 要求**： +- title 用英文，body 中英文均可 +- 关联 Issue（`Closes #N`） +- 包含 test plan +- 一个 PR 只做一件事，不混入无关改动 + +### 5. CI 必须通过 CI 不通过的 PR 不会被合入。 @@ -125,11 +173,68 @@ gh pr checks # 查看状态 gh run view --log-failed # 查看失败日志 ``` -CI 内容：mcpp 自举构建 + E2E 测试。只有 base 为 `main` 的 PR 触发。 +CI 包含三个平台： +| Workflow | 平台 | 内容 | +|----------|------|------| +| `ci` | Linux x86_64 | 自举构建 + E2E 测试 | +| `ci-macos` | macOS ARM64 | 自举构建 + E2E 测试 | +| `ci-windows` | Windows x86_64 | 自举构建 + E2E 测试 | + +**三个平台全部通过才能合入。** 如果某个平台失败： +1. 下载日志分析原因 +2. 修复后 push 到同一分支，CI 自动重跑 +3. 如果是 flaky test，在 PR 中说明 -### 5. Review & 合入 +### 6. Review & 合入 -维护者 review → 反馈修改 → CI 重跑 → Squash merge。 +维护者 review → 反馈修改 → CI 重跑 → Merge（保留 commit 历史）。 + +合入方式： +- 默认使用 **Merge commit**（保留完整历史） +- 单 commit 的 PR 也可用 **Squash merge** + +## Agent 开发规范 + +Agent（Claude Code 等）在执行任务时，**同样必须遵守 PR 流程**： + +### Agent 必须做的 +- 从最新 main 切新分支 +- 所有改动通过 PR 提交 +- 等 CI 通过后再请求合入 +- 合入前先确认 PR 无冲突 + +### Agent 禁止做的 +- 直接 push 到 main（即使有 admin 权限） +- 绕过 CI 检查合入 +- 在已合入的分支上继续开发（应切新分支） +- 一个 PR 混入不相关的改动 + +### Agent 的典型工作流 + +```bash +# 1. 从最新 main 切分支 +git checkout main && git pull origin main +git checkout -b / + +# 2. 实现改动 +# ... edit files ... + +# 3. 提交并推送 +git add +git commit -m ": " +git push -u origin / + +# 4. 创建 PR +gh pr create --title ": " --body "..." + +# 5. 等 CI 通过 +# 每 60s 检查一次，失败则分析修复 +gh run list --branch --limit 3 + +# 6. CI 全部通过后，请求用户 review 合入 +# 或者用户授权后： +gh pr merge --merge +``` ## 项目结构 @@ -138,6 +243,17 @@ src/ ├── cli.cppm ← 命令行入口 ├── config.cppm ← 全局配置 ├── manifest.cppm ← mcpp.toml 解析 +├── platform/ ← 平台抽象层（所有平台相关代码） +│ ├── platform.cppm ← 统一外观模块 +│ ├── common.cppm ← 平台常量与检测 +│ ├── process.cppm ← 进程执行（自动 stdin 保护） +│ ├── fs.cppm ← 文件系统（exe 路径、文件锁） +│ ├── shell.cppm ← Shell 引用 +│ ├── env.cppm ← 环境变量 +│ ├── terminal.cppm ← 终端检测 +│ ├── macos.cppm ← macOS 特有 +│ ├── linux.cppm ← Linux 特有 +│ └── windows.cppm ← Windows 特有 ├── build/ ← 构建系统（ninja 后端） ├── pm/ ← 包管理子系统 ├── toolchain/ ← 编译器检测管理 @@ -153,5 +269,7 @@ docs/ ← 用户文档 ## 注意事项 - C++23 模块项目，修改模块时注意 import 依赖顺序 +- 平台相关代码统一放 `src/platform/`，不在其他模块中直接使用 `#if defined` - E2E 测试应独立运行，不依赖网络 - 不确定方向时先在 Issue 讨论再动手 +- **永远走 PR 流程，不直接 push main** diff --git a/.github/workflows/ci-macos.yml b/.github/workflows/ci-macos.yml index 4664479..5f3e522 100644 --- a/.github/workflows/ci-macos.yml +++ b/.github/workflows/ci-macos.yml @@ -323,6 +323,6 @@ jobs: # May fail if xlings mcpp version lacks recent fixes. TMP=$(mktemp -d) cd "$TMP" - mcpp new hello + "$MCPP" new hello cd hello - mcpp run + "$MCPP" run diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e0ad346..23d2caf 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -141,6 +141,6 @@ jobs: # May fail if xlings mcpp version lacks recent fixes. TMP=$(mktemp -d) cd "$TMP" - mcpp new hello + "$MCPP" new hello cd hello - mcpp run + "$MCPP" run diff --git a/.xlings.json b/.xlings.json index 2ef3138..940017a 100644 --- a/.xlings.json +++ b/.xlings.json @@ -1,5 +1,5 @@ { "workspace": { - "mcpp": "0.0.17" + "mcpp": "0.0.20" } }