open-sourcing

开源发布仓库

为公开发布做好仓库准备，让没有背景信息的外部人员也能构建、使用并为其做出贡献，同时确保仓库中不包含任何敏感信息。按顺序完成以下步骤；首先进行机密信息审计，因为审计结果（保留还是重新创建仓库）会影响之后的所有工作。

适用场景

• 将私有仓库设为公开
• 审计现有公开仓库的发布质量（“正式发布”）
• 为项目选择许可证
• 在公开发布前设置打包、版本管理或发布自动化

不适用场景

• 对已发布项目进行日常开发（没有发布事件）
• 审计第三方代码中的漏洞（使用安全审查技能）
• 从将继续保持私有的仓库发布软件包——只需执行发布管理相关步骤，跳过其余部分

工作流

步骤 1：检测组织配置

bash {baseDir}/scripts/detect_org.sh

此脚本会检查 git 远程地址和近期提交者的邮箱，并输出一个配置名称。如果输出 trailofbits，请立即阅读 references/trailofbits.md，并在之后的步骤中遵循其中的许可证政策、发布账号和流程说明。如果输出 generic，则只遵循通用指南。如果用户表示检测结果有误，以用户的说法为准。

步骤 2：审计机密信息——必须先于其他一切操作

曾经包含过机密信息（API 密钥、凭据、客户端数据）的仓库不应直接改为公开。重写历史容易出错，而且无法覆盖分叉、缓存或 CI 产物。可靠的做法是创建一个全新的仓库：复制当前文件树，将其提交，然后将旧仓库归档并设为私有。

1. 询问项目是否曾处理过机密信息或客户端保密材料。对于安全咨询公司的工具，还要询问测试夹具或示例数据是否来自客户项目。
2. 如果有专用工具，请使用它扫描完整历史——例如 gitleaks git . 或 trufflehog git file://.——不要仅凭目测检查。
3. 检查 git 文件树以外的内容：GitHub Actions 日志和产物、旧版本、议题与 PR 历史，以及仓库 wiki 都会随仓库一起公开。
4. 公开后，在仓库设置中启用 GitHub 机密信息扫描和推送保护。

请拒绝以下说辞——发布之后，这一步无法补救：

• “密钥已撤销，所以历史记录没问题。” 已撤销的凭据仍会泄露基础设施名称、内部 URL，以及攻击者用于确定目标的模式。
• “我们会用 git-filter-repo 重写历史。” 重写无法覆盖分叉、克隆、副本缓存和 CI 产物；创建全新仓库则不会有这个问题。
• “这只是测试数据。” 源自客户项目或生产系统的测试夹具，无论如何标注都属于机密信息。

步骤 3：运行就绪情况检查

bash {baseDir}/scripts/check_readiness.sh

此脚本会打印一份就绪情况清单，列出各项是否存在（README、LICENSE、CONTRIBUTING、SECURITY.md、CI、测试、semver 标签等），并警告仓库中已跟踪的、通常会包含机密信息的文件。请将未勾选的项目视为讨论事项，而不是硬性要求——研究原型并不需要具备旗舰级库所需的一切。与用户逐项讨论缺失项，并修复对该项目重要的问题。

第 4 步：文档

README 是项目的门面。请确认其中说明了：

• 项目是什么以及它解决了什么问题（第一段）
• 如何安装——使用包管理器、容器镜像或从源码构建；仅使用仓库中的内容就必须能够完成全新克隆后的构建
• 如何使用——至少提供一个具体、可复制粘贴的示例
• 如何贡献——在 README 中说明或通过 CONTRIBUTING.md 说明
• 许可证——用简短的章节注明许可证名称

此外，还要添加：

• SECURITY.md，其中包含漏洞报告说明（联系地址或 GitHub 私密漏洞报告功能）。对于安全工具而言，这是基本要求。
• API 文档，构建并托管该文档（通常通过 CI 使用 GitHub Pages），并在 README 和仓库网站字段中添加链接。各生态系统的文档工具请参阅下方的语言参考。
• 如果项目希望接受外部贡献者，请添加行为准则。

第 5 步：许可

没有许可证就不算开源，无论项目是否公开可见。请阅读 references/licensing.md，了解选择标准和操作流程。简而言之：

1. 如果第 1 步中发现了组织的政策，请遵循该政策。
2. 否则：默认采用宽松的 Apache 2.0；如果确实担心竞争对手进行私有修改，则采用 AGPLv3；非代码类作品采用 Creative Commons。
3. 添加 LICENSE 文件，在软件包元数据中设置 SPDX 标识符，在 README 中注明许可证，并确认三者一致。

第 6 步：测试和 CI

• 确认测试套件存在且通过；公开仓库的默认分支如果测试失败，就会给人项目已被弃用的印象。
• 确保 CI 在每个 PR 上运行测试，并覆盖受支持的语言版本和平台组合。
• 在 CI 中执行格式检查和代码检查（各语言对应的工具见下方参考），避免风格争论进入代码审查。
• 尊重现有工具。 不要为了开源而替换仍在正常工作的格式化工具、代码检查工具或类型检查器。如果它们落后于当前一代工具（语言参考中会列出当前工具），请提醒维护者并让他们决定；只有某一类工具完全缺失——没有类型检查器或没有格式化工具——时，才添加当前的默认工具。
• 可以考虑设置覆盖率门槛，在覆盖率下降时让 CI 失败。
• 在工作流成为公开攻击面之前加固它们：
  • 将第三方 Actions 固定到完整的提交 SHA；为 github-actions 启用 Dependabot，以便及时更新固定版本。
  • 设置最低权限的 permissions: 区块（从 permissions: {} 开始）。
  • 使用 zizmor .github/workflows/ 进行审计，并使用 actionlint 检查。

第 7 步：仓库设置

• 默认分支的分支保护：禁止强制推送，必须通过 PR 提交。新仓库优先使用规则集；经典分支保护仍受支持。
• 合并保护：设置必需的状态检查，确保测试失败的 PR 无法合并。
• 使用 Dependabot 或 Renovate 更新依赖项和 Actions。将更新分组以减少 PR 噪声，并设置冷却期（例如 7 天），让刚发布——偶尔也可能被劫持——的版本在采用前经过一段时间。
• 添加 .editorconfig，确保贡献者使用的编辑器在空白字符等基础设置上保持一致。
• 标签：当需要为多个 issue 或 PR 添加标签时，立即创建标签；使用前缀表示类别，便于扩展（C: 表示组件，P: 表示平台）。可参阅 blight 的标签，了解一个实际示例。

第 8 步：发布与版本管理

• 为每个版本标记为 vX.Y.Z，遵循 semver；发布候选版本和预发布版本使用 -rc.N / -pre.N 后缀。
• 通过 CI 驱动发布：推送标签（或发布 GitHub Release）后，自动触发构建、打包和上传，无需手动操作。发布流程应为 git tag vX.Y.Z && git push origin vX.Y.Z。
• 使用组织所有的账号发布包，而非个人账号；只要软件包索引支持，就使用可信发布（OIDC），而非长期有效的令牌。

第 9 步：特定语言的实践

根据项目的标记文件确定所用语言，并阅读相应参考文档，了解打包、发布和质量工具：

标记文件	参考文档
pyproject.toml、setup.py	references/python.md — 工具配置遵循 modern-python 技能
CMakeLists.txt、Makefile（C/C++）	references/c-cpp.md
Cargo.toml	references/rust.md
go.mod	references/go.md
package.json	references/javascript.md
Gemfile、*.gemspec	references/ruby.md

对于其他生态系统，请应用通用原则：从全新克隆的仓库进行可复现构建、由 CI 驱动发布、使用可信发布或组织所有的账号，并在软件包清单中提供许可证元数据。

最终检查

在切换可见性设置之前，请从外部人员的角度进行验证：

1. 将仓库克隆到一个干净目录，并严格按照 README 中的构建说明操作——无需任何非公开的经验知识也能成功吗？
2. 重新运行 {baseDir}/scripts/check_readiness.sh，并确认剩余的缺口都是经过审慎决定的选择，且已向用户说明。
3. 确认确实执行了密钥审计（第 2 步）；这是发布后无法补救的唯一一步。

将仓库设为公开只需更改仓库设置。如果组织有相关流程，请同时发布公告。

附加资源

参考文件

• references/licensing.md — 许可证选择标准、SPDX 元数据、分叉与重新许可
• references/trailofbits.md — Trail of Bits 策略补充规则（仅在第 1 步检测到时加载）
• references/python.md、 references/c-cpp.md、 references/rust.md、 references/go.md、 references/javascript.md、 references/ruby.md — 各语言的打包、发布和质量工具

脚本

• scripts/detect_org.sh — 根据 git 远程地址和提交者电子邮件，打印组织配置（trailofbits 或 generic）
• scripts/check_readiness.sh — 打印发布就绪文件的存在情况，并标记通常可能包含密钥的已跟踪文件