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

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

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

另请参见

常见的工作流步骤

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

  1. 开始一个模块 并组织它的源代码，使开发人员更容易使用和维护。

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

    在 Go 的去中心化模块发布系统中，如何组织代码很重要。有关更多信息，请参阅管理模块源。

  2. 创建为编写调用未发布模块中的函数的本地客户端代码.

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

    有关本地开发的更多信息，请参阅 针对未发布的模块进行编码.

  3. 当模块的代码准备好供其他开发人员试用时， 开始发布 v0 预发布版本，例如 alphas 和 betas。有关更多信息，请参阅 发布预发布版本.

  4. 发布一个v0 不保证稳定，但用户可以尝试。有关更多信息，请参阅 发布第一个（不稳定）版本.

  5. 在您的 v0 版本发布后，您可以（并且应该！）继续发布它的新版本.

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

    有关更多信息，请参阅发布bug修复和发布非破坏性 API 更改.

  6. 当您准备好发布稳定版本时，您可以将预发布版本发布为 alphas 和 betas。有关更多信息，请参阅发布预发布版本.

  7. 发布 v1 作为第一个稳定版本.

    这是对模块稳定性做出承诺的第一个版本。有关更多信息，请参阅发布第一个稳定版本.

  8. 在 v1 版本中，继续修复bug，并在必要时向模块的公共 API 添加内容.

    有关更多信息，请参阅 发布bug修复 和 发布非破坏性 API 更改.

  9. 如果无法避免，请在新的主要版本中发布重大更改。

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

针对未发布的模块进行编码

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

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

发布预发布版本

您可以发布预发布版本以使模块可供其他人试用并给您反馈。预发布版本不包括稳定性保证。

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

这里有两个例子:

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 版本号的次要和补丁部分。例如，在发布 v.0.0.0 之后，您可能会发布带有第一组bug修复的 v0.0.1。

这是一个示例版本号:

v0.1.3

您可以通过标记存储库中的模块代码来发布不稳定版本，并在标记中指定 v0 版本号。有关更多信息，请参阅发布模块.

发布第一个稳定版本

您的第一个稳定版本将具有 v1.x.x版本号。第一个稳定版本是在预发布和 v0 版本之后发布的，您可以通过它们获得反馈、bug错误并为用户稳定模块.

在 v1 版本中，您向使用您的模块的开发人员做出以下承诺:

注意: 虽然您的第一个主要版本可能是 v0 版本，但 v0 版本并不表示稳定性或向后兼容性保证。因此，当您从 v0 递增到 v1 时，您无需注意破坏向后兼容性，因为 v0 版本被认为不稳定。

有关版本号的更多信息，请参阅 模块版本编号.

下面是一个稳定版本号的例子:

v1.0.0

您可以通过在存储库中标记模块代码，并在标记中指定 v1 版本号来发布第一个稳定版本。有关详细信息，请参阅发布模块。

发布bug修复

您可以发布一个版本，其中的更改仅限于bug修复。这称为补丁版本.

补丁版本 仅包含较小的更改。特别是，它没有对模块的公共 API 进行任何更改。使用代码的开发人员可以安全地升级到这个版本，而无需更改他们的代码.

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

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

在以下示例中，v1.0.1 是一个补丁版本.

旧版本: v1.0.0

新版本: v1.0.1

您可以通过标记存储库中的模块代码来发布补丁版本，并增加标记中的补丁版本号。有关更多信息，请参阅发布模块。

发布非破坏性API 更改

您可以对模块的公共 API 进行非破坏性更改，并在 次要 版本中发布这些更改。

此版本更改了 API，但不会破坏调用代码。这可能包括对模块自身依赖项的更改或添加新函数、方法、结构字段或类型。即使包含了更改，这种版本也保证了调用模块函数的现有代码的向后兼容性和稳定性.

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

在以下示例中，v1.1.0 是次要版本.

旧版本: v1.0.1

新版本: v1.1.0

您可以通过标记存储库中的模块代码来发布次要版本，并增加标记中的次要版本号。有关更多信息，请参阅发布模块。

发布破坏性 API 更改

您可以通过发布 主要 版本来发布破坏向后兼容性的版本。

主要版本不保证向后兼容性，通常是因为它包含对模块公共 API 的更改，这些更改会破坏使用模块以前版本的代码.

鉴于主要版本升级可能对依赖于模块的代码产生破坏性影响，如果可以的话，您应避免进行主要版本更新。有关主要版本更新的更多信息，请参阅开发主要版本更新。有关避免进行重大更改的策略，请参阅博客文章保持你的模块兼容.

发布其他类型的版本实质上需要使用版本号标记模块代码，而发布主要版本更新需要更多步骤.

  1. 在开始开发新的主要版本之前，在您的存储库中为新版本的源代码创建一个位置.

    一种方法是在存储库中创建一个新分支，专门用于新的主要版本及其后续的次要和补丁版本。有关更多信息，请参阅管理模块源.

  2. 在模块的 go.mod 文件中，修改模块路径以附加新的主要版本号，如下例所示:

    example.com/mymodule/v2

    鉴于模块路径是模块的标识符，此更改有效地创建了一个新模块。它还更改了包路径，确保开发人员不会无意中导入破坏其代码的版本。相反，那些想要升级的人会用新路径明确替换旧路径.

  3. 在您的代码中，更改您正在更新的模块中导入包的任何包路径，包括您正在更新的模块中的包。您需要这样做，因为您更改了模块路径.

  4. 与任何新版本一样，您应该在发布正式版本之前发布预发布版本以获得反馈和错误报告.

  5. 通过在存储库中标记模块代码，递增标记中的主要版本号（例如从 v1.5.2 到 v2.0.0），发布新的主要版本.

    有关更多信息，请参阅发布模块.

注 ：名词：主要（major），次要（minor），补丁（patch),预发布（ pre-release ），稳定（stable)，非稳定（unstable).