前言：从使用者到共同维护者

第一次参与开源，最难的往往不是写代码，而是不知道下一步该做什么：哪个项目愿意接纳新人，问题应发到哪里，PR 没有人回复是不是做错了，成为 Committer 又意味着什么？当你终于获得写权限，新的问题会随之出现：能否直接合并自己的修改，怎样发布版本，收到漏洞报告时应该公开多少信息，社区发生分歧时由谁决定？

本书把这些问题串成一条实践路线。你会先选择一个自己真正使用的 Apache 项目，完成一次能被复核的贡献，再逐步学习协作、维护、安全响应和治理。目标不是收集身份，而是让你能够在一个由志愿者、公司员工、独立开发者和用户共同组成的社区中，持续做值得信任的事。

全书以“林舟”参与一个虚构的数据处理项目为贯穿案例。项目、人物、邮件和事件均为教学示例，不代表任何真实 Apache 项目的政策或历史。终端中的仓库地址、分支名、测试命令和邮箱都必须按目标项目替换；示例域名使用 example.org，不能用于实际提交或安全报告。

如果你刚接触 Git，先阅读第一至六章，并完成第六章的练习。如果你已是贡献者，可直接阅读第七至九章。如果你正在值班处理安全报告，先看第十章，再回头补足发布与治理知识。

本书区分三类内容：ASF 的通用制度、项目自行约定的流程，以及作者建议的工作方法。官方链接列在各章及附录；涉及投票、任命、发布、安全与法律义务时，以执行当日的 ASF 官方政策和项目正式规则为准。本书核对日期为 2026 年 10 月 20 日，不承诺未来政策保持不变。

第一章 认识 Apache：代码之外还有共同体

1.1 ASF、项目与公司的边界

Apache 软件基金会（Apache Software Foundation，简称 ASF）为多个项目提供法律与组织框架、基础设施和品牌保护。项目的日常技术与社区事务由相应的项目管理委员会（Project Management Committee，PMC）负责。不能把 ASF 想象成一家统一分派需求、招聘开发人员的软件公司，也不能把某个项目看作主要赞助公司的内部产品部门。

公司可以资助员工参与，也可以投入大量工程资源。但公司里的职位、客户合同或商业投入，不会自动转换为社区中的决策权。参与者需要公开解释技术理由，接受其他人的审查，并尊重项目的治理流程。你可以在工作时间贡献，却应当以个人身份承担社区责任，主动披露与讨论有关的利益关系。

Apache License 2.0 是软件许可证；“一个仓库采用 Apache 许可证”和“它是 ASF 项目”是两回事。许可证授予的使用、修改和分发权限，也不能被理解成自动授予 Apache 商标使用权。选项目时先确认其官方网站和归属，不要只看 GitHub 上的组织名称或许可证文件。

1.2 角色是一组责任

Contributor、Committer 与 PMC 不应被理解为公司的职级。一个人可以主要贡献文档和社区支持，也可能因长期展示出可靠判断而获得信任。不同项目对权限范围、提名和工作分工有不同安排，孵化项目还需要结合 Incubator 的制度理解。

1.3 公开、异步、可追溯

Apache 社区强调公开协作与可归档的讨论。项目可能在 GitHub、邮件列表、问题跟踪器、即时聊天或会议中工作。关键是让受影响的人能够看到提案、理解理由并参与决定，而不是让少数在同一时区、同一公司的参与者提前定案。

“如果没有发生在邮件列表上，就没有发生”是一句常见文化表达，不宜机械解释为任何项目都只能用邮件处理所有事情。你应该查阅项目规定的正式讨论与决策渠道。会议可以加速理解，但应把结论、争议与后续动作带回正式公开渠道，留出异步回应机会。

公开也有边界。未披露漏洞、个人隐私、人员任命等敏感事务可以需要保密处理。治理的难点不是“所有内容都公开”，而是知道哪些应公开、哪些应保护，以及何时可以披露。

本章行动：在目标项目官网找到贡献指南、开发讨论渠道、问题跟踪器、发布页和安全入口。把这五个入口存成一张个人导航卡。

参考：ASF 如何运作。

第二章 选择一个可以长期参与的项目

2.1 从真实使用场景出发

不要先问“哪个项目最容易获得 Committer”。先问“哪个项目的问题，我愿意连续理解三个月”。一个真实使用场景能为你提供复现环境、需求判断和持续动机。比如，你用某个数据工具导入 CSV，发现文档中的命令已失效；这通常比随机寻找一个复杂调度器的性能问题更适合作为起点。

林舟先列出三个候选项目：工作中每天使用的数据工具、只读过介绍的流处理框架、朋友推荐的存储引擎。他没有立刻领 issue，而是各花半天执行一次安装和示例，观察最近的讨论与合并记录。最终他选择了第一个，因为他能判断修复是否真的改善使用体验。

2.2 用证据观察社区

建议为每个候选项目填写下表。评分是帮助自己做选择的工具，并非对社区优劣的排名。

不要只用 star 数、提交数或最后一次提交日期判断健康。基础库可能很稳定，文档工作也可能发生在另一个仓库。反过来，提交频繁不代表新人一定能得到评审。抽样阅读几次真实 review，比只看仪表盘更有价值。

2.3 顶级项目与孵化项目

ASF 的孵化项目通常称为 podling。它们正在形成可持续的社区与治理习惯，名称和发布说明通常有特定的孵化标识要求。参与 podling 可以更早接触社区建设，但也可能遇到文档和流程仍在演进的情况。

不要把“孵化”直接等同于代码质量差，也不要把“顶级项目”理解成必然适合新手。你的判断仍应落在可运行性、反馈质量、任务边界与长期兴趣上。参与孵化项目时，角色和发布投票不能直接套用顶级项目流程；PPMC、导师与 IPMC 的职责需要额外确认。

2.4 一次低成本试参与

给自己七天，而不是承诺一年。第一天完成安装，第二天跑通例子，第三天阅读一个已合并 PR，第四天复现一个问题，第五天写清复现步骤，第六天与社区确认范围，第七天决定继续还是换项目。

退出一个不合适的候选项目不意味着失败。离开前可以记录构建障碍，更新你认领任务的状态，让其他人知道你不会继续。尊重社区时间，也是在建立协作习惯。

本章产出：一页项目选择记录，包括选择理由、五个入口、最小构建命令和第一个候选问题。

参考：ASF 新人入口、Incubator 角色与职责。

第三章 在动手之前读懂协作现场

3.1 阅读顺序比阅读数量更重要

先读 README、贡献指南、行为准则和安全政策，再读你要修改模块的说明、构建配置与已有测试。不要以“必须通读整个仓库”为参与前提。你需要理解一条可以验证的路径：用户输入如何进入系统，在哪个位置产生行为，测试如何观察结果。

接着选两三个最近合并且范围相近的 PR，观察标题格式、issue 关联、测试类型、评审交流和合并方式。历史记录是项目习惯的重要证据，但若历史做法与现行规则冲突，应以现行规则为准，并向维护者确认。

3.2 订阅与第一次发言

从官网找到开发邮件列表及归档入口，按项目说明订阅。不要猜测订阅地址或私信某位看起来最活跃的维护者来索取任务。先搜索已有 issue、PR 和邮件线程，避免把同一个问题在多个地方无关联地重复发出。

第一次消息可以很短，但应包含你已经完成的工作：

主题：[Question] 文档中的 CSV 导入示例在当前版本失败

我按当前文档在某版本、某运行环境执行了导入命令，得到如下错误。最小输入与完整命令见 issue 链接。我发现示例仍使用旧参数，准备只更新这一节并验证输出。请问这个范围是否合适？

这里没有要求维护者替你从零排查，也没有承诺未经确认的大规模改造。你提供了足够事实，让对方可以快速回应。

3.3 提问是一项工程能力

一个好问题通常包含版本、环境、预期行为、实际行为、最小输入、完整步骤和已经尝试的排查。日志应经过检查，去掉令牌、真实客户数据、个人信息和内部地址。与安全有关的细节不要因为“需要完整复现”就发到公开 issue；第十章会说明私密报告路径。

如果问题暂时没有回复，可以在原线程补充新证据，或在合理间隔后礼貌跟进一次。时间间隔取决于项目节奏、问题紧迫性和是否覆盖休假，不存在所有项目通用的“过三天就升级”规则。不要把志愿者响应当作带服务等级协议的客服。

3.4 非英语母语者也能有效参与

用短句描述事实，一封消息集中解决一个问题。可以借助翻译工具整理语言，但要自行核对技术含义、版本号和引用。不要把未公开漏洞、私密邮件或凭据直接输入你无权分享数据的外部服务。

面对含糊评审，先用自己的话复述：“我理解你的意思是保留旧参数兼容性，同时给新参数增加测试，是否正确？”这比猜测后大改一遍更省时间。

本章行动：为一个非敏感问题写出可复制的复现说明，并让另一个人只按说明操作一次。若对方必须追问关键步骤，继续改进说明。

第四章 选择第一个值得合并的问题

4.1 小，不等于随意

适合首次贡献的问题有清晰的现象、有限的修改范围和明确的验收方式。例如：修复失效链接并验证目标、补全一个缺失的边界条件测试、修正文档中的命令、改进包含错误参数名的提示。

不适合作为首个任务的例子包括：没有性能测量的“大幅优化”、跨越多个子系统的重构、尚未确认语义的接口变化、没有负责人回应的庞大路线图任务。它们可能有价值，但需要更强的设计与协调基础。

good first issue 等标签只是线索。先确认问题仍存在、没有正在进行的 PR、期望行为足够清楚，再留言表达意向。是否需要正式分配由项目决定；没有分配权限通常不意味着无法贡献。

4.2 把问题写成验收条件

林舟发现文档使用旧参数 --input-file，当前版本示例要求 --input。他没有直接全库替换，而是先核实文档对应的版本、命令行帮助和兼容行为。他的验收条件是：

1. 在文档指定版本中复制示例可以执行。
2. 示例输入不依赖私人文件或外部凭据。
3. 输出与正文解释一致。
4. 修改不影响旧版本文档的正确性。

假如最终发现旧参数在该版本仍有效，问题就需要重新判断。贡献的价值来自事实，不来自一定要提交一个 diff。

4.3 非代码贡献也需要验证

文档改动要实际执行命令、检查链接和渲染；翻译需要保持术语与版本一致；issue 分诊需要确认复现并提供事实；用户支持需要区分建议与已验证结论。

避免为了留下活动记录而批量修改标点、制造低价值 PR，或未经讨论拆成大量微小请求。维护者阅读、启动 CI 和整理发布说明都需要成本。把具有同一目的的修改组织成一个可审查单元，通常比追求数量更有帮助。

本章产出：一份不超过一页的问题说明：现象、证据、边界、方案和验收条件。

第五章 从本地修复到第一个 PR

5.1 先建立干净基线

按项目说明安装工具链，记录运行时、编译器和依赖版本。先在未修改代码上执行与任务相关的测试，才能区分原有失败和新引入失败。大型项目不一定要求本机立即运行所有集成测试，但你应知道哪些验证只能由 CI 或特定环境完成。

下面是典型的 fork 工作流。仓库名和默认分支仅为占位示例，不应直接复制成真实地址：

# 先在托管平台创建自己的 fork，再替换下面地址。
git clone https://github.com/YOUR_ACCOUNT/PROJECT.git
cd PROJECT
git remote add upstream https://github.com/apache/PROJECT.git
git fetch upstream
git switch -c fix/csv-example upstream/main

若项目使用其他托管方式、默认分支或补丁提交机制，按其贡献指南操作。不要把 main 当作所有 Apache 项目的固定分支名。

5.2 一次只解决一个可解释的问题

修改之前，先定位负责该行为的代码或文档。代码修复优先补充能够暴露原问题的测试：在旧代码上失败，应用修复后通过，同时说明失败与问题之间的关系。文档修复则以可执行命令和渲染检查作为证据，不必为了简单文本修改构造与实现重复的测试。

避免顺手格式化整个文件、升级无关依赖或修复旁边的另一个问题。这些变化会扩大评审范围，也让回滚更困难。若必须同时修改公共接口和调用方，解释它们为什么构成一个不可拆分的行为变更。

提交前至少查看：

git diff --check
git diff
git status --short

git diff --check 只能发现部分空白问题，不能证明代码正确。你仍需运行目标测试、文档构建或实际复现。不要把生成文件、缓存、个人配置和敏感数据带入提交。

5.3 提交、推送与请求评审

git add docs/csv-import.md
git commit -m "Fix CSV import example for current CLI"
git push -u origin fix/csv-example

是否需要签署提交、DCO、特定标题、issue 编号或其他检查，由项目规则决定。ASF 的 ICLA 与某些社区使用的 DCO 是不同机制，不能互相替代，也不要假设所有首次 PR 都必须先走同一套手续。

一个可以直接改写的 PR 描述如下：

文档中的 CSV 导入示例使用了旧参数，按当前版本执行会报未知参数错误。本次将示例改为当前参数，并提供可直接创建的最小输入。

验证：在文档指定版本运行更新后的完整命令，确认导入两行记录；文档构建通过。相关 issue：填写实际链接。

范围：只修改当前版本示例。若旧版本文档也需要修复，将另行核对。

实际描述必须如实报告。没有跑某项测试，就写明未运行及原因，不能把“CI 应该会测”写成“验证通过”。

5.4 知识产权与贡献来源

只提交你有权提供的内容。工作时间产生的代码、从其他项目复制的片段、第三方图片和生成材料，都可能涉及雇佣合同、许可证或来源证明。不要因为网上能看到就认定可以复制。

ICLA 是个人贡献者许可协议，涉及贡献者授予 ASF 的相关权利；CCLA 可处理企业层面的相关安排。是否需要企业授权，应结合实际雇佣与权利关系、ASF 说明以及必要的法律意见判断。签署 ICLA 不会自动授予 Committer 身份，项目也不应把它当作晋升申请表。

涉及第三方依赖时，检查其许可证及 ASF 的兼容要求；是否需要调整 LICENSE、NOTICE 或分发内容，取决于实际引入和发布方式。不要把“加上来源链接”当成完成全部合规工作。

参考：贡献者协议。

第六章 评审、修改和合并之后

6.1 把评论转化为可验证的修改

收到 review 后，先区分必须修复的问题、需要澄清的设计意见与可选建议。逐项回应：“已增加空输入测试，旧行为会抛出异常，修复后返回空结果。”这样的回复比一律写“done”更容易复核。

如果你不同意，提出具体约束、数据或替代方案。不要以“我已经写好了”为设计理由，也不要把对代码的批评理解成对人的评价。双方仍然不一致时，可以总结分歧，带到项目规定的公开讨论渠道。

6.2 CI 失败不总是你的错，但需要调查

先阅读失败日志，判断是编译、测试、格式、许可证检查、文档、环境还是超时。将当前分支与基线表现比较。疑似偶发失败时，提供历史失败链接或可重复实验，遵循项目的重跑规则；不要为了绿灯无限点击重试。

若需要同步上游，根据项目习惯使用 merge 或 rebase。rebase 会改写你分支的提交历史，若已推送，更新前确认没有其他人在该分支协作，必要时用 git push --force-with-lease 并解释原因。不要对共享分支盲目强制推送。

6.3 没有合并也可以有成果

维护者可能认为问题应在别处解决，或者更小的改动已经覆盖需求。记录决策理由，关闭或调整 PR。一个认真排除错误方向的讨论，也能减少后续维护成本。

如果长期无人回复，可以在原 PR 总结当前状态，链接最关键证据，再到项目允许的渠道请求评审。不要群发私信、每天催促或用赞助关系施压。你可以选择暂停，并清楚说明是否欢迎他人接手。

6.4 合并不是终点

确认合并到哪个分支，跟踪相关 CI 和是否需要补充发布说明。不要把“PR 合并”描述成“用户已经可以在正式版本使用”。修复何时进入发布、是否回移维护分支，由项目维护策略决定。

如果合并后出现回归，尽快公开说明受影响范围、复现步骤和候选解决方案。小范围回滚有时比追加复杂修复更稳妥，但应遵守项目权限与评审流程。

完整练习：选择一个非安全问题，提交包含证据的 issue；形成小范围修改；完成实际验证；写出 PR 描述；模拟回应两条评审意见；说明合并后的跟踪动作。练习的完成标准是他人能复核你的工作，不是必须在某个期限内获得合并。

第七章 持续贡献：让别人愿意与你共同维护

7.1 从交付修改到承担问题

稳定贡献并不等于每周必须提交代码。你可以定期复现新问题、检查发布候选、更新文档、帮助用户，或评审熟悉模块的小改动。长期价值来自让别人能依靠你的判断：你说已经验证，就有命令和结果；你不能继续，就及时交接；你不确定，就明确标注。

林舟的第二个月没有增加很多 PR。他帮助确认了三个用户问题，其中一个是配置错误，一个是已修复的旧版本行为，一个才是新缺陷。他把判断与证据分别写回线程，减少了重复排查。这种工作同样帮助项目持续运转。

7.2 开始做评审

即使没有写权限，也可以提供 review。先声明自己验证了什么：读过某部分代码、运行过某组测试，还是只检查了文档。不要用一个赞同表情暗示自己完成了全面安全与兼容性审查。

有效评审可以沿着四个问题展开：修改是否解决原问题，是否引入新的边界情况，验证是否能防止回归，读者能否理解行为变化。遇到不熟悉的模块，提出具体问题比给出绝对判断更可靠。

7.3 让知识可以被接手

把搭建环境的坑、模块约束和常见故障写进项目认可的位置。不要让所有信息留在私人聊天中。处理一个任务时，留下已知事实、未解决问题和下一步，而不是只留下“还在看”。

当贡献与公司目标重合时，提前说明资源承诺和约束。不要代表公司承诺自己无法控制的维护期限，也不要让社区误以为某项工作永远有人付费维护。

7.4 一份可持续的九十天安排

前两周完成项目试参与与环境搭建；第三至四周完成一个范围明确的贡献；第二个月重复完整协作流程，并开始帮助分诊或评审；第三个月选择一个小领域持续跟进，整理文档和交接材料。

这份安排是学习计划，不是 Committer 倒计时。每周只投入两小时的人，也可以通过可靠的积累成为重要参与者。避免为了身份过量承诺，最后消耗自己与维护者。

本章复盘：列出最近三次你帮助别人做出更好判断的事实。如果记录里只有 PR 数量，试着补充验证、解释、支持和交接的证据。

第八章 成为 Committer：信任如何变成责任

8.1 没有统一的数量门槛

ASF 没有适用于所有项目的“合并十个 PR 自动成为 Committer”规则。项目通常根据持续贡献、判断力、协作方式和社区需要，由有权限的成员依照项目与 ASF 流程提出并讨论邀请。评估往往包含代码之外的工作，也可能发生在私密渠道，避免对候选人造成不必要压力。

你可以询问如何提升贡献质量，或者表达愿意承担更多维护工作，但不要要求别人保证某个日期授予身份。不同项目的任务、人员和权限安排不同，不能用另一项目的速度判断自己是否被认可。

8.2 收到邀请之后

仔细阅读邀请，了解授权范围、预期责任和后续流程。通常会涉及接受邀请、按要求提交或确认 ICLA、选择账户标识、完成账户开通，以及阅读安全与基础设施使用要求。操作顺序和办理人员以实际邀请和官方指南为准，不要自行发起不需要的账户请求。

签署文件前核实姓名、联系信息和权利来源，特别是雇佣环境中的贡献授权。不要把协议、账户创建和权限授予混成同一件事：它们各有目的，也可能由不同的人办理。

8.3 有写权限之后更需要克制

首先启用平台要求的多因素认证，保护恢复代码，按规定管理 SSH 密钥和令牌。为不同用途采用最小权限，不把凭据放入代码、日志或共享文档。离开一台机器或发现泄露时及时撤销相关凭据，而不只是从文件里删掉字符串。

熟悉项目对合并、评审、分支保护、回移和发布的规定。有的项目允许特定范围的先提交后评审，有的要求先评审；获得写权限不意味着可以忽略现行流程。对影响大或自己不熟悉的改动，应主动邀请他人审查。

对新人保持耐心。你曾经不知道的命令、缩写和规则，下一位贡献者也可能不知道。指出问题时解释原因，给出可执行的下一步，避免用权限优势结束合理讨论。

8.4 第一个月的维护练习

选择一次熟悉模块的评审，记录验证范围；帮助一位新人复现问题；参与一次发布候选验证；了解如何报告凭据泄露和安全问题；明确自己暂时不能独立批准的事项。这些动作比立即合并大量 PR 更能帮助你适应责任。

参考：新 Committer 指南。

第九章 从 Committer 到 PMC：照顾整个项目

9.1 从模块正确走向项目健康

PMC 的职责包括监督项目的技术与社区活动，确保发布与基金会政策相符，维持开放协作与可持续维护，并按要求向董事会报告。PMC 成员仍可以写代码，但职责不能只缩小为自己负责的模块。

你需要关注一些难以用提交数衡量的信号：重要决策是否只有一家公司参与，新人是否能得到解释，发布是否依赖唯一一人的机器，安全邮箱是否有人值守，长期争议是否无人协调。

9.2 任命不是自动升级

Committer 与 PMC member 不是同义词。是否邀请某位 Committer 加入 PMC，取决于其对项目整体的判断、责任承担与社区需要，并按照现行正式程序办理。顶级项目 PMC 的成员变更需要遵循 ASF 关于 PMC 变更的流程；不能把 GitHub 权限调整或一封欢迎邮件当作全部程序完成。

PMC Chair 是协调和对接董事会的重要角色，并不拥有超越社区规则的任意技术裁决权。ASF Member 又是基金会层面的身份，不应与 PMC 或 Chair 混淆。

孵化项目的 PPMC、导师与 IPMC 在监督、任命和发布中的职责不同于顶级项目。不要把“PPMC 的内部同意”直接当成所有基金会层面手续已完成。

9.3 董事会报告与实际治理

好的报告不是提交数列表，而是帮助董事会理解项目是否健康：近期活动、发布状态、社区人员变化、重要风险、未解决问题与需要帮助的事项。按现行报告节奏和模板提交，数字应有依据，不要用模糊的“社区很好”掩盖无人维护的关键环节。

可以维护一份内部工作清单：报告截止日期、发布准备、安全联系人、人员流程、基础设施依赖与待解决冲突。涉及隐私和安全的细节放在授权位置，公开报告保持适当范围。

9.4 可持续性需要主动设计

如果只有一人会签名发布，就让第二个人实际完成一次候选构建与验证；如果所有设计都在同一家公司会议里形成，就把方案提前带到公开渠道；如果新人不断在同一步失败，就修正文档和工具。

PMC 不必亲自完成所有任务，但应关注这些任务是否有人承担、是否可以交接。没有精力时及时寻求帮助，比维持“看起来有人负责”的状态更负责任。

参考：PMC 指南、ASF 如何运作。

第十章 安全报告：从私密接收到协调披露

10.1 发现疑似漏洞时的第一步

如果问题可能造成越权、敏感信息泄露、远程代码执行、重大可用性影响或其他安全后果，先查目标项目官网的安全政策、SECURITY.md 和 ASF 安全入口。按其中列出的私密渠道报告；如果找不到合适入口，可使用 ASF 官方安全页面给出的报告方式寻求分流。

不要把可利用细节、真实凭据或完整攻击样例发到公开 issue，也不要默认任何名为 security 的 GitHub 功能都已被项目启用并有人处理。不能用本书的示例邮箱替代真实官方地址。

对不确定的情况，可以先私密说明现象和潜在影响，请维护团队判断。这比自行公开一个尚未核实的高危标题更有帮助。

10.2 一份最小而充分的私密报告

报告可以使用以下结构：

• 项目、受影响版本、安装与运行方式。
• 预期的安全边界，以及实际越过了哪一条边界。
• 最小复现步骤、必要配置和观察到的结果。
• 攻击者需要的权限、网络位置和用户交互。
• 已确认的影响与尚未验证的推测。
• 你的联系信息、是否愿意署名致谢，以及是否已有披露安排。

复现应在你拥有授权的环境中进行。报告不需要附带从真实受害者取得的数据，也不应以持续测试公共部署作为“证明”。提供足以定位问题的最小材料即可；敏感附件按项目建议的安全方式传递。

10.3 维护者收到报告后的工作流

第一步是确认收到并建立私密记录，指定负责人和备份联系人，限制访问到需要参与的人。不要在公开聊天里转贴报告来找帮手。若问题发错项目，按安全流程协调分流，而不是直接转发给无关公开列表。

第二步是复现和分类。记录受影响版本、配置前提、攻击条件与影响范围，区分产品漏洞、使用错误和第三方依赖问题。不要仅因默认配置不受影响就立即排除，也不要把未经证实的影响写成事实。

第三步是与 ASF 安全团队及相关维护者协调，按当前流程办理漏洞追踪、CVE 和公告材料。CVE 编号不是严重性的证明，也不是每份报告都必须获得一个编号；编号与信息发布应按 ASF 当前作为 CNA 等相关安排处理，不要自行制造占位编号。

当前官方流程提供内部 CVE 门户，也支持通过 ASF 安全团队申请与协调编号。没有专用项目安全列表时，相关后续沟通应按官方流程抄送 ASF 安全团队；官方项目安全列表会自动抄送，不必重复添加。发布前应向报告者提供修复与公告草稿，协调修复和披露时间。

第四步是准备修复、测试、版本范围和缓解措施。修复代码、分支名、提交消息、CI 日志、预览站点和发布说明都可能泄露信息，选择工具前需要考虑可见性与访问权限。不要在公开 PR 标题里写明未披露的利用链。

第五步是完成适用的发布流程，并协调公告时机。ASF 正式发布仍须符合公开发布政策；安全保密需求不能被理解为可以跳过发布投票或把秘密二进制称为正式 Apache 发布。如何减少准备过程的信息泄露，需要项目与 ASF 安全团队共同安排。

提交修复时，当前官方指南要求不要在提交中指明其安全漏洞性质；这不等于承诺公开代码不会被人推断出问题，故仍需协调时机。

第六步是在发布公告之后或同时发布安全公告，按官方流程通知发布公告渠道、报告者、项目安全列表及 oss-security，更新项目安全页面和 CVE 记录。公告写清受影响与修复版本、前提条件、用户操作、缓解限制和致谢，并在协调后更新关联记录。最后复盘响应、修复和沟通中的问题。

10.4 一个虚构案例的时间线

林舟收到私密报告：一个可选导入接口在特定认证配置下允许读取其他租户的任务结果。他先确认收到，询问最小配置，在授权测试环境中复现，并找另一位维护者交叉核对。两人发现默认配置不受影响，但文档支持的某种配置受影响，因此不能以“默认安全”为由忽略。

团队在授权渠道记录版本范围，与 ASF 安全团队协调。修复不仅增加权限检查，也补充跨租户的回归测试，并核对旧维护分支。公告草稿解释了哪些部署需要升级、临时禁用接口能缓解什么、不能缓解什么。

发布准备与公告时机由相关团队协调，正式发布按 ASF 政策完成。发布后团队检查公告链接和版本说明是否一致，并向报告者确认致谢文字。这个案例没有规定“必须在七天内修复”：响应期限应结合实际风险、协调安排和适用规则判断。

10.5 已经公开了怎么办

若报告者已公开细节或误把秘密发进 issue，不能假装仍处于完整保密状态。立即通知项目安全负责人和 ASF 安全团队，评估已暴露的内容、是否需要临时提示或缓解措施。删除公开内容不保证所有副本消失；凭据泄露必须撤销或轮换，不能只删提交。

对报告者保持尊重，清楚解释协调需要。不要承诺无法兑现的赏金、修复期限或法律结果。公开公告应以已确认事实为基础，避免在紧急情况下扩大未经验证的说法。

安全演练：用完全虚构、无可用利用载荷的案例，检查项目是否能找到私密入口、确认值班者、保存受限记录、协调修复与发布，并形成用户能采取行动的公告。

参考：ASF 安全入口、Committer 安全处理指南。

第十一章 发布：把代码变成可以被信任的交付

11.1 合并、构建和发布是三件事

Git 仓库里存在一份代码，不代表它已经成为正式发布。CI 生成的快照、供开发者测试的候选构建和获得适当批准的正式发布，必须清楚区分。用户需要知道自己下载的是什么、来自哪里，以及如何验证。

Apache 的发布政策以源码发布为核心。项目也可能提供便利二进制包，但不能用二进制文件代替对源代码发布的要求。应检查许可证、通知文件、第三方内容、构建说明、版本标识和发布材料是否满足当前政策。

11.2 Release Manager 的工作

发布经理负责组织过程：确认范围、准备候选、给出验证方法、发起投票、汇总结果和执行获批后的分发步骤。发布经理不是唯一验证者，也不能以“我已经跑过测试”代替社区审查。

第一次参与发布，可以从复现候选源码构建开始。记录下载来源、校验与签名验证结果、工具链版本、运行命令和测试输出。签名验证说明文件与所用密钥的关系，密钥是否可信还需要核实身份与官方发布说明，不能只看工具显示一行成功。

11.3 发布投票中的关键边界

ASF 正式发布需要按发布政策进行批准。一般的发布批准要求至少三张有效的 binding +1，赞成票多于反对票，并满足适用的投票时长要求；现行政策通常建议至少开放 72 小时；特殊情况下可以加急，但缩短时长的投票邮件必须解释原因，并按政策向董事会报告，不能由发布经理默默缩短。执行前仍应核对现行政策与项目安排。顶级项目的 binding 发布票通常来自该 PMC；孵化发布需要结合 IPMC 的批准规则，不能只按 PPMC 内部投票计算。

投出 binding +1 前，现行发布政策要求个人把所有签名源码包下载到自己的硬件，核对政策要求、验证密码学签名、按所提供方式编译并在自己的平台测试。不要以他人的绿灯代替自己必须完成的验证。

发布投票不是代码变更的否决制度。一个 -1 不会自动构成不可越过的发布 veto，但指出的许可证、来源、安全或可构建性问题必须认真处理。不要仅凭数字过线就忽略实质问题。候选内容若改变，通常需要新的候选与适当重新验证，不能让大家验证一份内容后再悄悄替换。

非 binding 验证同样有价值。即使你不是 PMC 成员，也可以提供完整测试结果，帮助发现平台兼容、文档或依赖问题；只是不能把你的投票计入不适用的正式资格统计。

11.4 发布之后

按项目和 ASF 的分发要求处理下载位置、归档、公告和网站更新。公告链接应指向正确版本，包含适用的验证说明。安全发布还应与第十章的协调披露计划保持一致。

保留发布记录和构建说明，逐步减少对某个人、本地机器或私有配置的依赖。真正可持续的发布，是下一位维护者也能据此完成的发布。

参考：ASF 发布政策、投票规则。

第十二章 社区治理：让分歧可以被处理

12.1 先形成理解，再选择决策机制

大部分技术工作应先讨论问题、约束和可选方案，努力形成共识。投票不是快速结束争论的万能按钮。一个尚未明确兼容代价的提案，即使得到很多 +1，也可能留下严重维护问题。

懒共识（lazy consensus）适合项目规则允许、风险可控且可逆的事项：提案清楚列出动作、理由与回应窗口，在没有有效反对时推进。不能把无人看到的消息当成共识，也不能用懒共识代替正式发布或任命所需的程序。

12.2 不同投票不能套用同一种算法

技术 veto 应给出有效的技术理由，并按适用流程讨论和解决。不能用个人不喜欢、公司利益或商业竞争代替技术论据。反过来，也不能因为对方只占少数就忽略其指出的真实兼容性或正确性问题。遇到争议先查当前规则，确认事项类型和有资格的参与者。

12.3 一场设计争议的处理

林舟希望删除旧接口，因为维护成本高；另一位贡献者担心用户迁移。双方各自重复观点没有进展，于是把问题拆成可验证事实：哪些版本仍在支持、使用者有没有替代方案、保留兼容层的成本多大、需要怎样的弃用窗口。

他们写出三个方案：立即删除、标记弃用后移除、保留接口但限制新功能。讨论记录分别列出用户影响、测试成本与后续责任人。最终方案通过项目规定的方式确认，决定及理由保存在正式渠道，而不只是在两人的聊天窗口里。

这不是追求永远没有分歧，而是让不同观点能改善决策，并让未来维护者理解为何如此。

12.4 处理冲突、失礼和权力失衡

先区分事实分歧与行为问题。代码意见可以尖锐，但人身攻击、骚扰、歧视或持续威胁不应被包装成技术直率。按照项目与 ASF 行为准则的报告路径处理，保存必要证据并保护相关人员隐私；涉及敏感行为报告时，不要要求当事人先在公开邮件列表上自证。

如果你是 PMC 成员或长期维护者，要特别留意自己的话会产生怎样的权力效果。与自己存在雇佣、商业或私人利益关系的事项，应主动披露，必要时回避相关决定。不能用“我是 Committer”代替解释。

12.5 公司占比与社区独立性

某家公司贡献多，不自动意味着治理失败；关键是其他人能否获得信息、提出方案、参与评审和承担角色。如果路线图在公司内部确定后只要求社区背书，或离职员工被要求带走所有知识，项目就面临独立性与连续性风险。

可执行的改进包括：提前公开设计，记录会议，轮换主持和发布工作，让不同雇主及独立参与者有实际接手机会，为关键任务建立第二位负责人。不要为了表面多样性把邀请变成配额游戏，仍需关注个人贡献与责任。

本章演练：选择一个虚构争议，写出问题、事实、方案、利益关系、讨论渠道、适用决策机制与结果记录位置。先能解释“为什么采用这一机制”，再考虑发起投票。

参考：投票规则、ASF 行为准则。

第十三章 把路线变成自己的行动手册

13.1 你的第一个完整循环

用一周选择项目，用一次可运行示例建立信心，用一个边界清晰的问题进入协作。提交之后认真处理 review，合并之后观察真实效果。重复这样的循环，逐步扩大自己能判断的范围。

不要急着把所有角色写进个人时间表。Contributor 的核心是提供可复核的帮助；Committer 的核心是正确使用信任；PMC 的核心是照顾项目整体。它们之间的联系来自责任，而不是身份焦虑。

13.2 六张可以长期更新的记录

第一张是项目导航卡，保存正式入口。第二张是环境卡，保存可以复现的构建步骤。第三张是贡献记录，说明问题、修改、验证和后续结果。第四张是知识地图，标注自己熟悉与不熟悉的模块。第五张是交接记录，列出未完成事项和负责人。第六张是治理观察，记录哪些流程顺畅、哪些依赖单个人。

记录应放在合适位置。个人学习笔记可以本地保存，公共操作知识应尽量回馈社区，安全与人员信息只能存放于适当受限的渠道。不要因为“方便整理”而把不同保密级别的材料混进公开仓库。

13.3 衡量自己的进步

每个月问自己：我是否让一个问题更容易复现，是否帮一个人理解了项目，是否减少了一项隐性知识，是否让某个决定更透明，是否对不确定性保持诚实？这些问题没有统一分数，却比只数提交更接近开源协作的实际价值。

你不需要等到成为 PMC 才开始实践治理，也不需要等到成为 Committer 才能帮助评审。现在就可以把问题写清楚，把验证做好，把讨论留在正确的位置，把工作交给下一个能继续的人。

附录 A 可复制模板

A.1 项目选择卡

项目名称与官方网站：
为什么与我的真实使用有关：
贡献指南 / 开发讨论 / issue / 发布 / 安全入口：
最小构建命令与工具版本：
近期相似贡献的评审例子：
候选问题与复现证据：
每周可投入时间：
继续参与或换项目的判断日期：

A.2 非敏感问题报告

标题：准确描述可观察的行为
项目版本、操作系统、运行时：
预期行为：
实际行为：
最小输入与执行步骤：
错误输出（已清除秘密与个人信息）：
已尝试的排查：
可能相关的 issue / PR / 文档：

若怀疑涉及安全边界，不要使用公开模板提交，改走正式私密安全入口。

A.3 PR 描述

问题：什么情况下发生，影响是什么？
修改：如何改变行为，为什么采用这一方案？
验证：实际运行的命令、版本、结果；未运行项目及原因。
兼容性：配置、接口、数据格式或升级行为是否变化？
关联：issue / 设计讨论 / 文档链接。

A.4 请求评审

我已按上次意见更新该 PR，主要增加了……。
实际验证结果为……，仍未验证的范围是……。
目前最需要确认的是……。
相关上下文与最新修改见……。

A.5 发布候选验证记录

候选标识与正式投票线程：
源码取得位置、摘要与签名核验：
核实密钥来源的方式：
操作系统、编译器与运行时：
构建命令与测试命令：
通过 / 失败 / 未验证项目：
许可证、通知、第三方内容检查范围：
发现的问题与复现证据：
是否为 binding：按当前资格如实说明。

A.6 治理提案

要解决的问题与现状证据：
受影响的人与兼容性：
候选方案及取舍：
资源承诺和利益关系：
正式讨论渠道与回应窗口：
适用的决策规则及其官方依据：
实施、回滚与后续检查方式：
决定与理由的归档位置：

附录 B 术语速查

附录 C 官方资料与核对方法

以下是本书的主要制度依据。网址可能迁移，阅读时可从 ASF 官方站点重新定位。网页被本地保存只用于核对与编辑，不表示本书有权重新许可这些页面。政策摘要不能代替原文。

1. How the ASF works：组织、个人参与和角色。对应第一、八、九章。
2. Getting Started / Newcomers：新人参与入口。对应第二、三章。
3. New Committer Guide：邀请后的工作与账户流程。对应第八章。
4. PMC Guide：PMC 职责与运作。对应第九章。
5. Voting：不同事项的投票、共识与否决边界。对应第十一、十二章。
6. ASF Security：安全报告入口与通用信息。对应第十章。
7. Security for Committers：维护者安全处理流程。对应第十章。
8. Release Policy：正式发布、源码和批准要求。对应第十一章。
9. Contributor Agreements：ICLA 与 CCLA。对应第五、八章。
10. Code of Conduct：参与行为及报告路径。对应第三、十二章。
11. Incubator Roles and Responsibilities：孵化相关角色。对应第二、九、十一章。

执行重要操作前，请按以下顺序核对：先读当前 ASF 官方规则，再读目标项目的现行指南；确认自己处理的事项类型和权限；若发现矛盾，在适当渠道询问有责任处理的人；保存决定依据和执行记录。尤其不要仅凭搜索摘要、旧邮件或本书中的概括完成任命、发布或安全披露。

附录 D 学习验收与场景练习

完成阅读后，可以用下列问题检查自己是否已经具备实践能力。答案不要求背诵术语，而要求说明行动和证据。

1. 一个项目采用 Apache License 2.0，是否一定属于 ASF？你会去哪里确认？
2. 最近一周没有提交，是否说明社区不活跃？你还会查看哪些证据？
3. 你修正了一条命令，如何证明文档变得可用，而不只是语句更顺？
4. CI 失败但你怀疑是旧问题，如何给出可复核的判断？
5. PR 合并之后，为什么不能直接告诉用户正式版本已修复？
6. 已签 ICLA 是否意味着成为 Committer？写权限和治理责任有何不同？
7. 不是 PMC 成员，能否验证发布候选？如何表达你的验证范围与票的性质？
8. 发布投票与代码变更的 veto 机制有什么区别？你将核对哪份正式规则？
9. 疑似越权问题应发到哪里？如果已经公开，接下来如何协调？
10. 同一公司的参与者事先定好了设计，怎样让社区仍有实际参与机会？

可参考的判断方向：许可证与组织归属分别核实；社区活动需要多渠道证据；验证应包含真实执行；区分基线失败与新增失败；合并与发布分开；协议与授权分开；验证价值与正式投票资格分开；先区分事项再适用规则；安全问题走官方私密入口并在泄露时及时协调；把设计、理由与可修改空间提前交给正式公开讨论。

最后，选择其中一个场景，写出“我知道什么、还不知道什么、下一步去哪里核对、执行后留下什么记录”。当你能稳定做到这四点，参与 Apache 开源就已经从模糊的愿望变成可持续的实践。