open-sourcing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Open-Sourcing a Repository

开源仓库准备指南

Prepare a repository for public release so that an outsider with no prior context can build, use, and contribute to it — and so that nothing sensitive ships with it. Work through the steps in order; the secrets audit comes first because its outcome (keeping vs. recreating the repository) affects everything after it.

为公开发布准备仓库，让没有前置背景的外部人员能够构建、使用并为其做贡献，同时确保没有敏感内容随发布流出。请按顺序完成步骤；秘密审计是第一步，因为其结果（保留还是重新创建仓库）会影响后续所有步骤。

When to Use

使用场景

Making a private repository public
Auditing an existing public repository for release quality ("make it official")
Choosing a license for a project
Setting up packaging, versioning, or release automation ahead of a public launch

将私有仓库转为公开
审核现有公开仓库的发布质量（使其「正式化」）
为项目选择许可证
在公开发布前设置打包、版本控制或发布自动化

When NOT to Use

不适用场景

Routine development on an already-released project (no release event)
Auditing third-party code for vulnerabilities (use a security-review skill)
Publishing a package from a repository that will stay private — only the release-management steps apply; skip the rest

已发布项目的日常开发（无发布事件）
审核第三方代码的漏洞（使用安全审核技能）
从保持私有状态的仓库发布包——仅适用发布管理步骤，跳过其余步骤

Workflow

工作流

Step 1: Detect the organization profile

步骤1：检测组织配置文件

bash {baseDir}/scripts/detect_org.sh

The script inspects git remotes and recent committer emails, and prints a profile name. If it prints

trailofbits

, read references/trailofbits.md now and apply its license policy, publishing accounts, and process notes throughout the remaining steps. If it prints

generic

, proceed with the generic guidance alone. If the user says the detection is wrong, trust the user.

bash {baseDir}/scripts/detect_org.sh

该脚本会检查git远程仓库和近期提交者邮箱，并输出配置文件名称。如果输出

trailofbits

，请立即阅读references/trailofbits.md，并在后续所有步骤中应用其许可证政策、发布账户和流程说明。如果输出

generic

，仅遵循通用指南即可。如果用户表示检测结果错误，以用户意见为准。

Step 2: Audit for secrets — before anything else

步骤2：秘密审计——优先于所有步骤

A repository that has ever contained secrets (API keys, credentials, client data) should not be flipped public. History rewriting is error-prone and does not reach forks, caches, or CI artifacts. The reliable fix is a fresh repository: copy the current tree over, commit, and archive the old repository privately.

Ask whether the project ever handled secrets or client-confidential material. For a security consultancy's tooling, also ask whether test fixtures or example data came from client engagements.
Scan the full history with a dedicated tool if available —
```
gitleaks git .
```
or
```
trufflehog git file://.
```
— rather than eyeballing.
Check beyond the git tree: GitHub Actions logs and artifacts, old releases, issue and PR history, and the repository wiki all become public with the repository.
After going public, enable GitHub secret scanning and push protection in the repository settings.

Reject these rationalizations — this is the one step that cannot be fixed after publication:

"The key was revoked, so the history is fine." Revoked credentials still leak infrastructure names, internal URLs, and patterns attackers use for targeting.
"We'll rewrite history with git-filter-repo." Rewrites miss forks, clones, caches, and CI artifacts; the fresh-repository approach does not.
"It's only test data." Fixtures derived from client engagements or production systems are confidential regardless of how they are labeled.

曾包含秘密（API密钥、凭证、客户数据）的仓库不应转为公开。历史重写容易出错，且无法覆盖分支、缓存或CI工件。可靠的解决方案是创建新仓库：复制当前代码树，提交，然后将旧仓库设为私有归档。

询问项目是否曾处理过秘密或客户机密材料。对于安全咨询公司的工具，还需询问测试用例或示例数据是否来自客户业务。
如果有专用工具，请使用其扫描完整历史——例如
```
gitleaks git .
```
或
```
trufflehog git file://.
```
——而非人工检查。
检查git树之外的内容：GitHub Actions日志和工件、旧版本、问题和PR历史记录，以及仓库维基，这些内容都会随仓库公开而变为公开可见。
公开后，在仓库设置中启用GitHub秘密扫描和推送保护。

拒绝以下合理化借口——这是发布后无法修复的步骤：

「密钥已撤销，所以历史记录没问题。」 已撤销的凭证仍会泄露基础设施名称、内部URL和攻击者用于目标定位的模式。
「我们会用git-filter-repo重写历史。」 重写无法覆盖分支、克隆、缓存和CI工件；而新建仓库的方法可以避免这些问题。
「这只是测试数据。」 源自客户业务或生产系统的测试用例无论如何标注，都属于机密内容。

Step 3: Run the readiness check

步骤3：运行就绪检查

bash {baseDir}/scripts/check_readiness.sh

The script prints a checklist of presence indicators (README, LICENSE, CONTRIBUTING, SECURITY.md, CI, tests, semver tags, ...) and warns about tracked files that commonly contain secrets. Treat unchecked items as discussion prompts, not hard failures — a research prototype does not need everything a flagship library needs. Walk through the gaps with the user and fix the ones that matter for this project.

bash {baseDir}/scripts/check_readiness.sh

该脚本会输出一份就绪状态检查清单（包括README、LICENSE、CONTRIBUTING、SECURITY.md、CI、测试、semver标签等是否存在），并警告通常包含秘密的已跟踪文件。将未勾选的项目视为讨论提示，而非硬性失败——研究原型不需要旗舰库所需的所有内容。与用户一起梳理差距，并修复对本项目重要的部分。

Step 4: Documentation

步骤4：文档编写

The README is the project's front door. Confirm it explains:

What the project is and what problem it solves (first paragraph)
How to install it — package manager, container image, or build from source; a fresh-clone build must work using only what is in the repository
How to use it — at least one concrete, copy-pasteable example
How to contribute — inline or via
```
CONTRIBUTING.md
```
The license — a short section naming it

Also add:

SECURITY.md
with vulnerability-reporting instructions (a contact address or GitHub private vulnerability reporting). For security tooling this is table stakes.
API documentation, built and hosted (GitHub Pages via CI is the usual route), linked from the README and the repository website field. See the language references below for per-ecosystem doc tooling.
A code of conduct if the project expects outside contributors.

README是项目的「前门」。确认它包含以下内容：

项目定位及其解决的问题（第一段）
安装方法——包管理器、容器镜像或从源码构建；只需使用仓库中的内容，就能完成全新克隆后的构建
使用方法——至少一个具体的、可直接复制粘贴的示例
贡献方式——内联说明或通过
```
CONTRIBUTING.md
```
文件
许可证——一个简短的说明部分，明确许可证类型

还需添加：

SECURITY.md
：包含漏洞报告说明（联系方式或GitHub私有漏洞报告渠道）。对于安全工具而言，这是必备内容。
API文档：构建并托管（通常通过CI部署到GitHub Pages），从README和仓库网站字段链接到该文档。请参阅下方的语言参考文档，了解各生态系统的文档工具。
行为准则：如果项目期望外部贡献者参与，请添加此项。

Step 5: Licensing

步骤5：许可证管理

No license means not open source, regardless of visibility. Read references/licensing.md for selection criteria and mechanics. The short version:

Apply the organization's policy if one was detected in Step 1.
Otherwise: Apache 2.0 as the permissive default, AGPLv3 when private modification by competitors is a real concern, Creative Commons for non-code artifacts.
Add the
```
LICENSE
```
file, set SPDX identifiers in package metadata, state the license in the README, and verify all three agree.

没有许可证意味着不是开源项目，无论可见性如何。阅读references/licensing.md了解选择标准和操作方法。简要说明：

如果步骤1中检测到组织政策，请应用该政策。
否则：默认使用Apache 2.0（宽松许可证）；当竞争对手的私有修改是切实问题时，使用AGPLv3；非代码工件使用Creative Commons许可证。
添加
```
LICENSE
```
文件，在包元数据中设置SPDX标识符，在README中声明许可证，并验证三者内容一致。

Step 6: Tests and CI

步骤6：测试与CI（持续集成）

Confirm the test suite exists and passes; a public repository with a failing default branch signals abandonment.
Ensure CI runs the tests on every PR, across the supported language-version and platform matrix.
Enforce formatting and linting in CI (per-language tooling in the references below), so style debates never reach review.
Respect existing tooling. Do not replace a working formatter, linter, or type checker as part of open-sourcing. If it lags the current generation (the language references name the current tools), warn the maintainer and let them decide; only when a category is missing entirely — no type checker, no formatter — add the current default.
Consider a coverage gate that fails CI when coverage drops.
Harden the workflows themselves before they become public attack surface:
- Pin third-party actions to full commit SHAs; enable Dependabot for
```
github-actions
```
  so pins stay current.
- Set least-privilege
```
permissions:
```
  blocks (start from
```
permissions: {}
```
  ).
- Audit with
```
zizmor .github/workflows/
```
  and lint with
```
actionlint
```
  .

确认测试套件存在且能通过；默认分支测试失败的公开仓库会给人一种已被弃用的印象。
确保CI在每个PR上运行测试，覆盖支持的语言版本和平台矩阵。
在CI中强制执行代码格式化和静态检查（请参阅下方参考文档中的各语言工具），避免代码风格争论进入评审环节。
尊重现有工具。不要在开源过程中替换已在使用的格式化工具、静态检查器或类型检查器。如果工具滞后于当前版本（语言参考文档中列出了当前主流工具），请提醒维护者并让他们决定；只有当某类工具完全缺失时——比如没有类型检查器、没有格式化工具——才添加当前主流工具。
考虑设置覆盖率门槛，当覆盖率下降时使CI失败。
在工作流成为公开攻击面之前，对其进行加固：
- 将第三方操作固定到完整的提交SHA；为
```
github-actions
```
  启用Dependabot，使固定的版本保持最新。
- 设置最小权限的
```
permissions:
```
  块（从
```
permissions: {}
```
  开始）。
- 使用
```
zizmor .github/workflows/
```
  进行审核，使用
```
actionlint
```
  进行静态检查。

Step 7: Repository settings

步骤7：仓库设置

Branch protection on the default branch: no force pushes, PRs required. Prefer rulesets for new repositories; classic branch protection remains supported.
Merge protection: required status checks so PRs cannot merge with failing tests.
Dependabot or Renovate for dependency and Actions updates. Group updates to cut PR noise, and set a cooldown window (e.g., 7 days) so freshly published — and occasionally hijacked — versions age before adoption.
.editorconfig
so contributors' editors agree on whitespace basics.
Labels: create them as soon as more than one issue or PR needs one; prefixes for facets scale well (
```
C:
```
component,
```
P:
```
platform). See blight's labels for a worked example.

默认分支保护：禁止强制推送，要求PR（拉取请求）。对于新仓库，优先使用规则集；经典分支保护仍受支持。
合并保护：要求状态检查通过，否则PR无法合并。
Dependabot或Renovate：用于依赖项和Actions更新。将更新分组以减少PR数量，并设置冷却窗口（例如7天），使新发布的（偶尔被劫持的）版本在被采用前经过一段时间的验证。
.editorconfig
：使贡献者的编辑器在基础空白字符设置上保持一致。
标签：当有多个问题或PR需要标签时立即创建；按方面设置前缀的标签扩展性更好（如
```
C:
```
组件、
```
P:
```
平台）。可参考blight的标签作为示例。

Step 8: Releases and versioning

步骤8：发布与版本控制

Tag every release
```
vX.Y.Z
```
, following semver; use
```
-rc.N
```
/
```
-pre.N
```
suffixes for release candidates and prereleases.
Make releases CI-driven: pushing a tag (or publishing a GitHub Release) triggers build, packaging, and upload with no manual steps. A release should be
```
git tag vX.Y.Z && git push origin vX.Y.Z
```
.
Publish packages under an organization-owned account, not a personal one, and use trusted publishing (OIDC) instead of long-lived tokens wherever the index supports it.

为每个版本打上
```
vX.Y.Z
```
标签，遵循semver规范；使用
```
-rc.N
```
/
```
-pre.N
```
后缀标记候选版本和预发布版本。
使发布由CI驱动：推送标签（或发布GitHub Release）会触发构建、打包和上传，无需手动步骤。发布流程应简化为
```
git tag vX.Y.Z && git push origin vX.Y.Z
```
。
使用组织所有的账户发布包，而非个人账户；在包索引支持的情况下，使用可信发布（OIDC）而非长期令牌。

Step 9: Language-specific practices

步骤9：特定语言实践

Identify the project's languages from its marker files and read the matching reference for packaging, publishing, and quality tooling:

Marker file	Reference
`pyproject.toml` , `setup.py`	references/python.md — defers to the modern-python skill for tooling
`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

For other ecosystems, apply the cross-cutting principles: reproducible builds from a fresh clone, CI-driven releases, trusted publishing or organization-owned accounts, and license metadata in the package manifest.

从标记文件识别项目使用的语言，并阅读对应的参考文档了解打包、发布和质量工具：

标记文件	参考文档
`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驱动发布、可信发布或组织所有账户、包清单中包含许可证元数据。

Final Review

最终审核

Before the visibility switch is flipped, verify from an outsider's perspective:

Clone into a clean directory and follow the README's build instructions verbatim — do they work with no tribal knowledge?
Re-run
```
{baseDir}/scripts/check_readiness.sh
```
and confirm the remaining gaps are deliberate choices, stated to the user.
Confirm the secrets audit (Step 2) actually happened; it is the one step that cannot be fixed after publication.

Making the repository public is then a repository-settings change. Pair the release with an announcement where the organization has a process for one.

在切换仓库可见性之前，从外部人员的角度验证以下内容：

克隆到干净目录，严格按照README中的构建说明操作——无需内部知识就能成功吗？
重新运行
```
{baseDir}/scripts/check_readiness.sh
```
，确认剩余的差距是经过用户确认的有意选择。
确认秘密审计（步骤2）已实际完成；这是发布后无法修复的步骤。

之后只需在仓库设置中修改可见性即可将仓库设为公开。如果组织有相关流程，请配合发布发布公告。

Additional Resources

额外资源

Reference Files

参考文件

references/licensing.md — license selection criteria, SPDX metadata, forks and relicensing
references/trailofbits.md — Trail of Bits policy overlay (loaded only when detected in Step 1)
references/python.md, references/c-cpp.md, references/rust.md, references/go.md, references/javascript.md, references/ruby.md — per-language packaging, publishing, and quality tooling

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

脚本

scripts/detect_org.sh
— prints the organization profile (
```
trailofbits
```
or
```
generic
```
) from git remotes and committer emails
scripts/check_readiness.sh
— prints presence indicators for release-readiness files and flags tracked files that commonly hold secrets

scripts/detect_org.sh
— 从git远程仓库和提交者邮箱输出组织配置文件（
```
trailofbits
```
或
```
generic
```
）
scripts/check_readiness.sh
— 输出发布就绪文件的存在状态，并标记通常包含秘密的已跟踪文件