關於如何更好地使用Github的一些建議
原文(Github repository形式): https://github.com/Wasdns/github-example-repo
本文記錄了我對於Github使用的一些技巧，並針對以下幾個方面:
- 一、提交問題；
- 二、提交(commit)的註釋信息；
- 三、README形式的Github文檔撰寫。
給出了自己的一些建議，不足之處歡迎各位指出，歡迎補充和提問：）。
一、提交問題
在提問之前，請確認你的問題是否能夠通過以下方式解決：(1)百度；(2)bing；(3)Google；(4)Stackoverflow。
一個參考的主要提問步驟分為：
- (1)標題：出現bug的概要，例："在根目錄下，某某文件無法找到"
- (2)背景介紹(可選)：介紹你大概的目的是什麽；例："為了測試數獨，我做了這個實驗，遇到了這個問題。"
- (3)實驗環境：你的系統環境、安裝的依賴，選擇性給出；例："我的操作系統為ubuntu 14.04，64位。"
- (4)重要：重現bug的步驟，盡量條理清晰、簡明；
- (5)期待出現的行為(可選)：如果沒有遇到這個bug，你希望得到的結果是什麽；
- (6)結果出現的行為：較為全面的bug信息，或者錯誤日誌，或者二者兼具；
- (7)額外信息：一些附加的信息，如代碼(簡短的骨架，或者以站外鏈接的形式貼出)，或者你對於該錯誤的認識；
- (8)禮貌用語。
錯誤示範：WTF the bug is?
參考樣例："error: HashAlgorithm.csum16: Invalid enum tag"
二、提交(commit)的註釋信息
對於一個commit來說，一個完備的註釋信息有助於讓其他人了解你的這次提交做了什麽工作。例如，項目管理員對PR進行code review時需要對於該PR的每一次提交進行審核，如果每次提交的註釋信息都非常簡單/雜亂，那麽對於code reviewer來說是非常不友好的：他需要翻看你每一次文件的修改記錄來判斷你的這次提交做了什麽工作。
一個規範的commit有這樣的幾個特點：
- 1.註釋信息的標題有一句清晰的概述，且主體內容簡潔明了；
- 2.註釋信息的拓展描述中，對於每一處的修改都有清晰的記錄；
- 3.註釋信息應保留必要的信息。
1.註釋信息的標題有一句清晰的概述，且主體內容簡潔明了：
標題至少需要有一句完整的句子(建議少於50字)來說明本次提交做了哪些工作。在大部分同學的github中，每次提交的註釋信息通常只有"更新"、"修改"幾個單詞，其他開發者自然很困惑：到底你更新了什麽、修改了什麽？只能通過查閱詳細信息來查看這次commit的具體修改。一個參考的規範註釋信息標題的格式為文件名：簡述改動信息。
錯誤示例：fix bug，更新，發布；
參考示例：文件名：簡述改動信息，如：README.md: 更新第三章，加入了對commit註釋信息的描述。
此外，要求註釋信息的主體內容在能讓別人看懂的情況下盡量簡潔明了，不加入過多的不必要信息。
錯誤示例1：我把今天誌玲女神寫的代碼給刪除了。 其中今天誌玲女神寫的代碼是不明確且不必要的，而且沒有體現出本次提交的目的。
參考示例2：修改"你今天真好看"功能的API：刪除了文件hello.c中的函數模塊printBeauty()，修改了函數hello()的返回參數類型。
錯誤示例2：今天客戶A那貨提出了一個需求叫做"你今天真好看"，後面的同學註意了，我把原來文件hello.c中的一些功能做了適配，來支持這個新功能。
參考示例2：增加"你今天真好看"功能：修改hello.c中函數hello()的返回參數類型。
2.註釋信息的拓展描述中，對於每一處的修改都有清晰的記錄：
如果一個提交修改了項目中的多個文件/模塊，可以將這些修改的共同點，如加入新功能"你今天真好看"，作為提交註釋信息的標題，並將這些修改的具體信息在註釋信息的文本欄中分點列出。
錯誤示例：
Commit Title:
按今天客戶A的需求加了一個新功能Commit Content:
修改了文件hello.c, beauty.c, stupidClient.c。參考示例：
Commit Title:
2017/10/1：加入新功能"你今天真好看"Commit Content:
1.修改文件hello.c：hello函數返回參數類型(L101)；
2.修改文件beauty.c：將hello函數結果進行輸出(L20)；
3.增加2017/10/1的客戶需求到文件stupidClient.c中。3.註釋信息應保留必要的信息：
倘若你認為這一次的commit是有必要的，那麽請在註釋說明中說明以下必要的信息：
- 1.為什麽這次修改是必要的，它解決了什麽問題/它的目的是什麽？
- 2.這次commit是如何解決問題/達到上述目的的？
- 3.影響的文件有哪些？
錯誤示例：
Commit Title:
Fix bug // 它解決了什麽問題？Commit Content:
// 這次commit是如何解決問題的？影響的文件有哪些？
<Empty> 參考示例：
Commit Title:
Fix bug #1 // 它解決了issue#1，因此這次修改是必要的Commit Content:
// 這次commit通過...解決了問題。影響了文件src/hello.c。
1.修改文件src/hello.c：修改hello_beauty()函數的返回參數類型(L30)；
2.在單元測試中增加測試test1，避免#1的重復發生。此外，有一些commit完全沒有必要，或者對於該項目毫無意義，比如：
錯誤示例1：小陳為了刷KPI(Key Performance Indicator，關鍵績效指標)，將文件A中所有的空行刪除，做了一次提交，心裏美滋滋的。
錯誤示例2：負責在Github上進行某個項目開發的小李被開除了，被迫離開了現在的公司；在離開前，她將本地倉庫中所有的內容刪除，並將這些修改提交到了項目中，以此宣泄心中的憤恨。
不提交沒有必要、毫無意義的commit是每一個項目成員應該遵守的規範。
一些建議：
(1)個人推薦以Github的客戶端，如Github Desktop為主、命令行為輔來進行commit提交，寫提交信息時的效果圖如下：
此外，還可以在desktop上查看歷史的提交記錄：
(2)在使用命令行進行提交時，通常使用git commit -m '註釋信息'來填寫commit註釋信息，但是-m參數適合單行註釋，對於多行的commit註釋來說是不合適的。這裏推薦使用git commit -v命令，會自動跳出文本欄以供commit註釋信息的編輯，其中文本的首行將作為commit的標題，剩余部分將作為補充信息。
(3)如果某次提交修改的範圍非常大，即改動了非常多的文件，建議劃分為多次commit，每次提交一個子模塊並加以對應信息的說明；如果某次提交修改的範圍較小，比如只修改了一個文件中某個變量的賦值操作，可以酌情與其他commit合並為一個commit，在註釋信息中說明這一點即可。
(4)阮一峰老師寫了一篇關於Github commit註釋信息的博客：Commit message 和 Change log 編寫指南，介紹了AngularJS團隊的commit註釋信息格式，這裏推薦給大家。
<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>拓展閱讀：
- 寫好 Git Commit 信息的 7 個建議
- Commit message 和 Change log 編寫指南
- AngularJS Git Commit Message Conventions
三、README形式的Github文檔撰寫
一個規範化、詳細的文檔是一個優秀項目必不可少的內容。在Github上有兩種撰寫文檔的方式，一種是"README"，另一種是wiki，本節主要介紹筆者在使用README進行文檔記錄的一些經驗，主要包括：
- 1.如何創建README文檔；
- 2.使用Markdown語法記錄、修改文檔；
- 3.通用的README文檔格式；
- 4.實驗室Github科研型項目，README文檔的參考示例；
- 5.現有大型商用項目README文檔參考示例。
1.如何創建README文檔
方法一：
在創建一個新的項目時，有一個名為"Initialize this repository with a README"的選項，勾選即可為該項目創建一個README文檔：
在項目目錄中，該文件是"README.md"，.md後綴表明該文件是Markdown文件，使用Markdown文本編輯語言進行文件編輯。
方法二：
在項目主頁中，有一個名為"Create new file"的按鈕，如圖紅色陰影部分所示：
點擊進入創建界面，在"Name your file"一欄中，填入以.md後綴名結尾的文件名，如"README.md"：
Github默認在頁面中顯示使用"README.md", "readme.md", "README", "readme"作為名字的文件內容；其中在顯示"README.md"和"readme.md"文檔時，Github基於Markdown語法對其進行顯示，比如將文件的內容：# [標題名稱] 以一級標題的形式顯示出來。
緊接著就可以在下方的文本框中開始文檔的撰寫了。此外，Github支持在線的文檔視圖，點擊如圖紅色方框 "Preview"(創建文件時顯示)/"Preview changes"(修改文件時顯示) 所示：
即可將剛才新增/修改的內容以可視化的形式呈現：
最後，合理在commit中描述該文檔，並將該文檔提交到你的項目中：
方法三：
在主機的倉庫中創建README文檔，並提交至Github上。該方法不再具體闡釋。
註：上文中創建的README文檔即項目中的simple-README.md。
2.使用Markdown語法記錄、修改文檔
這裏為讀者提供了一些用於掌握基本的Markdown語法的參考資料，包括：
- 極簡MarkDown排版介紹（How to）
- Markdown快速入門
- Marstering Markdown
Github上README文檔的記錄、修改與普通的Markdown文檔的記錄、修改無異。
3.通用的README文檔格式
Github官方給出了一種通用的README文檔格式:
- 項目名：在人們往下瀏覽你的倉庫之前，首先會看到你的項目名稱；項目名稱應在README文件的首部。
- 描述：對於接下來README內容的一個描述；一個好的描述是非常清晰、簡潔、切合主題的；用於描述該項目的重要性以及作用。
- 內容表格：可選；引入內容表格的目的在於為人們提供一個快捷的導航，尤其是在README文檔內容多且詳細的時候。
- 安裝：接著，安裝教程告訴用戶如何快速、正確安裝你的項目；可以考慮的是，做一個gif描述安裝過程，使其他人對整個過程更加清楚。
- 使用說明：下一個階段是使用說明，用於告訴已經安裝好項目的用戶如何使用你的項目；該處適合增加一些項目的截屏。
- 貢獻：一個大型商用項目通常有一個獨立的章節，用於描述如何為這個項目作出貢獻(如文件命名、編碼規範等)，有時可能是一個獨立的描述文件；如果你有特殊的要求，詳細地解釋你的要求有助於其他開發者更好地為你的項目做出貢獻。深入閱讀：setting guidelines for repository contributors
- 榮譽：增加一個章節用於列舉出項目的作者和做出貢獻的開發者們。
- 許可證：加入一個章節用於描述該項目的許可證。如何選擇一個合適的許可證：licensing guide，也可以參考阮一峰老師的教程：如何選擇開源許可證？
4.實驗室Github科研型項目，README文檔的參考示例
標準語言：English。
一個實驗室Github科研型項目，README文檔參考示例由以下幾個部分組成：
- Chapter1: 項目名稱(一級標題)+項目貢獻描述(內容，以點列出)；
- Chapter2: 安裝所需的軟件依賴，貼上對應的Installation Guide鏈接；
- Chapter3: "Getting Start" 項目，即入門級項目，一個幫助用戶快速上手的demo；
- Chapter4: README主體部分，以項目貢獻點列章節，每個章節闡述項目中對應於該貢獻點的文件和子模塊；
- Chapter5: 相關工作，相關的論文或者Github項目，給出鏈接；
- Chapter6: 問題向導，當用戶遇到問題時解決問題的方法，包括給出社區鏈接、相關issues、聯系郵件地址等等；
- Chapter7: 引用的參考文獻，作者信息。
5.現有大型商用項目README文檔參考示例
- Baidu, brpc
- Barefoot, behavioral-model
- Google, protobuf
四、參考資料
- CloudLab Coding Style Guide, George Washington University
- Github Guides
- Git 寫出好的 commit message
- 寫好 Git Commit 信息的 7 個建議
- Commit message 和 Change log 編寫指南
- AngularJS Git Commit Message Conventions
- Documenting your projects on GitHub
- Mastering Issues
- 極簡MarkDown排版介紹（How to）
- Markdown快速入門
- Mastering Markdown
- setting guidelines for repository contributors
- licensing guide
- 如何選擇開源許可證？
- Composite Style Guide
- Google's C++ Style Guide
Tags: 提交 quot 信息 註釋 一些 Github
文章來源：