模組發布和版本控管工作流程

當您為其他開發人員開發模組時，您可以遵循一個工作流程，以協助確保使用模組的開發人員獲得可靠、一致的體驗。此主題說明該工作流程中的高階步驟。

如需模組開發概觀，請參閱開發和發布模組。

另請參閱

• 如果您只是想在程式碼中使用外部套件，請務必參閱管理相依性。
• 隨著每個新版本，您會使用版本號號表示模組的變更。如需更多資訊，請參閱模組版本編號。

常見工作流程步驟

下列順序說明範例新模組的發布和版本控制工作流程步驟。如需每個步驟的更多資訊，請參閱本主題中的各節。

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。

   如需更多資訊，請參閱發布模組。