贡献者入门引导 是做什么的?
新贡献者需要三样东西:一条路径(CONTRIBUTING.md)、一张地图(标签)和第一步任务(新手友好问题)。从项目的真实命令出发,构建所有这三样东西。
何时使用
- “写一份 CONTRIBUTING.md” / “我如何吸引贡献者?”
- 创建或清理 GitHub 标签
- 编写新手友好问题,或为 Hacktoberfest 或发布做准备
何时不使用
- 基金会治理文档(GOVERNANCE.md、章程):超出范围。
- 行为准则文本:采用 Contributor Covenant 原文;不要重写。
工作流程
1. CONTRIBUTING.md
- 找到真实的命令:设置(
pip install -e ".[dev]"、npm ci、composer install)、测试、代码检查/格式化、构建、文档。查看 CI 工作流;它们是事实来源。 - 复制模板并填写每个占位符。 记录每条命令都要亲自运行,或明确说明哪些未能运行。
- 保持易读性:贡献方式(按所需时间分类)、设置、测试、代码风格、提交规范、PR 流程、求助渠道。链接 CODE_OF_CONDUCT.md 和 SECURITY.md。
- 在“新手友好问题”下添加 5-10 个具体的入门任务,或链接标签。
2. 标签
scripts/ 是相对于此技能目录的路径。该脚本永远不会直接调用 GitHub API。
python3 scripts/labels.py generate > labels.json # 默认标签集
python3 scripts/labels.py generate --area cli --area docs --prefixed > labels.json
python3 scripts/labels.py validate labels.json # 发现问题时退出代码为 1
python3 scripts/labels.py commands labels.json --repo OWNER/NAME > apply-labels.sh
向用户展示 apply-labels.sh 并在执行前征求同意:它会在 GitHub 上创建或更新标签(gh label create ... --force)。它永远不会删除标签。如果用户希望删除旧标签,请使用 gh label list 列出,并逐一确认删除。
保持 GitHub 的原生名称 good first issue 和 help wanted 不变:GitHub 和第三方网站使用它们来展示初级任务。
3. 新手友好问题
使用指南重写候选 issue。每条都需要:上下文、需要修改的具体文件、验收标准、如何测试以及提供帮助。在 GitHub 上编辑或添加标签前请征得同意;先以草稿形式提供文本。
输出
- CONTRIBUTING.md(新建或更新)以及已验证与未验证的命令列表。
labels.json和apply-labels.sh(除非用户批准,否则不会执行)。- 以 Markdown 形式起草的新手友好问题,可直接粘贴或使用
gh issue create --title ... --body-file ... --label "good first issue"创建, 待批准后执行。
默认标签集
| 分组 | 标签 |
|---|---|
| 类型 | bug, enhancement, documentation, question, performance, refactor |
| 贡献者 | good first issue, help wanted |
| 状态 | needs-triage, needs-repro, needs-info, confirmed, in-progress, blocked, stale |
| 优先级 | priority: critical, priority: high, priority: low |
| 解决 | duplicate, invalid, wontfix |
| 依赖 | dependencies, security, breaking-change |
--prefixed 会将标签名切换为 type: bug、status: needs triage 等样式。GitHub 限制标签名最多 50 个字符,描述最多 100 个字符;validate 会检查这两项,以及 6 位十六进制颜色和不区分大小写的重复项。