Back to Details

gh-oss-release-prep

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OSS Release Preparation

开源（OSS）发布准备

Systematic workflow to prepare a repository for open-source publishing. Covers code quality, licensing, documentation, and release readiness.
用于为开源发布准备代码仓库的系统化工作流，涵盖代码质量、许可证合规、文档规范和发布就绪性检查。

Workflow

工作流

Step 1: Repository Scan

步骤1：仓库扫描

Scan the entire repository to understand its current state:
  1. Read the project structure (directories, key files)
  2. Check for existing README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT
  3. Identify the primary language and build system
  4. Check for any sensitive files (.env, credentials, API keys, internal URLs)
  5. Review .gitignore for completeness
Report findings as a checklist:
Repository Scan:
- [x/!] README.md exists
- [x/!] LICENSE file exists
- [x/!] .gitignore is comprehensive
- [x/!] No sensitive files detected
- [x/!] No hardcoded internal URLs or secrets
扫描整个代码仓库以了解当前状态：
  1. 查看项目结构（目录、关键文件）
  2. 检查是否存在README、LICENSE、CONTRIBUTING、CODE_OF_CONDUCT文件
  3. 确定主要开发语言和构建系统
  4. 检查是否存在敏感文件（.env、凭据、API密钥、内部URL）
  5. 检查.gitignore文件是否完善
将检查结果整理为清单：
Repository Scan:
- [x/!] README.md exists
- [x/!] LICENSE file exists
- [x/!] .gitignore is comprehensive
- [x/!] No sensitive files detected
- [x/!] No hardcoded internal URLs or secrets

Step 2: License & Dependency Audit

步骤2：许可证与依赖审计

  1. Identify the intended license (ask user if not specified, default suggestion: MIT)
  2. Check all dependencies for license compatibility:
    • Direct dependencies: list each with its license
    • Flag any copyleft (GPL, AGPL) dependencies that conflict with the chosen license
  3. If attribution is required, create or update a NOTICES file
  4. Verify the LICENSE file content is correct and includes the current year
  1. 确定目标许可证（若未指定则询问用户，默认建议使用MIT许可证）
  2. 检查所有依赖项的许可证兼容性：
    • 直接依赖项：列出每个依赖及其许可证
    • 标记所有与选定许可证冲突的Copyleft（GPL、AGPL）依赖项
  3. 若需要署名，则创建或更新NOTICES文件
  4. 验证LICENSE文件内容是否正确，且包含当前年份

Step 3: README Quality Check

步骤3：README质量检查

Evaluate and improve the README:
  1. Required sections (create if missing):
    • Project name and tagline (concise, memorable)
    • What it does (1-2 sentences)
    • Installation instructions
    • Quick start / basic usage
    • License
  2. Recommended sections (suggest if missing):
    • Features list
    • Configuration options
    • Contributing guidelines (or link to CONTRIBUTING.md)
    • Badges (CI status, license, version)
  3. Quality checks:
    • Does the README match the actual CLI/API interface?
    • Are code examples up to date and runnable?
    • Is the installation method documented correctly?
  4. Tagline: If the project lacks a compelling tagline, propose 3-5 options that are:
    • Short (under 10 words)
    • Descriptive of the core value
    • Memorable
评估并优化README文件：
  1. 必填章节（缺失则创建）：
    • 项目名称和标语（简洁、易记）
    • 功能介绍（1-2句话）
    • 安装说明
    • 快速开始/基础用法
    • 许可证信息
  2. 推荐章节（缺失则建议添加）：
    • 功能列表
    • 配置选项
    • 贡献指南（或链接到CONTRIBUTING.md）
    • 状态徽章（CI状态、许可证、版本号）
  3. 质量检查：
    • README内容是否与实际CLI/API接口一致？
    • 代码示例是否为最新且可运行？
    • 安装方法的文档是否准确？
  4. 标语优化：若项目缺乏吸引人的标语，提供3-5个符合以下要求的选项：
    • 简短（10字以内）
    • 体现核心价值
    • 容易记忆

Step 4: Code Quality Review

步骤4：代码质量审查

  1. Run available linters and fix issues:
    • Go: 
      golangci-lint run ./...
    • Node/TS: check 
      package.json
      scripts for lint commands
  2. Check for dead code using available tools (e.g., 
    deadcode ./...
    for Go)
  3. Ensure public API documentation exists (exported functions/types have comments)
  4. Remove TODO/FIXME comments that reference internal context
  5. Verify test coverage is reasonable for public consumption
  1. 运行可用的代码检查工具并修复问题：
    • Go: 
      golangci-lint run ./...
    • Node/TS：检查
      package.json
      中的lint脚本命令
  2. 使用工具检查无用代码（例如Go项目使用
    deadcode ./...
    ）
  3. 确保存在公开API文档（导出的函数/类型带有注释）
  4. 删除涉及内部上下文的TODO/FIXME注释
  5. 验证测试覆盖率符合开源项目的合理标准

Step 5: Release Readiness Checklist

步骤5：发布就绪检查清单

Present the final checklist:
OSS Release Readiness:
- [ ] LICENSE file is correct and complete
- [ ] All dependency licenses are compatible
- [ ] README is comprehensive and accurate
- [ ] No secrets, internal URLs, or sensitive data in code
- [ ] .gitignore covers build artifacts, IDE files, OS files
- [ ] CI/CD pipeline exists (GitHub Actions, etc.)
- [ ] Tests pass
- [ ] Linter passes with no errors
- [ ] Version/tag strategy defined (semver)
- [ ] Release automation configured (goreleaser, npm publish, etc.)
For each unchecked item, provide the specific fix needed.
展示最终检查清单：
OSS Release Readiness:
- [ ] LICENSE file is correct and complete
- [ ] All dependency licenses are compatible
- [ ] README is comprehensive and accurate
- [ ] No secrets, internal URLs, or sensitive data in code
- [ ] .gitignore covers build artifacts, IDE files, OS files
- [ ] CI/CD pipeline exists (GitHub Actions, etc.)
- [ ] Tests pass
- [ ] Linter passes with no errors
- [ ] Version/tag strategy defined (semver)
- [ ] Release automation configured (goreleaser, npm publish, etc.)
对于未勾选的项目，提供具体的修复建议。

Step 6: Final Actions

步骤6：最终操作

  1. If all checks pass, confirm with user before any publishing steps
  2. Suggest the release workflow:
    • Create initial release tag
    • Publish to package registry if applicable
    • Submit to relevant directories (Homebrew tap, npm, etc.)
  1. 若所有检查通过，在执行发布操作前与用户确认
  2. 建议发布工作流：
    • 创建初始发布标签
    • 若适用，发布到包管理仓库
    • 提交到相关目录（Homebrew tap、npm等）

Common Issues

常见问题

  • Goreleaser not configured: Create 
    .goreleaser.yaml
    for Go projects
  • Missing .gitignore entries: Add OS-specific (
    .DS_Store
    ), IDE-specific (
    .vscode/
    , 
    .idea/
    ), and language-specific entries
  • Internal references: Search for company-internal URLs, Slack channels, or employee names in code and docs
  • Inconsistent naming: Ensure the project name is consistent across README, package.json/go.mod, and CLI help text
  • 未配置Goreleaser：为Go项目创建
    .goreleaser.yaml
    文件
  • .gitignore条目缺失：添加系统特定（
    .DS_Store
    ）、IDE特定（
    .vscode/
    、
    .idea/
    ）和语言特定的忽略条目
  • 内部引用残留：在代码和文档中搜索公司内部URL、Slack频道或员工姓名并移除
  • 命名不一致：确保项目名称在README、package.json/go.mod和CLI帮助文本中保持一致

Examples

示例

Example 1: Go CLI tool
User: "prepare this for OSS"
Action:
1. Scan repo structure
2. Check go.mod dependencies for license compatibility
3. Ensure README matches `--help` output
4. Run golangci-lint, fix issues
5. Verify goreleaser config exists
6. Present checklist
Example 2: Node.js library
User: "make this repo public"
Action:
1. Scan for .env files, hardcoded URLs
2. Check package.json dependencies' licenses
3. Ensure README has install/usage/API docs
4. Run configured lint/test scripts
5. Verify npm publish config
6. Present checklist
示例1：Go CLI工具
用户: "为开源发布准备这个项目"
操作:
1. 扫描仓库结构
2. 检查go.mod依赖的许可证兼容性
3. 确保README与`--help`输出一致
4. 运行golangci-lint并修复问题
5. 验证是否存在goreleaser配置
6. 展示检查清单
示例2：Node.js库
用户: "将这个仓库公开"
操作:
1. 扫描是否存在.env文件和硬编码URL
2. 检查package.json依赖的许可证
3. 确保README包含安装/使用/API文档
4. 运行配置好的lint/测试脚本
5. 验证npm发布配置
6. 展示检查清单