发布 PLC4X 构建工具

与主项目不同，plc4x-build-tools 仓库是一组相对松散的子项目的集合。

根目录中的主要 pom.xml 主要用于将所有模块导入 IDE，不应将其用于发布。

如果你想发布构建工具的某个部分，请在 parts 子目录中执行以下发布步骤。

总体而言，发布某个构建工具的准备步骤与主项目的准备步骤相同。因此请查阅这里（章节：Preparing your system for being able to release 与 Preparing the codebase for a release）]。

其余步骤比主项目的步骤简单得多，因为其中不涉及任何 profile。

创建发布分支（针对代码生成模块）

根据 SemVer 规范，我们有 Major、Minor 和 Bugfix 三种发布。

每次新的 Major 和 Minor 发布，我们都会在代码冻结阶段开始时创建一个新分支。

因此，如果 develop 中当前的项目版本为 {1.0.0}，我们就创建一个 release/{code-generation-short-version} 分支。

创建分支的时刻，正是 develop 中的版本号递增到下一个次要版本的时刻。

这可以并且应当由 maven-release-plugin 自动完成。

默认情况下，该插件会在构建执行期间询问工作副本的版本。develop 分支将被更改为这个版本。

mvn release:branch -DbranchName=releases/code-generation/{minor-version}

默认情况下，插件建议的下一个 bugfix 版本作为工作版本，但我们希望它使用下一个次要版本。因此，如果要为 {1.0.0} 准备发布分支，命令如下：

   mvn release:branch -DbranchName=releases/code-generation/{code-generation-short-version}

随后插件会询问版本号：

   What is the new working copy version for "PLC4X Build Tools: Code Generation"? (org.apache.plc4x.plugins:plc4x-code-generation) {code-generation-bugfix-version}-SNAPSHOT: : {code-generation-development-version}-SNAPSHOT

其中建议的默认值已被手动覆盖。

由于不涉及任何构建和测试，此步骤现在应当执行得相当快。

不过，最后 develop 分支的版本会被更新，并且会创建一个新的 releases/code-generation/{code-generation-short-version} 分支。

为下一轮迭代准备 `develop`

现在正是在 RELEASE_NOTES 文档中为新的 SNAPSHOT 版本添加新章节的好时机。

以下是一个模板：

==============================================================
(Unreleased) Apache PLC4X {code-generation-development-version}-SNAPSHOT
==============================================================

New Features
------------

Incompatible changes
--------------------

Bug Fixes
---------

// Rest of the file

之后请从下一部分中移除 (Unreleased)，因为我们目前正在处理它的发布。

同时，请务必进行一次全文搜索，以确认版本号在所有位置都已正确更新。

	如果在此处发现任何问题，你需要在发布过程中加以注意。

发布稳定阶段

接下来通常会进入一个阶段，需要执行最后的测试和检查。

如果发现问题，必须在发布分支中予以修复。

相关变更应当重新应用到 develop 或 cherry-picked 中；不过，将内容合并回来可能会引发大量问题，而且我们已经不再使用相同的版本号了。

准备发布

在开始准备发布之前，重要的一点是手动调整 RELEASE_NOTES，使其与我们计划发布的版本一致。

	继续之前，请确保已经切换到发布分支。

因此，请务必从版本号中移除 (Unreleased) 和 SNAPSHOT。

尤其是在频繁切换不同分支的情况下，建议对仓库进行一次干净的检出。否则，可能会残留大量目录，而这些目录会被包含在源码发布 zip 包中。为了准备一个发布候选版本，第一步是切换到相应的发布分支。

	再次提醒，以防你错过了第一条警告：继续之前，请确保已经切换到发布分支。

之后，以下命令将执行发布所需的全部准备工作：

mvn release:prepare

通常，该插件会询问你 3 个问题：

我们想要发布的版本（它会建议你使用去掉 -SNAPSHOT 后缀的版本，保持不变即可）
发布提交在 SCM 中被打上的标签名称（命名为 releases/code-generation/{release-version}（在我们的例子中是 releases/code-generation/{1.0.0}））
下一个开发版本（发布后 pom 中的版本）（保持插件建议的版本即可）

通常第 1 项和第 3 项使用默认值即可，但要确保标签名称正确，因为它通常与默认值不同。

不过，重要的是要检查其他地方没有引用 SNAPSHOT 版本。

插件接下来会自动执行以下操作：

检查我们没有引用任何 SNAPSHOT 依赖。
将所有 pom 版本更新为发布版本。
运行包含所有测试的构建
提交更改（提交信息：[maven-release-plugin] prepare release releases/code-generation/{1.0.0}）
推送提交
为提交打标签
将所有 pom 更新为下一个开发版本。
提交更改（提交信息：[maven-release-plugin] prepare for next development iteration）
推送提交

不过，这仅仅准备好了用于发布的 git 仓库，我们还需要执行发布流程来生成并暂存发布构件。

请验证位于 https://gitbox.apache.org/repos/asf?p=plc4x-build-tools.git 的 git 仓库处于正确状态。请选择发布分支，并验证提交日志看起来类似如下：

release git history

确保提交信息为 "[maven-release-plugin] prepare release releases/code-generation/{1.0.0}" 的提交被打上了发布标签（在本例中为 releases/code-generation/{1.0.0}）这一点非常重要

如果你查看该提交本身，它应该主要由如下版本更新组成：

release git diff prepare release

根 pom 还有一些其他的更改，但总体上你应该看到这样的内容。

随后应该是第二个提交：

release git diff next development iteration

这会再次更新版本，但这次是从发布版本更新为我们选定的下一个开发版本（在本例中为 {code-generation-bugfix-version}-SNAPSHOT）

	如果提交历史不是这样的，则说明出了问题。

如果出了问题怎么办？

如果出了问题，你可以随时执行：

mvn release:rollback

它会将版本号改回原样，并进行提交与推送。

不过，它不会删除 GIT 中的标签（无论本地还是远程）。因此你必须手动删除，或者下次使用不同的标签。

执行发布

通过执行 maven-release-plugin 的另一个目标来完成：

mvn release:perform

此步骤会自动执行，因为它所需的全部信息都已由 prepare 目标准备好，存放于 release.properties 文件中。

第一步是 perform 目标将先前打过标签的修订版检出到根模块的 target/checkout 目录中。在此过程中，它会自动执行一次 Maven 构建（你不必手动执行，这里只是让你了解发生了什么）：

mvn clean deploy -P apache-release

随着 apache-release 配置的激活，该项目将被构建和测试，同时生成 JavaDoc、源码包，并使用你的 PGP 密钥对每一样进行签名。

由于此次构建使用的是发布版本，Maven 会自动选择用于部署构件的发布 URL。

在 Apache 父 POM 中的配置方式是：发布构件会被部署到所谓的 staging repository 中。

你可以把 staging repository 理解为在第一个构件到达时即时创建的专用仓库。

构建完成后，你将在 https://repository.apache.org/ 上得到一个干净整洁的 Maven 仓库，其中只包含本次构建产生的构件。

构建完成后，请务必登录 https://repository.apache.org/ 上的 Nexus，选择 Staging Repositories，并找到名称为 orgapacheplc4x-{somenumber} 的仓库。

选中它并点击 Close 按钮。

随后 Nexus 将对构件进行一些检查，并验证其签名。

一旦检查完成，Maven 这一侧的工作就全部结束了，我们可以继续进行发布流程的其余步骤。

发布构建还会生成一个所谓的 source-assembly zip 压缩包。

它包含项目的所有源代码，从 Apache 的角度来说，这才是真正的发布内容，也是我们将要投票表决的对象。

该文件同样会被签名，并生成 SHA512 校验和。

暂存发布

每个新的发布版本和发布候选版本都必须在 Apache SVN 中暂存，路径为：

https://dist.apache.org/repos/dist/dev/plc4x/

   ./KEYS
   ./build-tools/code-generation/{1.0.0}
   ./build-tools/code-generation/{1.0.0}/rc1
   ./build-tools/code-generation/{1.0.0}/rc1/README
   ./build-tools/code-generation/{1.0.0}/rc1/RELEASE_NOTES
   ./build-tools/code-generation/{1.0.0}/rc1/apache-plc4x-code-generation-{1.0.0}-source-release.zip
   ./build-tools/code-generation/{1.0.0}/rc1/apache-plc4x-code-generation-{1.0.0}-source-release.zip.asc
   ./build-tools/code-generation/{1.0.0}/rc1/apache-plc4x-code-generation-{1.0.0}-source-release.zip.sha512

我通常会准备完全相同的目录结构，先在本地从 {1.0.0} 开始，然后使用以下命令将所有内容导入：

svn import {1.0.0} https://dist.apache.org/repos/dist/dev/plc4x/build-tools/code-generation/{1.0.0} -m"Staging of rc1 of PLC4X Build-Tools (Code-Generation) {1.0.0}"

KEYS 文件包含与用于签署发布产物的私钥相对应的 PGP 公钥。

如果这是你的第一次发布，请务必将你的密钥添加到该文件中。关于格式，请查看该文件本身，它应当包含所需的全部信息。

请确保暂存的正是项目根目录中包含的 README 和 RELEASE_NOTES 文件。理想情况下，你只需将它们从原位置复制过来即可。

三个 -source-release.zip 产物应当位于目录：code-generation/target/checkout/code-generation/target 中

将这些文件提交到 SVN 后，你就可以开始发起投票了。

在邮件列表上发起投票

在 Apache SVN 中暂存发布候选版本之后，就该正式发出投票号召了。

为此，我们通常会发送两封邮件。下面这封将用于我们首次 TLP 发布：

E-Mail Topic:
[VOTE] Apache PLC4X Build-Tools Code-Generation {1.0.0} RC1

Message:
Apache PLC4X Build-Tools Code-Generation {1.0.0} has been staged under [2]
and it’s time to vote on accepting it for release.

All Maven artifacts are available under [1]. Voting will be open for 72hr.

A minimum of 3 binding +1 votes and more binding +1 than binding -1
are required to pass.

Repository: https://gitbox.apache.org/repos/asf/plc4x-build-tools.git
Release tag: releases/code-generation/{1.0.0}
Hash for the release tag: {replacethiswiththerealgitcommittag}

Per [3] "Before voting +1 PMC members are required to download
the signed source code package, compile it as provided, and test
the resulting executable on their own platform, along with also
verifying that the package meets the requirements of the ASF policy
on releases."

You can achieve the above by following [4].

[ ]  +1 accept (indicate what you validated - e.g. performed the non-RM items in [4])
[ ]  -1 reject (explanation required)


[1] https://repository.apache.org/content/repositories/orgapacheplc4x-{somefourdigitnumber}
[2] https://dist.apache.org/repos/dist/dev/plc4x/build-tools/code-generation/{1.0.0}/rc1/
[3] https://www.apache.org/legal/release-policy.html#approving-a-release
[4] https://plc4x.apache.org/plc4x/latest/developers/release/validation.html

由于在投票与讨论混在同一邮件线程中时统计票数有时较为困难，我们会另外发送第二封邮件：

E-Mail Topic:
[DISCUSS] Apache PLC4X Build-Tools Code-Generation {1.0.0} RC1

Message:
This is the discussion thread for the corresponding VOTE thread.

Please keep discussions in this thread to simplify the counting of votes.

If you have to vote -1 please mention a brief description on why and then take the details to this thread.

现在我们需要等待 72 小时，才能公布投票结果。

这是 Apache 的一项政策，目的是让任何人都能参与投票，无论其身处何地，也不受当前所处周末或公共假期的影响。

如果至少收到 3 张 +1 票，且 +1 的票数多于 -1，则投票通过。

在 72 小时的最短等待期结束后，且我们已满足至少获得 3 张 +1 票、且 +1 多于 -1 的要求，就会向投票邮件线程发送一封最终回复，标题中带有 [RESULT] 前缀，并以汇总形式呈现投票结果。

E-Mail Topic:
[RESULT] [VOTE] Apache PLC4X Build-Tools Code-Generation {1.0.0} RC1

Message:
So, the vote passes with 3 +1 votes by PMC members and one +1 vote by a non PMC member.

投票通过后的发布

一旦投票结束，且结果赞成发布，就可以发布暂存的构件。这通过在 Apache SVN 中移动它们来完成。

   svn move -m "Release Apache PLC4X {1.0.0}" \
       https://dist.apache.org/repos/dist/dev/plc4x/build-tools/code-generation/{1.0.0}/rc1 \
       https://dist.apache.org/repos/dist/release/plc4x/build-tools/code-generation/{1.0.0}

这将使发布产物可用，并触发将其复制到镜像站点。

这也是你应该在发送发布公告邮件之前至少等待 24 小时的原因。

清理较旧的发布版本

由于许多镜像站点在分发我们的发布产物，Apache 的策略是：当发布了新版本后，应从仓库中清理旧的发布版本。

清理方式如下：

svn delete https://dist.apache.org/repos/dist/release/plc4x/build-tools/code-generation/{1.8.0}/ -m"deleted old version of the build-tools"

在此之后，https://dist.apache.org/repos/dist/release/plc4x/build-tools/code-generation 应该只包含最新的发布目录。

发布 Maven 构件

最简单的部分大概就是发布 Maven 构件了。

为此，发布管理员登录位于 https://repository.apache.org/ 的 Nexus，选择暂存仓库并点击 Release 按钮。

这会将所有构件移入 Apache 发布仓库，并在此之后删除暂存仓库。

所有发布到 Apache 发布仓库的构件都会自动同步到 Maven 中央仓库。

将发布版本合并回 `release` 分支

`release 分支应始终指向最近发布的版本。这一步必须通过 git 完成

git checkout release
git merge releases/code-generation/{1.0.0}

当出现冲突时，使用 theirs 合并策略可能会有所帮助，即，

git merge -X theirs releases/code-generation/{1.0.0}

事后可能需要手动解决冲突。完成后，需要推送这些更改。

与 PLC4X 的正式版本发布不同，我们不会进行任何 GitHub Issues 版本更新、下载页面更新，也不会向 announce@apache.org] 发送面向全世界的通知邮件。

至此，一切就绪。恭喜！