模組釋出和版本控制工作流

當您開發供其他開發人員使用的模組時，可以遵循一個工作流，以幫助確保使用該模組的開發人員獲得可靠、一致的體驗。本主題描述了該工作流中的高階步驟。

有關模組開發的概述，請參閱開發和釋出模組。

另請參閱

• 如果您只是想在程式碼中使用外部包，請務必檢視管理依賴項。
• 對於每個新版本，您都透過其版本號來表示模組的更改。有關更多資訊，請參閱模組版本號。

常見工作流步驟

以下序列說明了新模組釋出和版本控制工作流的步驟。有關每個步驟的更多資訊，請參閱本主題中的部分。

1. 開始一個模組並組織其原始碼，以便開發人員更容易使用和您更容易維護。

   如果您是模組開發新手，請檢視教程：建立一個Go模組。

   在Go的去中心化模組釋出系統中，您組織程式碼的方式很重要。有關更多資訊，請參閱管理模組原始碼。

2. 設定編寫本地客戶端程式碼，該程式碼呼叫未釋出的模組中的函式。

   在您釋出模組之前，它無法用於使用go get等命令的典型依賴管理工作流。在此階段測試模組程式碼的好方法是在其位於呼叫程式碼的本地目錄中時進行嘗試。

   有關本地開發的更多資訊，請參閱針對未釋出的模組進行編碼。

3. 當模組程式碼準備好供其他開發人員試用時，開始釋出v0預釋出版本，例如alpha和beta版本。有關更多資訊，請參閱釋出預釋出版本。

4. 釋出一個v0版本，該版本不保證穩定，但使用者可以試用。有關更多資訊，請參閱釋出第一個（不穩定）版本。

5. 您的v0版本釋出後，您可以（並且應該！）繼續釋出新版本。

   這些新版本可能包括錯誤修復（補丁版本）、模組公共API的新增（次要版本），甚至是不相容的更改。由於v0版本不保證穩定性或向後相容性，您可以在其版本中進行不相容的更改。

   有關更多資訊，請參閱釋出錯誤修復和釋出非不相容API更改。

6. 當您準備釋出穩定版本時，您將預釋出版本釋出為alpha和beta版本。有關更多資訊，請參閱釋出預釋出版本。

7. 釋出v1作為第一個穩定版本。

   這是第一個對模組穩定性做出承諾的釋出。有關更多資訊，請參閱釋出第一個穩定版本。

8. 在v1版本中，繼續修復錯誤，並在必要時對模組的公共API進行新增。

   有關更多資訊，請參閱釋出錯誤修復和釋出非不相容API更改。

9. 當無法避免時，在新主要版本中釋出不相容的更改。

   主要版本更新（例如從v1.x.x到v2.x.x）對於模組使用者來說可能是一個非常具有破壞性的升級。它應該作為最後手段。有關更多資訊，請參閱釋出不相容API更改。

針對未釋出的模組進行編碼

當您開始開發模組或模組的新版本時，您尚未釋出它。在您釋出模組之前，您將無法使用Go命令將該模組新增為依賴項。相反，起初，當在呼叫未釋出模組中函式的不同模組中編寫客戶端程式碼時，您需要引用本地檔案系統上的模組副本。

您可以使用客戶端模組的go.mod檔案中的replace指令從客戶端模組的go.mod檔案本地引用模組。有關更多資訊，請參閱在本地目錄中要求模組程式碼。

釋出預釋出版本

您可以釋出預釋出版本，以便其他人可以試用模組並向您提供反饋。預釋出版本不保證穩定性。

預釋出版本號後附加預釋出識別符號。有關版本號的更多資訊，請參閱模組版本號。

以下是兩個示例

v0.2.1-beta.1
v1.2.3-alpha

在提供預釋出版本時，請記住，使用預釋出版本的開發人員需要使用go get命令透過版本明確指定它。這是因為，預設情況下，go命令在查詢您請求的模組時更喜歡釋出版本而不是預釋出版本。因此，開發人員必須透過明確指定預釋出版本來獲取它，如以下示例所示

go get example.com/theirmodule@v1.2.3-alpha

您透過在儲存庫中標記模組程式碼來發布預釋出版本，並在標籤中指定預釋出識別符號。有關更多資訊，請參閱釋出模組。

釋出第一個（不穩定）版本

與釋出預釋出版本一樣，您可以釋出不保證穩定性或向後相容性的釋出版本，但讓您的使用者有機會試用模組並向您提供反饋。

不穩定版本是版本號在v0.x.x範圍內的版本。v0版本不作任何穩定性或向後相容性保證。但它為您提供了一種在v1及更高版本做出穩定性承諾之前獲取反饋和完善API的方法。有關更多資訊，請參閱模組版本號。

與其他已釋出版本一樣，您可以在進行更改以釋出穩定的v1版本時，遞增v0版本號的次要和補丁部分。例如，在釋出v.0.0.0之後，您可能會發布帶有第一組錯誤修復的v0.0.1。

這是一個版本號示例

v0.1.3

您透過在儲存庫中標記模組程式碼來發布不穩定版本，並在標籤中指定v0版本號。有關更多資訊，請參閱釋出模組。

釋出第一個穩定版本

您的第一個穩定版本將具有v1.x.x版本號。第一個穩定版本是在您透過預釋出和v0版本獲得反饋、修復錯誤併為使用者穩定模組之後釋出的。

透過v1版本，您向使用您模組的開發人員做出以下承諾

• 他們可以升級到主要版本的後續次要和補丁版本，而不會破壞自己的程式碼。
• 您將不再對模組的公共API（包括其函式和方法簽名）進行任何破壞向後相容性的更改。
• 您將不會刪除任何匯出的型別，因為這會破壞向後相容性。
• 您API的未來更改（例如向結構體新增新欄位）將向後相容，並將包含在新的次要版本中。
• 錯誤修復（例如安全修復）將包含在補丁版本中或作為次要版本的一部分。

注意：雖然您的第一個主要版本可能是v0版本，但v0版本不表示穩定性或向後相容性保證。因此，當您從v0遞增到v1時，您不必擔心破壞向後相容性，因為v0版本不被認為是穩定的。

有關版本號的更多資訊，請參閱模組版本號。

這是一個穩定版本號的示例

v1.0.0

您透過在儲存庫中標記模組程式碼來發布第一個穩定版本，並在標籤中指定v1版本號。有關更多資訊，請參閱釋出模組。

釋出錯誤修復

您可以釋出一個只包含錯誤修復的釋出版本。這被稱為補丁版本。

補丁版本只包含細微的更改。特別是，它不包含對模組公共API的任何更改。使用程式碼的開發人員可以安全地升級到此版本，而無需更改其程式碼。

注意：您的補丁版本應儘量不要將其自身的任何傳遞依賴項升級超過一個補丁版本。否則，升級到您模組補丁版本的人可能會意外地引入他們使用的傳遞依賴項的更具侵入性的更改。

補丁版本遞增模組版本號的補丁部分。有關更多資訊，請參閱模組版本號。

在以下示例中，v1.0.1是一個補丁版本。

舊版本：v1.0.0

新版本：v1.0.1

您透過在儲存庫中標記模組程式碼來發布補丁版本，並在標籤中遞增補丁版本號。有關更多資訊，請參閱釋出模組。

釋出非破壞性API更改

您可以對模組的公共API進行非破壞性更改，並在次要版本釋出中釋出這些更改。

此版本更改了API，但不會以破壞呼叫程式碼的方式進行。這可能包括對模組自身依賴項的更改或新函式、方法、結構體欄位或型別的新增。即使包含這些更改，此類釋出仍保證現有呼叫模組函式的程式碼的向後相容性和穩定性。

次要版本遞增模組版本號的次要部分。有關更多資訊，請參閱模組版本號。

在以下示例中，v1.1.0是一個次要版本。

舊版本：v1.0.1

新版本：v1.1.0

您透過在儲存庫中標記模組程式碼來發布次要版本，並在標籤中遞增次要版本號。有關更多資訊，請參閱釋出模組。

釋出破壞性API更改

您可以透過釋出主要版本釋出來發布破壞向後相容性的版本。

主要版本釋出不保證向後相容性，通常是因為它包含對模組公共API的更改，這些更改會破壞使用模組先前版本的程式碼。

鑑於主要版本升級可能對依賴模組的程式碼產生破壞性影響，如果可能，您應該避免主要版本更新。有關主要版本更新的更多資訊，請參閱開發主要版本更新。有關避免進行破壞性更改的策略，請參閱部落格文章保持模組相容。

釋出其他型別的版本基本上只需用版本號標記模組程式碼，而釋出主要版本更新則需要更多步驟。

1. 在新主要版本開發開始之前，在您的儲存庫中為新版本的原始碼建立一個位置。

   一種方法是在您的儲存庫中建立一個專門用於新主要版本及其後續次要和補丁版本的新分支。有關更多資訊，請參閱管理模組原始碼。

2. 在模組的go.mod檔案中，修改模組路徑以附加新的主要版本號，如以下示例所示

   example.com/mymodule/v2
   

   鑑於模組路徑是模組的識別符號，此更改有效地建立了一個新模組。它還更改了包路徑，確保開發人員不會無意中匯入一個破壞其程式碼的版本。相反，那些想要升級的人將明確地用新路徑替換舊路徑的出現。

3. 在您的程式碼中，更改您正在更新的模組中匯入包的任何包路徑，包括您正在更新的模組中的包。您需要這樣做是因為您更改了模組路徑。

4. 與任何新發布一樣，您應該釋出預釋出版本以獲取反饋和錯誤報告，然後再發布正式版本。

5. 透過在儲存庫中標記模組程式碼來發布新的主要版本，並在標籤中遞增主要版本號——例如從v1.5.2到v2.0.0。

   有關更多資訊，請參閱釋出模組。