模块发布和版本控制工作流

当您开发供其他开发人员使用的模块时，您可以遵循一个工作流，帮助确保使用该模块的开发人员获得可靠、一致的体验。本主题介绍该工作流中的高级步骤。

有关模块开发的概述，请参阅开发和发布模块。

另请参阅

如果您只是想在代码中使用外部软件包，请务必参阅管理依赖项。
对于每个新版本，您都会通过其版本号来表示模块中的更改。有关更多信息，请参阅模块版本编号。

常见工作流步骤

以下序列说明了示例新模块的发布和版本控制工作流步骤。有关每个步骤的详细信息，请参阅本主题中的部分。

开始一个模块并组织其源代码，以便开发人员更轻松地使用，并且您更容易维护。

如果您是模块开发的新手，请查看教程：创建 Go 模块。

在 Go 的分散模块发布系统中，代码的组织方式很重要。有关详细信息，请参阅管理模块源代码。
设置编写本地客户端代码，以调用未发布模块中的函数。

在发布模块之前，它不可用于使用诸如 go get 之类的命令的典型依赖项管理工作流。在此阶段测试模块代码的一个好方法是在其位于调用代码的本地目录中时对其进行尝试。

有关本地开发的详细信息，请参阅针对未发布模块进行编码。
当模块的代码已准备好供其他开发人员试用时，开始发布 v0 预发布版本，例如 alpha 和 beta 版本。有关详细信息，请参阅发布预发布版本。
发布 v0，它不能保证稳定，但用户可以试用。有关详细信息，请参阅发布第一个（不稳定）版本。
发布 v0 版本后，您可以（并且应该！）继续发布新版本。

这些新版本可能包括错误修复（补丁版本）、对模块公共 API 的添加（次要版本）甚至重大更改。由于 v0 版本不保证稳定性或向后兼容性，因此您可以在其版本中进行重大更改。

有关详细信息，请参阅发布错误修复和发布非重大 API 更改。
当您准备发布稳定版本时，您可以发布预发布版本，例如 alpha 和 beta 版本。有关详细信息，请参阅发布预发布版本。
发布 v1 作为第一个稳定版本。

这是第一个对模块稳定性做出承诺的版本。有关详细信息，请参阅发布第一个稳定版本。
在 v1 版本中，继续修复错误，并在必要时对模块的公共 API 进行添加。

有关详细信息，请参阅发布错误修复和发布非重大 API 更改。
在无法避免的情况下，在新的主要版本中发布重大更改。

主版本更新（例如从 v1.x.x 到 v2.x.x）对于模块用户来说可能是一个非常破坏性的升级。这应该是最后的手段。更多信息，请参阅发布破坏性 API 更改。

针对未发布模块进行编码

当您开始开发模块或模块的新版本时，您还没有发布它。在发布模块之前，您将无法使用 Go 命令将该模块添加为依赖项。相反，最初，在编写调用未发布模块中函数的不同模块中的客户端代码时，您需要引用本地文件系统上的模块副本。

您可以通过使用客户端模块的 go.mod 文件中的 replace 指令，从客户端模块的 go.mod 文件中在本地引用模块。更多信息，请参阅在本地目录中需要模块代码。

发布预发布版本

您可以发布预发布版本，以便其他人可以试用模块并向您提供反馈。预发布版本不保证稳定性。

预发布版本号会附加预发布标识符。有关版本号的更多信息，请参阅模块版本编号。

这里有两个示例

v0.2.1-beta.1
v1.2.3-alpha

在提供预发布版本时，请记住，使用预发布版本的开发人员需要通过 go get 命令按版本显式指定它。这是因为在默认情况下，go 命令在查找您请求的模块时，优先选择发布版本而不是预发布版本。因此，开发人员必须通过显式指定它来获取预发布版本，如下例所示

go get example.com/[email protected]

您可以通过在存储库中标记模块代码来发布预发布版本，在标记中指定预发布标识符。更多信息，请参阅发布模块。

发布第一个（不稳定）版本

与发布预发布版本一样，您可以发布不保证稳定性或向后兼容性的发布版本，但让您的用户有机会试用模块并向您提供反馈。

不稳定版本是版本号在 v0.x.x 范围内的版本。v0 版本不提供稳定性或向后兼容性保证。但在使用 v1 及更高版本进行稳定性承诺之前，它为您提供了一种获取反馈并优化 API 的方式。更多信息，请参阅模块版本编号。

与其他已发布版本一样，您可以在向发布稳定 v1 版本迈进时递增 v0 版本号的次要部分和修补程序部分。例如，在发布 v.0.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 版本号，发布第一个稳定版本。有关更多信息，请参阅发布模块。

发布错误修复

您可以发布仅限于错误修复的版本。这称为补丁版本。

补丁版本仅包含次要更改。特别是，它不包含对模块公共 API 的任何更改。使用代码的开发者可以安全地升级到此版本，而无需更改其代码。

注意：您的补丁版本应尽量不将该模块自己的任何传递依赖项升级超过一个补丁版本。否则，升级到您模块的补丁的人可能会意外地将他们使用的传递依赖项拉入更具侵入性的更改。

补丁版本会增加模块版本号的补丁部分。有关更多信息，请参阅模块版本编号。

在以下示例中，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
```
鉴于模块路径是模块的标识符，此更改实际上创建了一个新模块。它还更改了包路径，确保开发人员不会无意中导入破坏其代码的版本。相反，想要升级的人员将明确用新路径替换旧路径的出现。
在你的代码中，更改你正在更新的模块中导入包的任何包路径，包括你正在更新的模块中的包。你需要执行此操作，因为你更改了模块路径。
与任何新版本一样，在发布正式版本之前，您应该发布预发布版本以获取反馈和错误报告。
通过在存储库中标记模块代码来发布新主要版本，将标记中的主要版本号增加 - 例如从 v1.5.2 到 v2.0.0。

更多信息，请参阅发布模块。