專案指南

開源儲存庫的 CONTRIBUTING.md 範本

CONTRIBUTING.md 能協助人們從「我想幫忙」走到提出有用的 Issue 或 Pull Request。請說明最小可接受的貢獻,以及驗證方式。要求應反映專案實際運作,而不是沒有人遵循的理想流程。

GitHubStart 編輯團隊 · 更新日期

複製並調整貢獻範本

替換預留欄位,並驗證每個指令與連結。即使貢獻者尚未準備好修改應用程式碼,也應歡迎文件修正及錯誤回報。

# 參與貢獻

## 開始之前
閱讀 README 並查看現有 Issue。
若是大型變更,請先討論方案再實作。

## 本機設定
[必要執行環境及已驗證的設定指令]

## 回報錯誤
包含版本、環境、操作步驟、預期結果及實際結果。
從日誌中移除機密及個人資料。

## 提交 Pull Request
- 說明問題及提議的變更。
- 讓變更保持聚焦。
- 執行[專案指定的檢查]。
- 更新受影響的文件。

## 審查
[由誰審查、如何回應及實際可投入的時間]

## 其他協助方式
[文件、範例、翻譯或可重現的回報]

讓指南容易找到

GitHub 能辨識儲存庫根目錄、docs 或 .github 目錄中的貢獻指南。也請從 README 連結到該檔案,讓閱讀專案介紹的人能立即找到流程。

從儲存庫實際的貢獻入口檢查整條路徑。若有多份指南,請整合互相衝突的說明。貢獻者不應在 README 看到一個設定指令,卻在貢獻指南看到另一個不受支援的指令。

設計一項容易上手的首次貢獻

選擇成果明確的小任務,例如修正支援執行環境的範例。解釋如何重現問題、哪些行為應改變,以及如何確認完成。若任務依賴未記載的內部知識,就不要標示為新手友善。

誠實說明可投入審查的時間。若無法承諾回應期限,請改為說明貢獻者可以如何查詢進度。清楚的界線能減少被擱置的工作,比承諾合併每一份貢獻更有用。

常見問題

CONTRIBUTING.md 會取代 README.md 嗎?

不會。README 解釋專案及使用方式;貢獻指南則說明如何提出及驗證變更。

應該複製其他專案的測試指令嗎?

只有在它們同樣適用於你的專案時才可以。請用實際檢查過的指令替換預留欄位。

貢獻指南能保證帶來更多貢獻者嗎?

不能。它能減少有興趣者的不確定性,但專案實用性、任務品質及維護者後續回應仍然重要。

參考資料