bk-cmdb 社区贡献指南：从 Issue 沟通到 Pull Request 合入的完整参与流程

• 后端
• 企业应用
• 运维

蓝鲸配置平台（bk-cmdb）遵循通用的 GitHub 代码贡献流程，社区欢迎并鼓励开发者参与到源代码的维护中，共同构建良好的社区发展生态。本文以官方贡献指南 docs/wiki/contribute.md 为主体，完整梳理了从账户注册、Issue 沟通、方案确认，到 Fork 开发、提交 Pull Request、通过 Review 最终合入主库的每一步操作，并结合仓库内的 Contributing Guide、Bug 提单说明、版本迭代规则 以及编译、测试脚本等资料，帮助你快速上手成为 bk-cmdb 的 Contributor。读完本文，你将掌握一套可完整落地执行的社区贡献实战流程，并了解 CI 检查与本地验证的具体做法。

社区贡献概述

蓝鲸 cmdb 社区中的源代码、说明文档、方案设计文档等都是社区宝贵的资源，所有开发者都可以对这些资源进行维护。参与社区维护有两条主要途径（详见 docs/wiki/community.md）：

• Issue：在使用过程中遇到问题、发现 bug、提出新需求或功能优化点，都可以通过创建 Issue 的方式与社区互动；
• Pull Request（PR）：在阅读源代码、社区文档过程中发现问题后，通过提交 PR 来修复 bug、优化代码，内容可以是源码 bug、功能优化，甚至是一处文档描述错误或一个标点符号。

整个贡献流程可以概括为：注册账户 → 沟通 → 确定方案 → 开发 → 提交 PR → PR Review → PR Approve。下面按阶段逐一展开。

第一步：注册 GitHub 账户

参与贡献的第一步是拥有一个 GitHub 账户。如果还没有账户，可以到 GitHub 官网的注册入口快速注册。注册完成后，登录后即可进行 Fork、提 Issue、提交 PR 等后续操作。同时，你也可以点击 bk-cmdb 仓库上方的Watch按钮，实时跟踪社区动态，第一时间了解版本发布与讨论进展。

第二步：沟通——先提交 Issue，避免重复工作

对于 bug、需求类的问题，建议先在 GitHub 的 Issues 页面提交 issue，向社区反馈你的问题或需求，做一次初步沟通。这样做的目的有两个：

• 了解社区是否已经解决了该问题；
• 确认需求是否已经进入了排期。

提前沟通可以避免因信息不对称导致你做重复性的工作。在提交 Issue 之前，建议先在已有 Issue 中搜索是否存在相同或类似的问题，保证 Issue 不冗余（这也是 docs/CONTRIBUTING.md 中的明确要求）。

高效提交 Bug Issue：使用社区模板

为了让社区快速定位问题，官方在 docs/wiki/issue.md 中给出了 Bug 提单模板，建议按模板填写以下关键信息：

• 问题本身的具体内容（可以是一段日志，也可以是 Web 页面上弹出的提示截图）；
• 你使用的版本号，可对某个组件执行version命令获取，例如./cmdb_apiserver --version；
• 问题复现的具体流程。

社区提供的 Issue 模板示例如下：

问题描述 =========== <这里写问题描述> 重现方法 ================ <列出如何重现的方法或操作步骤> **重要提醒**: 请优先尝试最新发布的版本，如果问题不能在最新发布的版本里重现，说明此问题已经被修复。 关键信息 ========= **重要提醒**: 这些关键信息会辅助我们快速定位问题。 请提供以下信息: - [x] bk-cmdb 版本 (发布版本号 或 git tag): `<示例： v3.0.6-alpha 或者 git sha. 请不要使用 "最新版本" 或 "当前版本"等无法准确定位代码版本的语句描述>` - [ ] Redis 版本: `<示例： 3.2.11>` - [ ] MongoDB 版本: `<示例： 2.8.0>` - [ ] ZooKeeper 版本: `<示例： 3.4.11>` - [ ] 操作系统 : `<示例： Centos 5 (x64)>` - [ ] bk-cmdb 异常日志

你提供的信息越多，社区定位、解决问题的速度就越快。若不确定自己发现的是 Bug 还是 Feature，也可以直接提 Issue，由社区一起确认。针对提交的 Issue，社区确认是 bug 后的修复方式有多种：你可以直接提交修复 PR、在社区指导下修复，也可以交由社区修复。

第三步：确定方案——形成设计文档与接口文档

提交的问题、需求 Issue 经过社区确认后，就可以确定相应的解决方案，并输出相应的设计文档、接口文档等。这是社区参与者参与到开发过程的基础。有了这个基础，如果你希望深度参与开发，就可以进入下一个环节。

第四步：开发——Fork、Clone 与 Checkout

1. Fork 仓库到自己的账户

在 bk-cmdb 的仓库主页将源代码Fork到自己的仓库中。Fork 完成后，你的个人仓库中就会出现一份 bk-cmdb 的代码副本，后续所有修改都在这个副本上进行：

注意：仓库根目录的master分支在开发过程中可能处于不稳定或不可用状态，官方建议通过 releases 获取稳定的二进制文件，参与开发时则以社区确定的分支/tag 为准。

2. Clone 到本地

Fork 完成后，将你自己的仓库代码clone到本地。clone 速度较慢或超时，可参考 docs/overview/source_compile.md 中给出的代理配置方式：

git config --global http.proxy IP:PORT git config --global https.proxy IP:PORT

3. Checkout 到对应分支或 Tag

在确定方案后，社区会确定该问题、需求所属的分支或者 tag。将代码 clone 到本地后，需要将代码checkout到对应的分支、tag，然后根据确定的方案、接口文档等进行对应的开发工作。

关于分支协作，docs/CONTRIBUTING.md 补充了以下要求：

1. 从master或者hotfixfork 你自己的开发分支；
2. 修改代码之后，同步修改对应的文档和注释；
3. 在新建的文件中加入 license 和 copyright 声明；
4. 确保一致的代码风格；
5. 做充分的测试；
6. 然后将代码提交到dev或者hotfix分支。

4. 分批 Commit

在开发过程中，可以根据需要将大的需求拆解，分多个commit分批提交，使每次提交的变更内容清晰、便于社区 Review。需要说明的是，bk-cmdb 的版本号共分为 3 段，依据整个项目的迭代节奏管理，例如v3.2.4：第一段3代表大版本；第二段2代表一个版本迭代周期（包含一个或多个新特性或大的结构调整）；第三段4代表当前迭代周期内的特性与 bugfix 集合，一般为 1~3 周的周期（详见 docs/wiki/version-guidline.md）。了解这一规则有助于你在提交 Issue 和 PR 时准确描述版本上下文。

5. 本地编译与测试验证

在提交 PR 前，建议在本地完成编译与测试验证。仓库提供了完整的编译流程，可参考 docs/overview/source_compile.md：编译环境要求 golang >= 1.20（当前仓库go.mod中声明为go 1.25.0）、python 2.x、nodejs 14 LTS 等。在源码根目录src下执行：

make # 同时编译前端 UI 和后端服务 make server # 仅编译后端服务 make ui # 仅编译前端 UI make package # 打包，归档包存放于 configcenter/src/bin/pub/cmdb.tar.gz

编译脚本会遍历各服务模块的 Makefile 并逐个执行（见 scripts/build.sh），整体编译入口定义在 src/Makefile。仓库还提供了测试脚本 scripts/gotest.sh，可以对全部包执行go test并统计覆盖率。在修改了源码后跑通编译和测试，能显著提高 PR 一次通过 Review 的概率。

第五步：提交 PR——向主库发起 Pull Request

当完成代码开发后，就可以在你的仓库上向 bk-cmdb 主库发起一个Pull Request，将你完成的代码合入主库。提交 PR 时要选择好你要合入的对应分支。具体操作分三步：

1. 发起 PR

在你的仓库中，进入Pull requests页面，点击New pull request即可发起创建 PR 的操作：

2. 创建 PR

选择你本地开发的分支和要提交到主库的分支（确定方案后拿到的开发分支）：

3. 完成 PR 创建——填写必要信息

为了方便社区对你的 PR 进行 review，需要你在 PR 中填写相应的信息：

填写要点如下：

• 标题：简要填写该 PR 的主要内容；
• 描述框：详细描述本次变更，可以是新加功能、优化功能，或者是问题修复；
• 关联 Issue：利用 close 命令，在描述中声明该 PR 被合入主库后需要关闭的 Issue。

完成了这些信息的填写，点击Create pull request按钮即完成了 PR 的整个创建流程。PR 创建完成后，社区即收到你的 PR，进入 PR 的 review 环节。

第六步：PR Review——CI 检查与社区评审

在你完成 PR 的提交后，会自动触发 CI 流程，对提供的代码进行代码扫描、编译检查、单元测试、集成测试等。在通过这些检查后，社区会对你的 PR 发起review。这一过程与仓库内置的质量保障手段一致：编译脚本build.sh会遍历所有模块执行 make，测试脚本gotest.sh会对../src/...全量执行go test -cover并统计覆盖率。

评审结果有两种走向：

• Approve 合入：如果你的 PR 很完善，符合对应的方案，满足社区对应的开发规范，社区的 reviewer 会Approve你的 PR，然后将其合入主库；
• 调整后重新 Review：如果你的 PR 还需要调整，reviewer 会在你的 PR 下面评论，提出相应的调整建议。待你修改完成后，提交对应的 commit，reviewer 会再次发起 review，直到你的 PR 符合要求，最终合入主库。

注意：即使代码团队通过检查接纳了 PR，也不会立即合并到 master 分支，而是按社区分支管理流程统一处理，这一点在 docs/CONTRIBUTING.md 中有明确说明。

第七步：PR Approve——贡献达成

如果流程走到了这里，恭喜你，你的 PR 已经被核准，合入到了主库中。你的代码改动从此成为 bk-cmdb 主线的一部分，并受社区后续版本迭代的持续维护。

整体流程一览

为了更直观地展示参与社区的具体过程，官方给出了完整的流程示意图：

整个流程看上去比较复杂，实际操作起来还是比较简单的：先通过 Issue 与社区对齐目标，再 Fork 开发并提交 PR，配合 CI 检查和社区 Review，即可完成一次完整的贡献闭环。

协议说明：贡献代码即受 MIT 协议保护

bk-cmdb 采用 MIT 开源协议，具体内容见仓库根目录 LICENSE.txt。你贡献的代码同样受此协议保护，这也是在新建文件时需加入 license 与 copyright 声明的原因（见 docs/CONTRIBUTING.md）。项目承诺不会更改适用于交付给任何人的当前项目版本的开源许可证（MIT 协议），开发者可以放心参与共建。

• 后端
• 企业应用
• 运维