在 Day 24 - 為套件撰寫文件（Markdown & Github Wiki） 有介紹到如何使用 Markdown 的格式來寫文件，然後在昨天的文章 Day 25 - 虛擬環境 venv 與 requirements.txt 介紹了如何使用虛擬環境建立 requirements.txt 來幫助統一套件。有了這些我們就可以來寫引導別人如何貢獻這個開源的文件：CONTRIBUTING.md。

CONTRIBUTING.md

在各大的開源，都能看到這個檔案，去引導其他有興趣的貢獻者，讓他們照著統一的規則開發。舉我們在上個系列介紹的 pybaseball 為例子，裡面的結構大概可以分成幾個：

1. 套件需要哪些幫忙
2. 需要遵守的程式開發寫法（Coding Style）
3. 開發程式碼到開 Pull Request 到 Merge 到 main 的流程

從第一項開始介紹
需要哪些幫忙
通常這邊會寫套件要加新需求的話會有哪些，跟如何取得 Issues，我們套件的目的是獲取棒球資料的話，會大概有這幾項：

1. 當 Savant 或是其他數據網站有新功能的時候，開發新的 function 使用
2. 提供範例程式碼或是更新介紹文件
3. 錯誤回報或是錯誤修正，包含介紹文件內容的錯字之類的

以上都是可以貢獻的內容，最後可以再附註可以透過 標籤（Labels），去找可以解決的 Issues，通常會找有 good first issue 跟 bug 或 help wanted 標籤的，為了以後的貢獻者，正確的標籤也會很重要。

需要遵守的程式開發寫法
因為會來一起貢獻的人可能來自世界各地，也可能是各式各樣種類的人，為了讓我們的程式碼有一致性，就會特別訂定一些規範給來貢獻的人。像是排版，跟開 Issue 跟 Pull Request 的規則。排版有時候會請所有人都安裝一樣的排版工具（Linter），或是設置一些自動化的處理，讓程式碼在 Merge 之前會用套件自動幫我們排版，這都可以在這邊做說明。至於 Issue 跟 Pull Requet 的規範，Github 有提供設置 模板（Template） 的功能，之後只要請開發者照著填就好了，這在等等會做更詳細的介紹。

實際開發流程
最後這個項目會介紹從把程式碼載下來，到開發完畢上傳的流程，這會很像是之前介紹的 Day 08 - 用 Git 指令 下載 Repo 到本地端 跟 Day 10 - 上傳程式碼回 Github，不過比較不一樣的是，通常會要求開發者使用 Github Fork，把 Repo 複製一份到自己的 Github，再 git clone 那一份複製過的 Repo 到自己本地端開發跟上傳，之後再透過 git remote 同步到 upstream 就是我原本這一份 Repo。這樣的好處是在自己的 Repo 做一些大修改比較不會影響到原本的 Repo，也不會有維護者的一些限制，可以多做一些常識。也不用怕 branch 開太多太雜，因為都是在自己的 Repo 上進行操作。

以上大概都會是 CONTRIBUTING.md 可以提供的內容，有些比較大的開源像是 React，他們會自己寫一頁在他們的 官網 上，不過一般來說我們自己寫一個套件，用一個 .md 檔說明就很夠了。

Templates

再來介紹剛剛提到的 Templates，Issue 跟 Pull Request 新增模板的方式不一樣，Issue 的話比較簡單，只要去 Repo 頁的 Setting 後，往下滑會有個 Features 區裡有個 Issue，點選 Set up templates 按鈕：

進去會有個下拉式選單選取，可以使用預設的 Bug 跟 Feature 模板，或是自己寫個客製化 Custom 的

選擇一個後就會產生一個 Template，要編輯的話點選 Preview and edit 然後點標題旁邊的鉛筆 Icon 就能看到可以編輯的項目

他也可以在 Issue default title 設定預設負責人（Assignees） 跟 Issue 標題。編輯完再按左上角的叉叉就可以預覽我們的改動。

確定沒問題點選右上方的 Propose changes，他會要你 commit 這次的改動，會需要 commit 是因為我們建立新的模板，其實就是在 .github/ISSUE_TEMPLATE 建立一個 .md 檔。commit 成功後，可以去 Issues 那邊新增一個看看，點選 New issue，他就會問你要不要使用模板，只要點選 Get started 就能使用該模板。

如果是要新增 Pull Request 的模板，就不像 Issue 一樣有提供介紹工具，會需要自己到 .github 建立一個 pull_request_template.md 或是要多個的話則是建立 PULL_REQUEST_TEMPLATE/pull_request_template.md，這個 .md 的內容就會是 Pull Request 裡的敘述欄會有的文字訊息，更多詳情可以參考：Creating a pull request template for your repository

本日小結

今天介紹了開源套件會需要的 CONTRIBUTING.md 跟模板的撰寫，雖然這兩個項目不是必要的，但我自己覺得如果要建立一個良好的開源環境，這兩項是非常重要的，清楚的規範流程跟方便的模板，都會提升其他人參與的意願，讓更多人來參與開源。

最後一樣感謝大家耐心地看完文章，有任何意見或問題都歡迎留言跟我討論，明天見，掰掰。