G2rain（谷雨）开源智能体平台

# 贡献指南（Contributing Guide）

感谢你对 g2rain 的关注与贡献意愿！ 为了让协作更顺畅、更高效，请在参与项目前阅读本指南。

希望寻找适合自己的参与方向？欢迎阅读开源共建招募，了解参与方向、入门任务和联系入口。

# 1. 我可以如何贡献？

无论你是刚接触 g2rain，还是已经深入使用，都有很多方式可以参与：

  • 使用反馈：在实际项目中使用 g2rain，并反馈遇到的问题与需求。
  • 文档改进：修正文档中的错别字、过期内容、示例不清晰等问题。
  • Bug 修复：修复现有 Issue 中标记的 Bug，或你自己发现的问题。
  • 新特性：为平台提出或实现新功能（建议先通过 Issue / RFC 讨论）。
  • 示例与教程：补充 Demo、最佳实践、集成案例等。
  • 生态扩展：基于 G2rain 开发新的业务模块、应用、主题或插件，在自己的仓库发布开源后，将地址分享给我们，便于收录链接并推广。具体方式见独立扩展与生态分享。

# 2. 提交 Issue 前请先检查

在创建 Issue 之前，请先：

  1. 搜索现有 Issue，避免重复提问。
  2. 尽量确认问题属于 g2rain 本身，而不是环境或依赖配置问题。

创建 Issue 时建议包含：

  • 使用的仓库名称与版本（例如：g2rain-main-shell@1.0.0）。
  • 运行环境（Node 版本、浏览器、操作系统等）。
  • 复现步骤（最好附上最小可复现示例）。
  • 实际行为 vs 期望行为。

# 3. 提交 Pull Request（PR）流程

  1. Fork 仓库 在 GitHub 上 Fork 目标仓库（例如 g2rain-main-shell），并 Clone 到本地。

  2. 创建分支 从上游仓库最新的 develop 创建工作分支。以下以 g2rain-agent-runtime 为例，请替换为你实际贡献的仓库和 GitHub 用户名：

    git clone https://github.com/YOUR_USERNAME/g2rain-agent-runtime.git
cd g2rain-agent-runtime
git remote add upstream https://github.com/g2rain/g2rain-agent-runtime.git
git fetch upstream
git switch -c fix/issue-123 upstream/develop

    新功能可使用 feature/xxx，文档修改可使用 docs/xxx。一个分支聚焦一个问题；如果目标仓库没有 develop，先通过 Issue 联系维护者确认接入分支。

  3. 按目标仓库执行验证 本中央仓库仅维护文档，没有应用构建、启动或测试命令。文档变更需检查 Markdown 链接，并执行 git diff --check。子项目的依赖安装、构建和测试请遵循目标仓库 README 与 AGENTS.md，不要默认所有项目都使用 npm。

  4. 保持提交粒度清晰

    • 一个 PR 尽量专注于一个问题或一个特性。
    • Commit 信息建议遵循简单的约定式（如 fix: xxx、feat: yyy、docs: update zzz）。

  5. 编写或更新测试/示例（如果适用）

    • 为新功能添加必要的测试或示例。
    • 确保现有测试都能通过。

  6. 提交 PR 将工作分支推送到自己的 Fork：

    git add path/to/changed-file
git commit -m "fix: 修复问题的简要说明"
git push -u origin fix/issue-123

    在 GitHub 点击 Compare & pull request，确认目标为 g2rain/目标仓库 的 develop 分支，来源为 你的 Fork 的工作分支。代码改动提交到对应组件仓库；平台文档与治理改动提交到 g2rain/g2rain。

    PR 描述请包含：

    • 问题与关联 Issue：发生条件、期望结果和实际结果，可写 Refs #123。
    • 改动内容：实现方式、影响的模块与接口，以及兼容性影响。
    • 验证结果：实际执行的命令、测试结果及必要的截图；未完成的验证说明原因。
    • 部署与迁移：是否涉及数据库、配置、依赖版本或跨仓库配套，如何升级和回滚；不涉及时注明。
    • 文档与示例：说明同步更新的使用说明或示例入口。

    尚在开发或希望提前讨论的改动可以创建 Draft PR，完成后再标记 Ready for review。提交前检查 diff，移除本地配置、凭据、构建产物和无关格式变更。

  7. Review 与修改 Maintainer 或 Committer 会进行 Review，并可能提出修改建议。 请根据反馈在原工作分支继续提交并推送，更新同一个 PR。需要同步上游时，获取最新 upstream/develop 并解决冲突，再执行相关验证。

    贡献 PR 先合入 develop，由维护者完成测试环境验证及必要的跨组件联调后，再统一合并进入 main。 main 用于维护已验证的稳定内容；贡献者无需另行向 main 提交相同 PR。版本标签及正式发布由维护者按发布流程处理。

    Fork 工作分支 → PR 到上游 develop → Review 与修改
→ 合入 develop → 维护者验证 → 合入 main → 按计划发布

# 4. 代码风格与规范

不同子项目可能有各自的 Lint / 格式化配置（如 ESLint、Prettier 等），一般建议：

  • 保持与现有代码风格一致。

  • 子项目按目标仓库实际提供的格式检查、测试和构建命令验证；不要默认每个项目都使用 npm。

  • 本仓库文档变更检查相对链接与页内锚点，并执行 git diff --check。

  • 避免在无必要时大规模重排代码，以免影响 Review。

# 5. 文档贡献建议

先查看文档导航与维护分工 (opens new window)：组织介绍维护在首页，领域解释放入专题，项目运行事实回到责任项目，架构规则按既有治理流程修改。新增页面时同步补充索引，避免同一能力状态在多处重复维护。

文档同样重要，甚至比代码更容易帮助新用户上手。你可以：

  • 为新特性补充文档说明。
  • 将零散的 Issue / 评论中的经验整理成正式文档。
  • 补充中文/英文双语文档（如果社区有此需求）。

更新文档时建议：

  • 保证示例可运行、配置项与实际代码同步。
  • 在需要时添加简要的架构图或时序图，帮助理解。

# 6. 提案（RFC）与大改动

对于架构级别变更或影响较大的新特性，建议先通过 RFC 讨论：

  1. 在本仓库或相关子仓库创建 Issue，简单描述你的想法。
  2. 影响多个项目的架构规则时，按架构治理机制 (opens new window)在现有 ADR 目录 (opens new window)提出或更新决策，说明动机、方案与验证计划。
  3. 通过 Discussions 或社区会议收集反馈。
  4. 涉及跨项目规则时，更新适用 Profile Draft、选择代表项目验证，经评审后发布架构基线，由各项目显式升级。项目内的功能建议在对应仓库讨论。

这样可以避免重复劳动，也有助于社区理解设计背景。

# 7. 行为准则

所有参与者都应遵守项目的 行为准则 (opens new window)，保持友好、专业、尊重的交流氛围。 违反行为准则的行为可能导致 Issue / PR 被关闭，严重情况会被限制参与。

# 8. 致谢

感谢每一位使用、传播和贡献 g2rain 的开发者。 你的任何一点改动（哪怕只是修正一个错别字）都在帮助这个项目变得更好。

Last Updated: 2026-11-04T16:12:05.994Z

←