關於如何更好地使用Github的一些建議

時間 2019-11-24

標籤關於如何更好使用 github 一些建議欄目 Git 简体版

原文原文鏈接

關於如何更好地使用Github的一些建議

原文(Github repository形式): https://github.com/Wasdns/github-example-repohtml

本文記錄了我對於Github使用的一些技巧，並針對如下幾個方面:git

1、提交問題；
2、提交(commit)的註釋信息；
3、README形式的Github文檔撰寫。

給出了本身的一些建議，不足之處歡迎各位指出，歡迎補充和提問：）。github

1、提交問題

在提問以前，請確認你的問題是否可以經過如下方式解決：(1)百度；(2)bing；(3)Google；(4)Stackoverflow。ubuntu

一個參考的主要提問步驟分爲：ruby

(1)標題：出現bug的概要，例："在根目錄下，某某文件沒法找到"
(2)背景介紹(可選)：介紹你大概的目的是什麼；例："爲了測試數獨，我作了這個實驗，遇到了這個問題。"
(3)實驗環境：你的系統環境、安裝的依賴，選擇性給出；例："個人操做系統爲Ubuntu 14.04，64位。"
(4)重要：重現bug的步驟，儘可能條理清晰、簡明；
(5)期待出現的行爲(可選)：若是沒有遇到這個bug，你但願獲得的結果是什麼；
(6)結果出現的行爲：較爲全面的bug信息，或者錯誤日誌，或者兩者兼具；
(7)額外信息：一些附加的信息，如代碼(簡短的骨架，或者以站外連接的形式貼出)，或者你對於該錯誤的認識；
(8)禮貌用語。

錯誤示範：WTF the bug is?markdown

參考樣例："error: HashAlgorithm.csum16: Invalid enum tag"ide

2、提交(commit)的註釋信息

對於一個commit來講，一個完備的註釋信息有助於讓其餘人瞭解你的此次提交作了什麼工做。例如，項目管理員對PR進行code review時須要對於該PR的每一次提交進行審覈，若是每次提交的註釋信息都很是簡單/雜亂，那麼對於code reviewer來講是很是不友好的：他須要翻看你每一次文件的修改記錄來判斷你的此次提交作了什麼工做。svn

一個規範的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>

拓展閱讀：

3、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語法的參考資料，包括：

Github上README文檔的記錄、修改與普通的Markdown文檔的記錄、修改無異。

3.通用的README文檔格式

Github官方給出了一種通用的README文檔格式:

項目名：在人們往下瀏覽你的倉庫以前，首先會看到你的項目名稱；項目名稱應在README文件的首部。
描述：對於接下來README內容的一個描述；一個好的描述是很是清晰、簡潔、切合主題的；用於描述該項目的重要性以及做用。
內容表格：可選；引入內容表格的目的在於爲人們提供一個快捷的導航，尤爲是在README文檔內容多且詳細的時候。
安裝：接着，安裝教程告訴用戶如何快速、正確安裝你的項目；能夠考慮的是，作一個gif描述安裝過程，使其餘人對整個過程更加清楚。
使用說明：下一個階段是使用說明，用於告訴已經安裝好項目的用戶如何使用你的項目；該處適合增長一些項目的截屏。
貢獻：一個大型商用項目一般有一個獨立的章節，用於描述如何爲這個項目做出貢獻(如文件命名、編碼規範等)，有時多是一個獨立的描述文件；若是你有特殊的要求，詳細地解釋你的要求有助於其餘開發者更好地爲你的項目作出貢獻。深刻閱讀：setting guidelines for repository contributors
榮譽：增長一個章節用於列舉出項目的做者和作出貢獻的開發者們。
許可證：加入一個章節用於描述該項目的許可證。如何選擇一個合適的許可證：licensing guide，也能夠參考阮一峯老師的教程：如何選擇開源許可證？