本文翻译自《Developing a major version update》。
目录
当你在潜在的新版本中所做的更改不能保证模块用户的向后兼容性时,你必须把这些更改更新到主版本。例如,如果你更改模块的公开API会破坏使用该模块以前版本的客户端代码,你就应该通过开发一个新的主版本来实现这种更改。
注意:每个版本类型——主版本、次版本、补丁版本或预发布版本——对模块的用户来说都有不同的含义。这些用户依靠这些差异来了解版本对他们自己的代码所代表的风险级别。换句话说,在准备发布时,请确保其版本号准确地反映了自上一版本以来的更改的性质。有关版本号的更多信息,请参阅模块版本编号。
另请参阅
- 有关模块开发的概述,请参阅开发和发布模块。
- 有关手把手教学,请参阅模块发布和版本控制工作流程。
主版本更新的注意事项
仅在绝对必要时才更新到新的主版本。因为主版本更新对你和你模块的用户来说都意味着重大的变化。当你考虑进行主版本更新时,请考虑以下事项:
- 发布新的主版本对你以前的主版本的维护意味着什么,你需要向你的用户明确这一点。以前的版本是否已弃用?还是像以前一样支持?你会维护以前的版本,包括Bug修复吗?
- 准备好维护两个版本:旧版本和新版本。例如,如果你修复了一个Bug,你通常会将这些修复移植到另一个中。
- 请记住,从依赖管理的角度来看,新的主版本是一个新模块。在你发布新的主版本后,你的用户将需要更新以使用新模块,而不是简单地升级。这是因为新的主版本与之前的主版本具有不同的模块路径。例如,对于模块路径为example.com/mymodule的模块,v2版本将具有模块路径example.com/mymodule/v2。
- 当你开发新的主版本时,你还必须在导入新模块里的包的那些代码里,修改导入路径。如果你的模块的用户想要升级到新的主版本,他们也必须更改他们的导入路径。
为主版本的发布创建分支
在准备开发新的主版本时,最直接的处理源代码的方式是从存储库创建先前主版本的最新版本的分支。
例如,在命令提示符下,你可以cd到模块的根目录,然后在那里创建一个新的v2分支。
$ cd mymodule
$ git checkout -b v2
Switched to a new branch "v2"
![](https://raw.githubusercontent.com/JohnGuoy/pictureBed/main/开发一个主版本更新/1.png)
创建源代码的分支后,需要对新版本的源代码进行以下更改:
- 在新版本的go.mod文件中,将新的主版本号附加到模块路径,如下例所示:
现有版本:example.com/mymodule
新版本:example.com/mymodule/v2
- 在Go代码中,更新从该模块导入包的每个导入路径,将主版本号附加到模块路径部分。
旧的导入语句:import“example.com/mymodule/package1”
新的导入语句:import“example.com/mymodule/v2/package1”
有关发布步骤,请参见发布一个模块。