开发主要版本更新

当您在潜在的新版本中所做的更改无法保证模块用户的向后兼容性时，您必须更新到主要版本。例如，如果您更改模块的公共 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"

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