模块发布和版本管理的工作流程
8 分钟阅读
Module release and versioning workflow - 模块发布和版本管理的工作流程
当您开发模块供其他开发者使用时,您可以遵循一个工作流程,以帮助确保使用该模块的开发者获得可靠、一致的体验。本主题描述了该工作流程中的高级步骤。
关于模块开发的概述,请参阅开发和发布模块。
另请参阅:
常见的工作流程步骤
下面的顺序说明了一个新模块例子的发布和版本管理工作流程步骤。关于每个步骤的更多信息,请参见本主题中的章节。
启用一个模块,并组织它的源代码,使它更容易被开发人员使用,也更容易被您维护。
如果您是开发模块的新手,请查看教程:创建一个Go模块。
在Go的分布式模块发布系统中,您如何组织您的代码很重要。更多信息,请看管理模块源代码。
开始编写本地客户端代码,调用未发布模块中的函数。
在您发布模块之前,它对于使用诸如
go get
命令的典型依赖管理工作流程是不可用的。在这个阶段测试模块代码的一个好方法是将其放在与调用代码相同的本地目录中,并在此目录中进行尝试。。关于本地开发的更多信息,请参见针对未发布模块的编码。
当模块的代码已经准备好供其他开发人员尝试时,可以开始发布 v0 的预发布版本,如 alpha 版和 beta 版。更多信息请参阅发布预发布版本。
发布一个不保证稳定的v0版本,但用户可以试用。更多内容请参见发布第一个(不稳定)版本。
在您的v0版本发布之后,您可以(而且应该!)继续发布新的版本。
这些新版本可能包括 bug 修复(补丁版本 - patch releases)、模块公共 API 的添加(次要版本 - minor releases)甚至是破坏性的变更。由于 v0 版本不保证稳定性或向后兼容性,因此可以在其版本中进行破坏性的变更。
更多信息,请参阅发布bug修复和发布非破坏性的API变更。
当您准备发布一个稳定版本时,您可以将预发布版本发布为 alpha 和 beta 版本。有关更多信息,请参阅发布预发布版本。
发布一个v1版本作为第一个稳定版本。
这是对模块的稳定性做出承诺的第一个版本。更多信息,请参见发布第一个稳定版本。
在v1版本中,继续bug修复,并在必要时对模块的公共 API 进行扩展。
更多信息,请参见发布bug修复和发布非破坏性的API变更。
在无法避免的情况下,使用新的主要版本发布破坏性变更。
主要版本更新(例如从 v1.x.x 到 v2.x.x)对于模块的用户来说可能是一个非常具有破坏性的升级。这应该是最后的选择。有关更多信息,请参阅发布破坏性 API 变更。
针对未发布的模块进行编码
当您开始开发一个模块或一个模块的新版本时,您还没有发布它。在发布模块之前,您将无法使用Go命令将该模块作为依赖项添加。相反,在最初阶段,在编写调用未发布模块中的函数的不同模块的客户端代码时,您需要在本地文件系统上引用该模块的副本。
您可以在客户端模块的go.mod文件中使用replace
指令来从本地引用模块。有关更多信息,请参阅要求本地目录中的模块代码。
发布预发布版本
您可以发布预发布版本,使模块可供其他人尝试并给您提供反馈。预发布版本不包含稳定性保证。
预发布的版本号后面有一个预发布的标识符。更多关于版本号的信息,请参见模块版本编号。
这里有两个示例:
v0.2.1-beta.1
v1.2.3-alpha
发布预发布版本时,请记住使用预发布的开发者需要通过 go get
命令显式指定版本号。这是因为,默认情况下,go
命令在查找所需的模块时会优先选择发布版本而不是预发布版本。因此,开发者必须通过显式指定版本号来获取预发布版本,如以下示例所示:
go get example.com/theirmodule@v1.2.3-alpha
通过在存储库中为该模块代码打标签,并在标签中指定预发布标识符来发布预发布版本。更多信息请参见 发布模块。
发布第一个不稳定版本
当发布预发布版本时,您可以发布不保证稳定性或向后兼容性的发布版本,但给您的用户一个机会来试用模块并给您反馈。
不稳定的发布版本是指其版本号在 v0.x.x 范围内的版本。v0 版本不做任何稳定性或向后兼容性的保证。但它为您在进行 v1 及之后的稳定性承诺之前,获得反馈并完善 API 提供了一种方式。更多信息请参见 模块版本编号。
与其他发布版本一样,您可以在向发布稳定的 v1 版本迈进的过程中递增 v0 版本号的次要版本和修订版本。例如,在发布了 v0.0.0 后,您可以发布带有第一组错误修复的 v0.0.1。
以下是一个示例版本号:
v0.1.3
通过在存储库中为模块代码打标签,并在标签中指定 v0 版本号来发布不稳定的版本。更多信息请参见 发布模块。
发布第一个稳定版本
您的第一个稳定版本将具有 v1.x.x 版本号。第一个稳定版本是在预发布和v0版本之后发布的,通过这些版本您可以得到反馈,修复错误,并为用户稳定模块。
通过 v1 版本的发布,您向使用您的模块的开发者做出以下承诺:
- 他们可以升级到主版本的后续次要版本和修订版本,而不会破坏他们自己的代码。
- 您不会对模块的公共API(包括其函数和方法签名)做进一步的变更,以避免破坏向后兼容性。
- 您不会删除任何导出的类型,以避免破坏向后兼容性。
- 对于 API 的未来变更(例如向结构体添加新字段),将保持向后兼容,并作为新的次要版本发布。
- 错误修复(例如安全修复)将作为修订版本的一部分或作为次要版本的一部分进行发布。
注意: 虽然您的第一个主版本可能是一个 v0 发布,但 v0 版本不表示稳定性或向后兼容性的保证。因此,当您从 v0 升级到 v1 时,无需考虑破坏向后兼容性,因为 v0 发布被认为不稳定。
有关版本号的更多信息,请参阅模块版本编号。
下面是一个稳定版本号的示例:
v1.0.0
您通过在代码库中标记模块代码,并在标签中指定 v1 版本号来发布第一个稳定版本。更多信息请参见发布模块。
发布bug修复
您可以发布仅包含错误修复的版本。这被称为修订版本。
一个修订版本仅包含次要的变更。特别是,它不包含对模块的公共 API 的任何变更。使用该模块的开发者可以安全地升级到此版本,无需修改他们的代码。
Note: Your patch release should try not to upgrade any of that module’s own transitive dependencies by more than a patch release. Otherwise, someone upgrading to the patch of your module could wind up accidentally pulling in a more invasive change to a transitive dependency that they use.
注意: 您的修订版本应尽量避免将该模块自身的传递依赖项(transitive dependencies)升级超过修订版本。否则,升级到您的模块的修订版本时,可能会意外地引入对使用的传递依赖项(transitive dependency)的更大干扰性更改。(transitive 该怎么翻译?)
修订版本会增加模块版本号的修订部分。更多信息请参阅模块版本编号。
在下面的示例中,v1.0.1 是一个修订版本。
旧版本:v1.0.0
新版本: v1.0.1
您可以通过在代码库中标记模块代码,并在标签中递增修订版本号来发布修订版本。更多信息请参见发布模块。
发布非破坏性的API变更
您可以对模块的公共 API 进行非破坏性的变更,并将这些变更发布为次要版本。
该版本变更了 API,但不会破坏调用代码。这可能包括对模块自身的依赖项进行变更或添加新的函数、方法、结构字段或类型。即使包含了这些变更,这种发布方式仍保证了对调用该模块函数的现有代码的向后兼容性和稳定性。
次要版本会递增模块版本号的次要部分。更多信息请参阅模块版本编号。
在下面的示例中,v1.1.0 是一个次要版本。
旧版本: v1.0.1
新版本: v1.1.0
您可以通过在代码库中标记模块代码,并在标签中递增次要版本号来发布次要版本。更多信息请参见发布模块。
发布破坏性的API变更
您可以通过发布一个主要版本来引入破坏性的向后不兼容变更。
主要版本发布不保证向后兼容性,通常是因为它包含了对模块的公共 API 进行的变更,这些变更会破坏使用该模块先前版本的代码。
考虑到主要版本升级对依赖该模块的代码可能产生的破坏性影响,如果可能的话,应避免进行主要版本更新。有关主要版本更新的更多信息,请参阅开发主要版本更新。有关避免进行破坏性变更的策略,请参阅博文保持模块的兼容性。
发布其他类型的版本基本上只需通过标记模块代码与版本号,而发布主要版本更新则需要更多步骤。
在开始开发新的主要版本之前,在您的代码库中创建一个用于新版本源代码的位置。
一种方法是在代码库中创建一个专门用于新的主要版本及其后续的次要和修订版本的新分支。更多信息,请参见管理模块源代码。
在该模块的 go.mod 文件中,修改其模块路径以附加新的主要版本号,就像下面的示例一样:
example.com/mymodule/v2
考虑到该模块路径是模块的标识符,这个更改实际上创建了一个新的模块。它还更改了包路径,确保开发者不会意外地导入破坏他们代码的版本。相反,那些想要升级的人将显式地将旧路径的出现替换为新路径。
In your code, change any package paths where you’re importing packages in the module you’re updating, including packages in the module you’re updating. You need to do this because you changed your module path.在您的代码中,改变任何您要导入的模块中的包的路径,包括您要更新的模块中的包。您需要这样做是因为您改变了您的模块路径。在您的代码中,修改那些(导入您正在更新的该模块中的)包的任何包路径,包括那些(您正在更新的该模块中的)包 【这里翻译还是有点问题——待处理】。您需要这样做是因为您改变了您的模块路径。
与任何新版本一样,您应该发布预发布版本以获得反馈和bug报告,然后再发布官方版本。
通过在您的代码库中标记该模块代码并递增标记中的主要版本号来发布新的主要版本,例如从 v1.5.2 到 v2.0.0。
更多信息,请参见发布模块。