Apache Mesos 初学者贡献指南：从首个 GitHub PR 到 JIRA 工作流完整实战

• 云原生

Apache Mesos 是一个分布式系统内核，负责管理数据中心内的 CPU、内存、存储等资源并对外提供 API。本文是一份面向首次参与 Mesos 贡献的开发者的实操指南，核心覆盖"如何通过 GitHub Pull Request 提交文档类补丁或小型修复"这一最轻量的贡献路径，并完整介绍 JIRA 选题、本地构建测试、代码风格校验与提交流程。读完本文，你将掌握从 fork 仓库、安装开发钩子、定位 beginner 级 JIRA 议题，到跑通make check并成功提交 PR 的全链路技能，为日后切换到 高级贡献工作流 打好基础。

一、贡献路径概览：什么场景走 GitHub PR

Mesos 社区为贡献者提供了两条并行的工作流：

• GitHub Pull Request 流程（本文主线）：适用于文档修改（docs/目录下的 Markdown 页面）和小型、琐碎的修复（trivial fixes）。这类变更无需通过 Apache 的代码评审系统，直接向 Apache Mesos GitHub 镜像仓库 提交 PR 即可。
• 高级贡献流程（Advanced Workflow）：适用于涉及多组件、需要设计文档、或补丁规模较大的功能变更。该流程要求 Apache Review Board 账号、JIRA 账号以及 RBTools 等工具链，细节见 advanced-contribution.md。

快速总结（Quick Summary）：要向 Mesos 提议一个小变更，只需向 https://github.com/apache/mesos 这个公共 GitHub 镜像打开一个 PR。下面的章节给出逐步细节。

二、下载并准备 Mesos 仓库

2.1 Fork 与 Clone

要提交 GitHub PR，第一步是 fork Apache Mesos GitHub 镜像 到自己的账号下，然后把 fork 克隆到本地：

git clone https://github.com/<your-username>/mesos.git cd mesos

后续提交时把改动 push 到自己的 fork，再在 GitHub 上对上游仓库发起 PR。

2.2 按变更类型决定是否需要构建

这是初学者最容易混淆的一点，官方指南明确区分两种情况：

• 文档类变更（documentation-only）：不需要构建 Mesos即可开始。你只需要本地用任意 Markdown 阅读器渲染预览，确认显示效果即可。
• 功能性代码变更（functional change）：必须先构建 Mesos。完整依赖安装与构建步骤见 building.md，其中覆盖 Ubuntu 14.04/16.04、CentOS 6.6/7.1、macOS 以及 Windows 等系统的依赖清单与编译要求。

2.3 安装开发钩子：./support/setup-dev.sh

官方文档特别提醒：./support/setup-dev.sh脚本会安装 git hooks，帮助你在提交时遵守 Mesos 的代码风格。查看 support/setup-dev.sh 的源码可以看到它实际做的事：

# 必须在仓库根目录运行（检测 configure.ac 是否存在） if test ! -f configure.ac; then echo "You must run 'support/setup-dev.sh' from the root of the distribution." exit 1 fi # 为各种风格与工具配置创建软链接 ln -s support/gitignore .gitignore ln -s support/reviewboardrc .reviewboardrc ln -s support/clang-format .clang-format ln -s support/clang-tidy .clang-tidy ln -s support/CPPLINT.cfg CPPLINT.cfg ln -s support/gitlint .gitlint ln -s support/pre-commit-config.yaml .pre-commit-config.yaml # 安装 pre-commit 钩子 pre-commit install-hooks pre-commit install --hook-type pre-commit pre-commit install --hook-type commit-msg

也就是说，脚本会完成两件事：

1. 在仓库根目录为support/下的风格工具配置文件（.clang-format、.clang-tidy、CPPLINT.cfg、.gitlint、.pre-commit-config.yaml等）建立软链接；
2. 调用 pre-commit（需要预先安装该工具，否则脚本会报错退出）安装 pre-commit 与 commit-msg 两类钩子。

从 support/pre-commit-config.yaml 可以看到这些钩子在提交时自动执行的检查，包括：

• split：调用python ./support/mesos-split.py，检查一次提交是否跨多个子项目。Mesos 仓库实际由mesos、3rdparty/libprocess、3rdparty/stout等子项目组成，按项目拆分提交是硬性要求；
• license：调用python ./support/check-license.py，校验.cpp/.hpp/.py文件的 Apache License 头；
• cpplint：调用python ./support/cpplint.py，做 Google 风格 C++ 检查（对应 c++-style-guide.md）；
• gitlint（commit-msg 阶段）：校验提交信息，从 support/gitlint 可见其规则为标题行必须大写字母开头、以句号结尾且不超过 72 字符；
• pylint / eslint / require-ascii / check-yaml / check-json等按文件类型触发的检查。

因此，即使你只是提交文档补丁，也建议先跑一遍./support/setup-dev.sh，让提交信息与文件风格从一开始就符合社区要求。

三、找到要解决的问题：JIRA 选题策略

3.1 已有目标 vs 待选题

• 已有明确想改进的点：直接到 Mesos Slack（仓库site/下的社区页面）或开发者邮件列表（dev 列表）与 committers 沟通你的改进想法。
• 尚未确定做什么：在 JIRA 议题跟踪系统 中寻找开放的 issue。同样可以在 Slack 或开发者邮件列表询问哪些工作对社区影响力最大。

3.2 先沟通再写代码

官方指南从过往经验出发给出明确建议：贡献者在写代码之前最好先与 committer 讨论修复方案。这样做有两个实际收益：

1. 确保你掌握的上下文与代码库其余部分的风格一致；
2. 避免在需要大改才能合并（merge）的方案上浪费时间。

"请在我们写代码之前聊聊，我们会帮你设计解决方案！"——这是指南原文的号召。你可以在 JIRA ticket 中 @ 相关维护者、给 dev 邮件列表发邮件，或到 Slack/IRC（mesos频道）寻求 committer 担任你的shepherd（结对指导者），这个角色会为你的设计提供反馈并最终把你的改动提交进 Mesos 源码树。

3.3 用 JIRA 标签筛选新手议题

JIRA 是 Mesos 所有 bug 修复和功能新增的议题跟踪系统。关于某个 issue 的分配、讨论和解决方案提案都应记录在 JIRA 条目中；凡是超过 trivial 修复规模的贡献，都建议在 JIRA 中跟踪。以下标签可用于筛选 beginner 级别的 JIRA ticket：

官方强烈建议：从 beginner 级议题开始，随时间推移再挑战更高级的议题。此外，advanced-contribution.md 还补充了两个进阶选题原则：优先选择状态为 "Accepted" 的 issue（说明至少有一位开发者认为值得推进），并优先选择与下一个 release 相关的议题——这会提高评审阶段的优先级。

3.4 何时该升级到高级流程

GitHub PR 工作流最适合文档修改和小型修复。如果发现想做的议题需要提交的补丁规模较大（涉及多组件、需要设计文档），就应切换到 高级贡献工作流，它要求 JIRA 与 Apache Review Board 账号、RBTools 工具（0.7.10 版本可用，1.0.1 存在已知问题），并用support/post-reviews.py提交评审。

四、修改代码：改什么、怎么改

4.1 动手前的自查清单

官方指南在"Make Modifications"一节给出两条必须自问的问题：

• 文档是否需要同步更新？查看仓库中的docs/目录。Mesos 的所有用户文档、配置说明都集中在这里，功能变更几乎必然伴随文档改动。
• 测试是否需要新增或更新？查看仓库中的src/tests/目录。该目录存放全部测试套件，例如 src/tests/api_tests.cpp、src/tests/attributes_tests.cpp、src/tests/allocator.cpp 等，测试的组织方式可参考 testing-patterns.md。

4.2 遵循代码风格

对核心代码的补丁必须遵循 Mesos C++ Style Guide。该指南在 Google C++ Style Guide 基础上做了若干 Mesos 特有调整，例如：

• 应用代码使用lowerCamelCase变量命名，而 libprocess 与 stout 库使用snake_case；
• 构造函数/函数参数加前导下划线避免歧义；
• 常量使用SCREAMING_SNAKE_CASE；
• 用pre-commit run cpplint检查高层符合性，用support/mesos-tidy.sh检查低层细节。

安装好setup-dev.sh的钩子后，commit 阶段会自动执行上述大部分检查。

4.3 构建建议：在 build 目录外构建

advanced-contribution.md 给出了一个避免污染源码树的实践：不要在src/目录内构建，而是：

mkdir build && cd build ../configure make

这样configure和make生成的所有文件都隔离在build/目录中，想重置构建过程时直接删除build/目录重建即可，不会影响到你在src/中的改动。

五、构建与测试：让make check全部通过

5.1 两种变更的验证方式

• 文档类变更：用 Markdown 阅读器查看渲染效果，确认格式与链接正确。注意文档内部链接必须使用仓库内的相对路径（如docs/内的页面互相引用），确保渲染后能正确跳转。
• 代码变更：打开 PR 前必须构建并运行测试。核心命令是：

make check

必须在所有测试通过后才能提交 PR。构建的完整依赖与系统要求参见 building.md：例如 Linux 需要 64 位系统、GCC 4.8.1+ 或 Clang 3.5+、内核 2.6.28+；Ubuntu 16.04 上需要autoconf libtool build-essential python-dev python-six python-virtualenv libcurl4-nss-dev libsasl2-dev libsasl2-modules maven libapr1-dev libsvn-dev zlib1g-dev iputils-ping等软件包；从 git 仓库构建时还需先运行./bootstrap生成 configure 脚本。

5.2 测试套件的构成

从 src/tests/CMakeLists.txt 可以看到测试目标如何装配：mesos-tests可执行文件由MESOS_TESTS_SRC源码集合构建，并通过mesos-tests-interface接口库链接全部测试模块，最终add_test(NAME MesosTests ...)将测试注册到 CTest——这就是make check实际触发的内容。此外 CMake 还自动依赖test-helper、mesos-agent等辅助目标，说明测试运行时会拉起真实的 agent 进程。

5.3 高级测试技巧（进阶可参考）

advanced-contribution.md 提供的调试手段包括：

• 只构建不执行：make tests；
• 只跑单个用例：make check GTEST_FILTER="HTTPTest.Delete"；
• 反复执行单测捕捉偶发失败（跑 1000 次）：

sudo GLOG_v=1 ./bin/mesos-tests.sh --verbose --gtest_filter="*DOCKER*" --gtest_break_on_failure --gtest_repeat=1000

另外，Mesos 测试大量使用 libprocess 的Clock工具加速时间敏感事件（如注册重试退避），避免测试线程真的等待超时拖慢make check。模式细节（Clock::advance、Clock::settle、Clock::pause的组合用法）与完整示例代码见 testing-patterns.md。

六、提交 PR：从本地分支到 GitHub

6.1 提交前整理提交

advanced-contribution.md 对提交（commit）质量有明确要求，初学者应尽早养成这些习惯：

• 把变更拆分为一个或多个逻辑原子的提交（每个提交对应一次单一逻辑变更），便于评审；
• 避免把无关清理（如 typo 修复、风格微调）混入功能性变更的同一提交，否则历史难以阅读；
• 常用做法是先做增量提交保存进度，然后用git rebase -i重写历史整理成干净提交；
• 提交信息用过去时态，首句总结变更，以大写字母开头、不超过 72 字符并以句号结尾——这正是 support/gitlint 中regex=^[A-Z].*\.$与line-length=72两条规则所强制的。

6.2 同步上游后再推送

提交前确保与上游 master 同步，避免评审时夹杂他人改动：

git checkout master git pull git checkout my_branch git diff master # 确认只列出你的改动 git rebase master # 若有其他改动混入，用 rebase 对齐

6.3 打开 PR 并通知社区

当本地分支干净且准备就绪时：

1. push 到你的 Mesos fork；
2. 在 GitHub 上对 Apache Mesos 仓库发起 PR；
3. PR 打开后，到 Mesos Slack 或开发者邮件列表通知社区，吸引评审关注。

七、JIRA 使用要点与进阶指引

7.1 JIRA 是议题的唯一事实来源

JIRA 是 Mesos 所有 bug 修复与功能新增的跟踪系统（项目键MESOS）。官方要求：

• 所有 issue 的分配、讨论、解决方案提案都要记录在 JIRA 条目内；
• 超过 trivial 修复规模的贡献都应先在 JIRA 中跟踪。

7.2 认领议题的方式

在 JIRA 中找一个当前未分配（unassigned）的 ticket。当你提交的contributors.yaml相关 PR 被合并后，JIRA 管理员会把你的账号升级为 contributor 状态，此后你就能自行 assign JIRA 给自己。仓库根目录下的 docs/contributors.yaml 就是贡献者账号映射表，其中记录了每位贡献者的 name、affiliations、emails、jira_user 与 reviewboard_user 字段，用于把贡献映射到 JIRA 与 Review Board 账号。

7.3 从 beginner 到 advanced 的成长路径

以newbie、newbie++、beginner、beginners标签起步，逐步挑战更复杂的议题。当议题涉及多个组件、对开发者或用户社区影响较大时，社区会组建工作小组并撰写设计文档，参考案例是 inverse offer 项目（JIRA MESOS-1592）。此时你已进入 高级贡献工作流 的范畴：创建 Review Board 评审、在 "Bugs" 字段填写 JIRA 编号自动关联、在 "People" 字段添加 shepherd、在 "Testing Done" 字段写明测试过程，直到收到 committer 的 "Ship It!" 后由 committer 把补丁提交进源码树。

八、全流程速查清单

为方便查阅，将整个 beginner 贡献流程压缩为一张可执行的清单：

对于文档类小补丁，从 fork 到 PR 通常只需一个晚上；对于功能性修复，务必把构建与make check作为提交前的硬门槛。遵循"先讨论、再编码、风格合规、测试通过"的原则，你的第一个 Mesos 补丁就能顺利进入评审并合并进 Apache Mesos 源码树。

• 云原生