# 为本项目做贡献

感谢您考虑为本项目做贡献！本文档概述了贡献流程和一些需要遵循的准则。

🆕 **GitHub 或拉取请求新手？** 请先查看我们的[初学者友好的拉取请求指南](docs/how-to-contribute-with-pull-requests.md)！

📋 **在贡献之前**，请阅读我们的[指导原则](docs/GUIDING-PRINCIPLES.md)以了解 BMad 方法的核心理念和架构决策。

另请注意，我们使用 GitHub 中的讨论功能来建立一个社区，讨论潜在的想法、用途、补充和增强功能。

💬 **Discord 社区**：加入我们的 [Discord 服务器](https://discord.gg/gk8jAdXWmj) 进行实时讨论：

-   **#general-dev** - 技术讨论、功能想法和开发问题
-   **#bugs-issues** - 错误报告和问题讨论

## 行为准则

通过参与本项目，您同意遵守我们的行为准则。请在参与前阅读。

## 如何贡献

### 报告错误

1.  **首先检查现有问题**以避免重复
2.  **创建新问题时使用错误报告模板** - 它将指导您提供：
    -   清晰的错误描述
    -   重现步骤
    -   预期与实际行为
    -   模型/IDE/BMad 版本详细信息
    -   如果适用，请提供屏幕截图或链接
3.  **考虑在 Discord 中讨论**（#bugs-issues 频道）以获得快速帮助
4.  **表明您正在修复**以避免重复工作

### 建议功能

1.  **首先在 Discord 中讨论**（#general-dev 频道）- 功能请求模板会询问您是否已这样做
2.  **检查现有问题和讨论**以避免重复
3.  **创建问题时使用功能请求模板** - 它将指导您：
    -   确认 Discord 讨论
    -   描述它解决的问题
    -   解释您的解决方案
    -   列出已考虑的替代方案
4.  **具体说明**为什么此功能将使 BMad 社区受益

### 拉取请求流程

⚠️ **开始工作前：**

1.  **对于错误**：检查是否存在问题（如果不存在，请使用错误模板创建一个）
2.  **对于功能**：确保您已在 Discord（#general-dev）中讨论过并创建了功能请求问题
3.  **对于大的更改**：始终先打开一个问题以讨论对齐

请只提出小的、粒度化的提交！如果更改较大或重要，请在讨论选项卡中讨论并首先打开一个问题。我不希望您在一个可能非常大的 PR 上浪费时间，结果却因为它没有对齐或偏离了其他计划的更改而被拒绝。沟通，让我们共同努力，建立和改进这个伟大的社区项目！

**重要提示**：所有贡献都必须符合我们的[指导原则](docs/GUIDING-PRINCIPLES.md)。要点：

-   保持开发代理精简 - 它们需要编码的上下文，而不是文档
-   Web/规划代理可以更大，任务更复杂
-   一切都是自然语言（markdown）- 核心框架中没有代码
-   使用扩展包实现特定领域的功能

#### 您的 PR 应该提交到哪个分支？

**提交到 `next` 分支**（大多数贡献）：

-   ✨ 新功能或代理
-   🎨 对现有功能的增强
-   📚 文档更新
-   ♻️ 代码重构
-   ⚡ 性能改进
-   🧪 新测试
-   🎁 新扩展包

**提交到 `main` 分支**（仅限关键）：

-   🚨 破坏基本功能的关键错误修复
-   🔒 安全补丁
-   📚 修复严重不正确的文档
-   🐛 阻止安装或基本使用的错误

**如有疑问，请提交到 `next`**。我们宁愿在更改进入稳定版之前对其进行彻底测试。

#### PR 大小指南

-   **理想的 PR 大小**：200-400 行代码更改
-   **最大 PR 大-  **每个 PR 一个功能/修复**：每个 PR 应解决一个问题或添加一个功能
-   **如果您的更改较大**：将其分解为多个可以独立审查的较小 PR
-   **相关更改**：即使是相关的更改，如果它们提供独立的价值，也应该是独立的 PR

#### 分解大型 PR

如果您的更改超过 800 行，请使用此清单进行拆分：

-   [ ] 我可以将重构与功能实现分开吗？
-   [ ] 我可以在一个 PR 中引入新的 API/接口，在另一个 PR 中实现吗？
-   [ ] 我可以按文件或模块拆分吗？
-   [ ] 我可以先创建一个包含共享实用程序的基础 PR 吗？
-   [ ] 我可以将测试添加与实现分开吗？
-   [ ] 即使更改是相关的，它们能否独立提供价值？
-   [ ] 这些更改可以按任何顺序合并而不会破坏任何东西吗？

示例分解：

1.  PR #1：添加实用程序函数和类型（100 行）
2.  PR #2：重构现有代码以使用实用程序（200 行）
3.  PR #3：使用重构后的代码实现新功能（300 行）
4.  PR #4：添加综合测试（200 行）

**注意**：PR #1 和 #4 可以同时提交，因为它们提供独立的价值并且不依赖于彼此的合并顺序。

#### 拉取请求步骤

1.  Fork 存储库
2.  创建一个新分支 (`git checkout -b feature/your-feature-name`)
3.  进行更改
4.  运行任何测试或 linting 以确保质量
5.  使用清晰、描述性的消息提交您的更改，遵循我们的提交消息约定
6.  推送到您的分支 (`git push origin feature/your-feature-name`)
7.  针对主分支打开一个拉取请求

## 问题模板

我们使用 GitHub 问题模板来确保提供所有必要的信息：

-   **错误报告**：自动指导您提供重现步骤、环境详细信息和预期行为
-   **功能请求**：需要 Discord 讨论确认并要求提供问题/解决方案描述

使用这些模板有助于维护人员更快地理解和处理您的贡献。

## 拉取请求描述指南

遵循此模板，使 PR 描述简短明了：

### PR 描述模板

保持您的 PR 描述简洁明了。使用此模板：

```markdown
## 内容

[1-2 句话描述更改了什么]

## 原因

[1-2 句话解释为什么需要此更改]
修复 #[问题编号]（如果适用）

## 方法

[2-3 个要点列出您是如何实现的]

-
-
-

## 测试

[1-2 句话说明您如何测试]
```

**最大 PR 描述长度：200 字**（如果需要，不包括代码示例）

### 好的与坏的 PR 描述

❌ **坏例子：**

> 这个革命性的 PR 通过实施一种利用尖端方法论来优化性能指标并通过创新方法为利益相关者提供前所未有的价值的先进解决方案，对系统的架构进行了范式转换的增强...

✅ **好例子：**

> **内容：** 添加了对代理依赖解析的验证
> **原因：** 当代理具有循环依赖时，构建会静默失败
> **方法：**
>
> -   在 dependency-resolver.js 中添加了循环检测
> -   抛出带有依赖链的清晰错误
>   **测试：** 使用 3 个代理之间的循环依赖进行了测试

## 提交消息约定

使用常规提交格式：

-   `feat:` 新功能
-   `fix:` 错误修复
-   `docs:` 仅文档
-   `refactor:` 既不修复错误也不添加功能的代码更改
-   `test:` 添加缺失的测试
-   `chore:` 对构建过程或辅助工具的更改

保持提交消息在 72 个字符以内。

### 原子提交

每个提交都应代表一个逻辑更改：

-   **做：** 每个提交一个错误修复
-   **做：** 每个提交一个功能添加
-   **不要：** 将重构与错误修复混合在一起
-   **不要：** 合并无关的更改

## 代码风格

-   遵循现有的代码风格和约定
-   为复杂逻辑编写清晰的注释

## 许可证

通过为本项目做贡献，您同意您的贡献将根据 MIT 许可证获得许可。