建立存放庫的 README

  • 發行項

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

您的 Git 存放庫應該有自述檔，讓檢視者知道程式碼的用途，以及如何開始使用它。 您的自述檔應該與下列物件交談：

  • 只想要執行程式碼的使用者。
  • 想要建置及測試程式代碼的開發人員。 開發人員也是使用者。
  • 想要將變更提交至程式代碼的參與者。 參與者同時是開發人員和使用者。

在 Markdown 中撰寫自述檔，而不是純文本。 Markdown 可讓您輕鬆地格式化文字、包含影像，以及視需要連結至自述檔中的更多檔。

以下是一些偉大的閱讀內容，使用這個格式，並對所有三個觀眾說話，以參考和靈感：

建立簡介

使用描述您項目的簡短說明，從自述文件開始。 如果您的專案有使用者介面，請在簡介中新增螢幕快照或動畫GIF。 如果您的程式代碼依賴另一個應用程式或連結庫，請務必在簡介中或正下方陳述這些相依性。 只在特定平台上執行的應用程式和工具，應該有自述檔本節中記下支援的操作系統版本。

協助用戶開始使用

引導使用者在自述檔下一節中啟動並執行自己的系統程序代碼。 請專注於開始使用程式代碼的基本步驟。 連結至任何必要軟體的必要版本，讓使用者可以輕鬆地取得這些軟體。 如果您有複雜的設定步驟，請記錄自述檔以外的步驟，並連結至這些步驟。

指出取得最新版程序代碼的位置。 透過封裝工具使用程式碼的二進位安裝程式或指示最好。 如果您的專案是 API 的連結庫或介面，請放置代碼段以顯示基本用法，並顯示該代碼段中程式代碼的範例輸出。

為開發人員提供建置步驟

使用自述檔下一節來示範開發人員如何從存放庫的新複本建置程式代碼，並執行任何包含的測試。 執行下列操作：

  • 提供建置程式代碼所需的工具詳細數據，並記載設定程式代碼以取得全新組建的步驟。
  • 將密集或複雜的建置指示分成檔中的個別頁面，並視需要連結至該頁面。
  • 在您撰寫指示時執行指示，以確認這些指示適用於新的參與者。

請記住，依賴這些指示的開發人員可能是您在一段時間未處理項目之後。

提供命令，以在建置成功之後，執行原始程式碼所提供的任何測試案例。 開發人員會依賴這些測試案例，以確保他們不會在變更程式代碼時中斷程序代碼。 良好的測試案例也可做為範例，開發人員可在新增新功能時用來建置自己的測試案例。

協助用戶參與

自述文件的最後一節可協助使用者和開發人員參與報告問題，並建議讓程式代碼變得更好的想法。 用戶應該連結到可以開啟 Bug、要求功能，或使用程式代碼取得協助的通道。

開發人員必須知道需要遵循哪些規則來參與變更，例如編碼/測試指導方針和提取要求需求。 如果您需要參與者合約接受提取要求或強制執行社群行為規範，則此程式應該連結到本節中或記載。 說明程式代碼在下方發行的授權，並連結至授權的全文。