<!--{
  "Title": "开发主版本更新"
}-->

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

> **注意：** 每种发布类型——主版本、次版本、修订版或预发布版——对模块用户具有不同含义。用户依赖这些差异来理解发布版本对其自身代码的风险程度。换言之，在准备发布时，请确保版本号准确反映自上次发布以来变更的性质。有关版本号的更多信息，请参阅[模块版本编号](/doc/modules/version-numbers)。

**另请参阅**

* 模块开发概述请参阅[开发与发布模块](developing)。
* 完整流程请参阅[模块发布与版本控制工作流](release-workflow)。

## 主版本更新的考量因素 {#considerations}

仅在绝对必要时才应更新到新的主版本。主版本更新对您和模块用户都意味着重大变更。考虑主版本更新时，请思考以下几点：

* 向用户明确说明发布新主版本对您支持旧主版本的影响。

  旧版本是否已弃用？是否继续提供原有支持？您是否会维护旧版本（包括错误修复）？

* 准备好维护两个版本：新版本和旧版本。例如，如果在某个版本中修复了错误，通常需要将修复移植到另一个版本。

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

  因为新主版本的模块路径与之前的主版本不同。例如，模块路径为 `example.com/mymodule` 的模块，其v2版本的模块路径将变为 `example.com/mymodule/v2`。

* 开发新主版本时，还需更新所有导入新模块包的代码路径。模块用户若想升级到新主版本，也必须更新其导入路径。

## 主版本分支策略 {#branching}

准备开发新主版本时，处理源代码最直接的方法是在前一个主版本的最新版本处对代码仓库进行分支。

例如，在命令提示符中，您可以切换到模块的根目录，然后在那里创建新的 `v2` 分支。

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

     alt="展示从主分支创建 v2 分支的示意图"
     style="width: 600px;" />

完成源代码分支后，需要对新版本的源代码进行以下修改：

* 在新版本的 `go.mod` 文件中，将新的主版本号追加到模块路径，示例如下：
  * 现有版本：`example.com/mymodule`
  * 新版本：`example.com/mymodule/v2`

* 在 Go 代码中，更新所有导入该模块包的导入路径，将主版本号追加到模块路径部分。
  * 旧导入语句：`import "example.com/mymodule/package1"`
  * 新导入语句：`import "example.com/mymodule/v2/package1"`

发布步骤请参阅[发布模块](/doc/modules/publishing)。