开发主要版本更新

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

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

另请参阅

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

主要版本更新的注意事项

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

• 向您的用户清楚说明发布新主要版本对您支持旧主要版本意味着什么。

  旧版本是否已弃用？是否像以前一样受到支持？您是否会维护旧版本，包括进行错误修复？

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

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

  这是因为新的主要版本具有与前一个主要版本不同的模块路径。例如，对于模块路径为 example.com/mymodule 的模块，v2 版本将具有模块路径 example.com/mymodule/v2。

• 当您开发新的主要版本时，您还必须更新所有从新模块导入包的代码中的导入路径。您的模块用户如果想升级到新的主要版本，也必须更新他们的导入路径。

主要版本发布的 branching

在准备开发新主要版本时处理源代码最直接的方法是在上一个主要版本的最新版本处分支存储库。

例如，在命令提示符中，您可以更改到模块的根目录，然后在那里创建一个新的 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"

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