開發主要版本更新

當你在潛在的新版本中所做的變更無法保證模組使用者的後向相容性時，你必須更新至主要版本。例如，如果你變更模組的公開 API，導致使用模組先前版本的用戶端程式碼中斷，你就會進行此變更。

注意：每個發行類型（主要、次要、修補或預發行）對模組使用者而言都有不同的意義。這些使用者依賴這些差異來了解發行對其自身程式碼的風險等級。換句話說，在準備發行時，請確保其版本號準確反映自前一次發行以來的變更性質。有關版本號碼的詳細資訊，請參閱模組版本編號。

另請參閱

• 有關模組開發的概觀，請參閱開發和發布模組。
• 有關端到端的檢視，請參閱模組發行和版本控管工作流程。

主要版本更新的考量因素

你應該只在絕對必要時更新至新的主要版本。主要版本更新對你和你模組的使用者而言都代表著重大的變動。當你考慮主要版本更新時，請考慮下列事項

• 對你的使用者清楚說明發行新的主要版本對你支援先前主要版本的意義。

  先前版本是否已棄用？是否像以前一樣受到支援？你是否會維護先前版本，包括錯誤修正？

• 準備好承擔兩個版本的維護工作：舊版本和新版本。例如，如果你修正其中一個版本的錯誤，你通常會將這些修正移植到另一個版本。

• 請記住，從依賴項管理的角度來看，新的主要版本是一個新的模組。你的使用者在發行後需要更新才能使用新的模組，而不能只是升級。

  這是因為新主要版本與前一個主要版本具有不同的模組路徑。例如，對於模組路徑為 example.com/mymodule 的模組，v2 版本的模組路徑為 example.com/mymodule/v2。

• 當您開發新主要版本時，您還必須更新匯入路徑，無論程式碼從新模組匯入套件在哪裡。您的模組使用者也必須更新他們的匯入路徑，如果他們想要升級到新主要版本。

分支主要版本

準備開發新主要版本時，處理原始碼最直接的方法是在前一個主要版本的最新版本分支儲存庫。

例如，在命令提示字元中，您可能會變更到模組的根目錄，然後在那裡建立新的 v2 分支。

$ cd mymodule
$ git checkout -b v2
Switched to a new branch "v2"

一旦您分支原始碼，您需要對新版本的原始碼進行以下變更

• 在新的版本的 go.mod 檔案中，將新的主要版本號碼附加到模組路徑，如下面的範例

  • 現有版本：example.com/mymodule
  • 新版本：example.com/mymodule/v2

• 在您的 Go 程式碼中，更新您從模組匯入套件的每個匯入套件路徑，將主要版本號碼附加到模組路徑部分。

  • 舊匯入陳述式：import "example.com/mymodule/package1"
  • 新匯入陳述式：import "example.com/mymodule/v2/package1"

有關發佈步驟，請參閱 發佈模組。