貢獻者入門引導 是做什麼的?
新貢獻者需要三樣東西:一條路徑(CONTRIBUTING.md)、一張地圖(標籤)和一個第一步(good first issues)。從專案的實際命令中建立這三樣東西。
使用時機
- 「撰寫 CONTRIBUTING.md」/「如何吸引貢獻者?」
- 建立或清理 GitHub 標籤
- 撰寫 good first issues,或為 Hacktoberfest 或發佈做準備
不應使用時機
- 基金會治理文件(GOVERNANCE.md、章程):超出範圍。
- 行為準則文字:採用 Contributor Covenant 原樣;不要重寫。
工作流程
1. CONTRIBUTING.md
- 找出實際命令:設定(
pip install -e ".[dev]"、npm ci、composer install)、 測試、lint/格式化、建置、文件。閱讀 CI 工作流程;它們是事實來源。 - 複製範本並填入所有佔位符。 執行你記錄的每個命令,或者清楚說明哪些命令你無法執行。
- 保持易於掃讀:貢獻方式(按所需時間分類)、設定、測試、風格、 提交規範、PR 流程、到哪裡詢問。連結 CODE_OF_CONDUCT.md 和 SECURITY.md。
- 在「Good first issues」下加入 5-10 個具體的入門任務,或連結到該標籤。
2. 標籤
scripts/ 是相對於此技能目錄的路徑。該腳本絕不會直接呼叫 GitHub 本身。
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. Good first issues
依照指南改寫候選問題。每個問題需要: 背景、確切要修改的檔案、驗收標準、如何測試,以及提供協助的意願。 在編輯或標記 GitHub 上的問題之前先詢問;先以草稿形式提供文字。
輸出
- CONTRIBUTING.md(新檔案或更新)以及已驗證與未驗證的命令清單。
labels.json和apply-labels.sh(只有使用者同意後才執行)。- 草擬的 good first issues,以 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 位十六進位顏色和忽略大小寫的重複項。