build

這邊我對build的定義是和建制這個專案有關的一些script檔或者建制過程產生的一些臨時檔案可以放的地方。

我習慣性會把build script例如建立nuget或者執行測試放到一個自己的獨立資料夾，而這裡就是那個地方。

docs

放文件的地方，有些習慣用doc - 不過很多專案都有加s，所以這邊是有加s的版本

原則上任何專案都應該有文件，而文件可以放在另外一個地方，但是最好是用markdown和專案放在一起，這樣也可以順便版控文件

整個結構大概會是：

docs
   |--asset
   |--topic 1
     |--asset
     |--sub topic 1
       |--...
     |--README.md
   |-README.md
   |-SUMMARY.md

說明一下：

asset

這個資料夾用來放markdown裡面用到的圖片或者檔案 - 方便鏈接過去

README.md

這個是每一個chapter或者每一個部分的起始頁，有點類似index.html在網站的地位

SUMMARY.md

這個則是整個文件的目錄的概念

src

這個就是主要放程式碼的地方，有些專案會叫他lib或app。

裡面的資料結構大概會是：

src
   |--{project name}.Bll
   |--{project name}.Web
   |-- ...
   |-{project name}.sln

說明一下：

{project name}

這個指的是專案名稱，例如假設我今天有一個xxx專案的網站，那麼我就會有 xxx.Bll作為bll層的csproj位置，xxx.Web作為網站的csproj位置。

{project name}.sln

src進去之後的唯一檔案就是他，這樣不僅很明確如何開啟這個專案，如果有多個sln也不會混在一起

tools

這個資料夾我會放一些工具類的內容。例如說網站都要套版，ui就會放在裡面。

假設有用到一些第三方的dll或者exe也可以放在這邊

.gitignore

.gitignore基本上就是git的忽略檔案 - 忽略那些不要進入版控的檔案。

這個為什麼重要？除了可以讓git的repo小一點之外，也可以避免每一次commit看到一堆修改，或者是在追log的時候看到一些“雜訊”。

什麼才應該commit到git裡面？基本上只要是可以 重新建立出來的都應該進入忽略檔案。例如build出來的bin檔案。

.gitattributes

這個檔案能夠設定git在操作某些檔案的時候要做那些處理。

為什麼重要？還記得之前有一篇介紹關於斷行的問題：[git]為什麼常出現有修改但是比對不卻顯示不出差異？談談檔案斷行問題和如何達到不同平台正確一致化

README.md

這個檔案就好比以前一包html裡面index.html的概念 - 所有資訊的入口都在這個檔案。

為什麼重要？如果沒有一個入口，根本無法快速上手這個專案。尤其目前各個git host都會預設呈現這個檔案的內容。

在這個檔案裡面，一般來說會有幾個內容：

介紹專案的目的

每個專案都有特定目的，介紹清楚可以讓後來看的時候馬上知道這個專案是不是你在找的那個專案。

專案狀態的badge

例如目前最新版本的build狀態，還是透過gitter溝通的網址，這些都可以用badge快速呈現讓使用者一看知道一些資訊。

badge可以參考http://shields.io/

如何快速上手

怎麼讓人能夠快速使用這個專案，例如透過nuget安裝然後使用

其他資訊的鏈接

例如要看文件提供一個鏈接連到docs的README.md檔案；看變更記錄提供鏈接到對應檔案。

網路上蠻多README.md的範例（例如這個https://github.com/fraction/readme-boilerplate）大家都可以參考一下

LICENSE.md

這個很明顯就是open source專案會用到的，明確告訴使用者你的授權模式。

一般來說，如果只是希望版權是你的，但是允許大家做任何修改並且沒有其他限制，那麼MIT最適合。

MIT的license很簡單，就是一段話，把名字改成自己的的名字和年份改成對應年份就好。

CONTRIBUTING.md

這個檔案基本上是介紹如何貢獻到你的專案。

貢獻有很多形式，例如：

1. 翻譯
2. 寫文件
3. 改code - 介紹如何build和改code

這邊也可以提供一些專案目標（roadmap）的資訊，讓其他人知道你的目標。

也可以提到一些這個專案不接受什麼貢獻，避免有人不清楚一直問。

CHANGELOG.md

專案的變更記錄檔案。

這個檔案為什麼重要？

是否能夠讓人家一眼了解版號之間變更的主要目的就是這個檔案要傳達的消息。

和git的log有什麼差別？

切記，git log是細部的說明每次調整什麼，但是這個檔案則是從大局來看到底變動了什麼，所以他絕對不是git log貼上去就好。

github 的 release不就可以寫說明，幹嘛還要有這個檔案？

github release非常巧妙的利用了git tag的資訊讓大家方便找每一個release，但是問題是 假設今天你的repo要搬到別的地方去呢，假設那個hosting不支援release的時候要怎麼辦？因此這個檔案提供一種萬用（universal）資訊的提供位置。

這個檔案應該些什麼？

基本上，每一個版號會有個時間記錄，然後這個版號下面會有 對應的 變更類型（Added、Changed、Deprecated、Removed、Fixed和 Security）

CODE_OF_CONDUCT.md

這個是大家在這個repo合作的合作公約。

不過說實話，我個人覺得意義比較沒那麼大，所以我的範例repo沒有放。

ISSUE_TEMPLATE

這個是github上面才會吃的檔案，當使用者建立一個issue，會有一個範本跑出來。這個檔案就是定義範本內容。

NEW_PULL_REQUEST

一樣是github上面才會吃的檔案，當使用者建立一個pull request呈現的內容，這個範本就是定義那些內容。