开发主要版本更新

当您在潜在的新版本中所做的更改无法保证模块用户的向后兼容性时，您必须更新到主要版本。例如，如果您更改模块的公共 API 以破坏使用该模块先前版本的客户端代码，您将进行此更改.

注意: 每个发布类型 – 主要、次要、补丁或预发布 – 对模块的用户都有不同的含义。这些用户依靠这些差异来了解版本对他们自己的代码所代表的风险级别。换句话说，在准备发布时，请确保其版本号准确地反映了自上一版本以来更改的性质。有关版本号的更多信息，请参阅模块版本编号.

另请参见

• 有关模块开发的概述，请参阅开发和发布模块.
• 有关端到端视图，请参阅模块发布和版本控制工作流.

主要版本更新的注意事项

仅在绝对必要时才应更新到新的主要版本。主要版本更新对您和您的模块用户来说都意味着重大的改动。在考虑主要版本更新时，请考虑以下事项:

• 与您的用户明确发布新的主要版本对您支持以前的主要版本意味着什么。

  以前的版本是否已弃用？像以前一样得到支持？您是否会维护以前的版本，包括bug修复?

• 准备好维护两个版本：旧版本和新版本。例如，如果您修复了一个错误，您通常会将这些修复移植到另一个中.

• 请记住，从依赖管理的角度来看，新的主要版本是一个新模块。在您发布后，您的用户将需要更新以使用新模块，而不是简单地升级.

  这是因为新的主要版本与之前的主要版本具有不同的模块路径。例如，对于模块路径为 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"

有关发布步骤，请参阅发布模块 发布模块.