mcpp-contributing

mcpp 项目开发贡献规范

Overview

mcpp 项目的贡献流程：先创建 Issue → 切分支 → 实现改动 → 提交 PR → CI 通过 → Review 合入。

• 仓库：https://github.com/mcpp-community/mcpp
• 构建：mcpp build（C++23 模块自举）
• 测试：mcpp test 覆盖 tests/**/*.cpp，tests/e2e/ 提供真实二进制的端到端脚本
• CI：GitHub Actions，base 为 main 的 PR 触发分平台构建、测试与 E2E 检查

核心原则

禁止直接 push main

所有改动必须通过 PR 合入 main，无论改动大小。这包括：

• 代码改动（feat / fix / refactor）
• 文档改动（docs / skills / .agents/）
• 配置改动（mcpp.toml / .xlings.json / CI workflow）
• 版本号 bump（必须通过 PR，不能直接 push）

唯一例外：紧急 hotfix 需要 --admin 合入，但也必须先创建 PR。

违规示例（不允许）：

# ✗ 直接 push 到 main
git commit -m "docs: add skill" && git push origin main

# ✗ 绕过分支保护
git push origin feature:main

正确做法：

# ✓ 始终走 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（必须）

所有贡献先创建 Issue，特别是新功能。避免重复工作，留下讨论记录。

Bug 修复

gh issue create \
  --title "fix: 简短描述" \
  --body "## 复现步骤
1. ...

## 期望行为
...

## 实际行为
...

## 环境
- mcpp 版本：\`mcpp --version\`
- OS："

新功能

gh issue create \
  --title "feat: 简短描述" \
  --body "## 动机
...

## 设计思路
...

## 涉及模块
..."

代码优化

gh issue create \
  --title "refactor: 简短描述" \
  --body "## 当前问题
...

## 优化方案
..."

2. 创建分支

必须从最新 main 创建分支，禁止在 main 上直接开发。

git checkout main && git pull origin main
git checkout -b <type>/<short-description>
# 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/ 目录下

构建验证

# 用现有 bootstrap mcpp 自举构建
mcpp build
# 选择刚生成的 target/**/bin/mcpp（Windows 为 mcpp.exe），不要硬编码宿主 triple
<fresh-mcpp-binary> --version

测试

# C++ 单元/集成测试：由刚构建的二进制发现 tests/**/*.cpp
<fresh-mcpp-binary> test
# 端到端测试：显式把刚构建的二进制交给脚本
# 路径必须是刚构建产物的绝对路径；Windows 使用 mcpp.exe。
MCPP=<absolute-path-to-fresh-mcpp-or-mcpp.exe> bash tests/e2e/01_help_and_version.sh
MCPP=<absolute-path-to-fresh-mcpp-or-mcpp.exe> bash tests/e2e/<relevant-test>.sh
# 新功能按变更契约补充 focused unit/integration 和/或 E2E 覆盖