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:

Read the project structure (directories, key files)
Check for existing README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT
Identify the primary language and build system
Check for any sensitive files (.env, credentials, API keys, internal URLs)
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

扫描整个代码仓库以了解当前状态：

查看项目结构（目录、关键文件）
检查是否存在README、LICENSE、CONTRIBUTING、CODE_OF_CONDUCT文件
确定主要开发语言和构建系统
检查是否存在敏感文件（.env、凭据、API密钥、内部URL）
检查.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：许可证与依赖审计

Identify the intended license (ask user if not specified, default suggestion: MIT)
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
If attribution is required, create or update a NOTICES file
Verify the LICENSE file content is correct and includes the current year

确定目标许可证（若未指定则询问用户，默认建议使用MIT许可证）
检查所有依赖项的许可证兼容性：
- 直接依赖项：列出每个依赖及其许可证
- 标记所有与选定许可证冲突的Copyleft（GPL、AGPL）依赖项
若需要署名，则创建或更新NOTICES文件
验证LICENSE文件内容是否正确，且包含当前年份

Step 3: README Quality Check

步骤3：README质量检查

Evaluate and improve the README:

Required sections (create if missing):
- Project name and tagline (concise, memorable)
- What it does (1-2 sentences)
- Installation instructions
- Quick start / basic usage
- License
Recommended sections (suggest if missing):
- Features list
- Configuration options
- Contributing guidelines (or link to CONTRIBUTING.md)
- Badges (CI status, license, version)
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?
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-2句话）
- 安装说明
- 快速开始/基础用法
- 许可证信息
推荐章节（缺失则建议添加）：
- 功能列表
- 配置选项
- 贡献指南（或链接到CONTRIBUTING.md）
- 状态徽章（CI状态、许可证、版本号）
质量检查：
- README内容是否与实际CLI/API接口一致？
- 代码示例是否为最新且可运行？
- 安装方法的文档是否准确？
标语优化：若项目缺乏吸引人的标语，提供3-5个符合以下要求的选项：
- 简短（10字以内）
- 体现核心价值
- 容易记忆

Step 4: Code Quality Review

步骤4：代码质量审查

Run available linters and fix issues:
- Go:
```
golangci-lint run ./...
```
- Node/TS: check
```
package.json
```
  scripts for lint commands
Check for dead code using available tools (e.g.,
```
deadcode ./...
```
for Go)
Ensure public API documentation exists (exported functions/types have comments)
Remove TODO/FIXME comments that reference internal context
Verify test coverage is reasonable for public consumption

运行可用的代码检查工具并修复问题：
- Go:
```
golangci-lint run ./...
```
- Node/TS：检查
```
package.json
```
  中的lint脚本命令
使用工具检查无用代码（例如Go项目使用
```
deadcode ./...
```
）
确保存在公开API文档（导出的函数/类型带有注释）
删除涉及内部上下文的TODO/FIXME注释
验证测试覆盖率符合开源项目的合理标准

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：最终操作

If all checks pass, confirm with user before any publishing steps
Suggest the release workflow:
- Create initial release tag
- Publish to package registry if applicable
- Submit to relevant directories (Homebrew tap, npm, etc.)

若所有检查通过，在执行发布操作前与用户确认
建议发布工作流：
- 创建初始发布标签
- 若适用，发布到包管理仓库
- 提交到相关目录（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. 展示检查清单