发布经理指南

本文档描述了发布 Apache Ozone 的流程。该流程尚未脚本化，文档仍在编写中。

前置条件

安装所需软件包

发布过程中需要以下软件包：

JDK 8
用于构建的 Maven。
用于发布发布产物和 GPG 密钥的 Subversion。
用于管理 GPG 密钥的 GnuPG。
用于管理 protocol buffer 兼容性的 Protolock。

note

从 Ozone 2.0.0 开始，我们提供了用于故障注入工具和 Ozone Snapshot 功能的可选本地库。建议在 Linux 上构建，以便用户能够使用这些功能。

Mac
Rocky Linux
Ubuntu Linux

使用 Homebrew 安装前置依赖。

brew install svn git pinentry-mac cmake gcc coreutils gpatch

sudo ln -s /usr/local/bin/gsha256sum /usr/local/bin/sha256sum
sudo ln -s /usr/local/bin/gsha512sum /usr/local/bin/sha512sum

# use GNU patch as patch
PATH="$HOMEBREW_PREFIX/opt/gpatch/libexec/gnubin:$PATH"

确保使用 GNU tar。在 Mac 上，系统自带的 tar 会在归档文件中附加额外的元数据，这些元数据在其他平台上解压时会显示为多余的文件。GNU tar 可以通过 Homebrew 等方式安装：

在 Mac 上安装 GNU tar

brew install gnu-tar
# to use it as "tar", not "gtar", add the "gnubin" directory to your PATH
export PATH="$HOMEBREW_PREFIX/opt/gnu-tar/libexec/gnubin:$PATH"

在 Mac 上安装 Subversion 时，你可能会遇到 sqlite3 兼容性问题。请使用以下方法解决：

在 Mac 上安装 Subversion

# fix svn sqlite3 incompatibility
brew update
brew remove sqlite svn
brew reinstall sqlite svn --build-from-source

发布您的 GPG 密钥

如果您还没有用于签名构建产物的 GPG 密钥，请先创建一个。有关创建密钥的帮助，请参阅 ASF 新提交者指南。发布管理者的 GPG 密钥应当随版本一同发布。如果该密钥尚不存在，请将其追加到 Subversion 中存储的 KEYS 文件末尾。

PMC 成员可以将自己的密钥直接追加到版本 KEYS 文件中：

发布密钥（PMC）

svn co https://dist.apache.org/repos/dist/release/ozone
cd ozone
export CODESIGNINGKEY=<your_gpg_key_id>
gpg --list-sigs $CODESIGNINGKEY >> KEYS
gpg --armor --export $CODESIGNINGKEY >> KEYS
svn commit -m "ozone: adding key of <your_name> to the KEYS"

如果你是 Committer 而不是 PMC 成员，你可以先将自己的密钥添加到 dev KEYS 文件中，再由一位 PMC 成员将其移动到最终位置：

发布密钥（Committer）

# Use the latest KEYS as the base
svn rm https://dist.apache.org/repos/dist/dev/ozone/KEYS
svn cp https://dist.apache.org/repos/dist/release/ozone/KEYS https://dist.apache.org/repos/dist/dev/ozone/KEYS

svn co https://dist.apache.org/repos/dist/dev/ozone
cd ozone
export CODESIGNINGKEY=<your_gpg_key_id>
gpg --list-sigs $CODESIGNINGKEY >> KEYS
gpg --armor --export $CODESIGNINGKEY >> KEYS
svn commit -m "ozone: adding key of <your_name> to the KEYS"

Move Key（PMC）

svn mv -m "ozone: adding key of <name> to the KEYS" https://dist.apache.org/repos/dist/dev/ozone/KEYS https://dist.apache.org/repos/dist/release/ozone/KEYS

配置 Maven 凭据

将你的 Apache 凭据添加到本地 Maven 配置文件 ~/.m2/settings.xml。

settings.xml

<settings>
  <servers>
    <server>
      <id>apache.staging.https</id>
      <username>your_apache_id</username>
      <password>your_apache_password</password>
    </server>
  </servers>
</settings>

投票前准备

为本次发布创建父级 Jira

这可以让社区了解发布的进度。本指南中提到的任务，例如将修复 cherry-pick 到发布分支、更新 Ozone 网站、发布 Docker 镜像等，都可以作为子任务添加到该父级 Jira 中。

执行类似此查询的 Jira 查询（请将其中的版本号改为你要处理的发布版本），以找出所有目标版本（Target Version）字段设为本次发布的未解决 Jira。请注意，有些人会错误地将修复版本（Fix Version）当作目标版本使用，因此该查询中也包含了 Fix Version。请按以下步骤对这些 Jira 执行批量更新：

在右上角点击 Tools，然后在 Bulk Change 下选择 all ... issues。
点击顶部的复选框以选中所有问题，然后点击 Next。
选择 Edit Issues，然后点击 Next。
选择 Change Fix Version/s，并在下拉菜单中选择 Clear field。

note

这会修正那些错误地为本次发布设置了修复版本的未解决问题。
选择 Change Target Version/s，并输入你正在处理的发布之后的下一个版本。
选择 Change Comment，添加一条评论，说明你已移除其发布版本字段；如果该问题正在积极处理中、接近完成，并希望包含在本次发布中，请在指定日期前（通常为一周后）与你联系。

note

尽管该操作名为 Change Comment，但它实际上是向 Jira 添加一条新评论，不会影响已有评论。
持续点击下一步，直到操作开始。Jira 开始批量更新后，可能需要一段时间才能完成。

在继续执行下一步（更新 master 分支并切出发布分支）之前，请等待 Jira 评论中指定的日期过去，并确保阻塞性问题已得到解决。

构建并将 `proto.lock` 文件提交到 master 分支

Protolock 文件用于检查各版本之间 Protocol Buffers 的向后兼容性。Ozone 构建过程会将 Protocol Buffers 与这些锁文件进行比对，如果检测到不兼容则构建失败。这些文件应在每次发布时更新，并且需要安装 protolock。

在 Ozone 仓库根目录下保存并运行以下脚本。

update_protolocks.sh

#!/usr/bin/env sh

for lock in $(find . -name proto.lock); do
  lockdir="$(dirname "$lock")"
  protoroot="$lockdir"/../proto
  if protolock status --lockdir="$lockdir" --protoroot="$protoroot"; then
    protolock commit --lockdir="$lockdir" --protoroot="$protoroot"
  else
    echo "protolock update failed for $protoroot"
  fi
done

提交对 proto.lock 文件所做的更改。

git commit -m "Update proto.lock for Ozone $VERSION"

:::warning
请仔细检查，确保提交的文件只有 proto.lock，并且这些文件的改动与本次发布新增的功能相匹配。
:::

:::tip
Ozone 目前使用以下 protolock 文件：

hadoop-hdds/interface-client/src/main/resources/proto.lock：控制客户端与 Datanode 通信的协议。
hadoop-hdds/interface-admin/src/main/resources/proto.lock：控制客户端与 SCM 通信的协议。
hadoop-hdds/interface-server/src/main/resources/proto.lock：控制 SCM 之间相互通信的协议。
hadoop-ozone/interface-client/src/main/resources/proto.lock：控制所有涉及 Ozone Manager 的协议。
hadoop-ozone/csi/src/main/resources/proto.lock：控制 Ozone CSI 服务器的协议。
:::

提交一个拉取请求，将更新后的 proto.lock 改动添加到 Ozone 的 master 分支。该提交将成为你的发布分支的父提交。

更新主分支上的 Ozone 版本

通过拉取请求更新 master 分支上的 Ozone SNAPSHOT 版本和国家公园标签。快照版本应设置为当前版本的下一个次版本号。例如，如果你要发布 2.0.0，那么 master 分支的当前版本为 2.0.0-SNAPSHOT，此时应将其提升为 2.1.0-SNAPSHOT。作为此更改的一部分，你需要为 Ozone 的下一个版本选择一个美国国家公园，并将其设置在项目顶层 pom 的 <ozone.release> 中。示例请参见此拉取请求。

更新项目版本

mvn versions:set -DgenerateBackupPoms=false -DnewVersion=2.1.0-SNAPSHOT
mvn versions:set-property -DgenerateBackupPoms=false -Dproperty=ozone.version -DnewVersion=2.1.0-SNAPSHOT
mvn versions:set-property -DgenerateBackupPoms=false -Dproperty=ozone.release -DnewVersion="Joshua Tree"

:::note

在 master 分支上，proto.lock 文件更新与 SNAPSHOT 版本号提升之间合入一些提交是没有问题的，但这些提交不会包含在本次发布中，除非在创建发布分支后手动进行 cherry-pick。

创建发布分支

当上述更新 protolock 文件和 Ozone SNAPSHOT 版本的两个 Pull Request 都已合并后，你就可以在 apache/ozone GitHub 仓库中创建发布分支了。

:::important

发布分支的父提交应当是proto.lock 文件更新合并时的那次提交。

:::

分支名使用发布版本的主版本号和次版本号来命名，这样补丁版本也可以基于该分支进行发布。例如，如果要发布 2.0.0，就创建一个名为 ozone-2.0 的分支。在发布完成之前，所有与发布相关的改动都会提交到这个分支。

搭建本地环境

后续的命令中会引用以下变量：

export VERSION=2.0.0 # Set to the version of ozone being released.
export RELEASE_DIR=~/ozone-release/ # ozone-release needs to be created
export CODESIGNINGKEY=<your_gpg_key_id>
export RC=0 # Set to the number of the current release candidate, starting at 0.
# Optional, if not specified, gpg will prompt during the build for passphrase.
export MAVEN_GPG_PASSPHRASE=<PASSPHRASE> # Maven passes this environment variable to gpg for passphrase.

最好在本地克隆一个全新的 Ozone 仓库来进行发布工作，而将现有的仓库保持原样，用于你可能同时进行的开发任务。克隆完成后，请确保 apache/ozone 上游仓库对应的 git remote 名称为 origin，这是正确填充发布构建元数据的必要条件。

运行以下命令以确保你的仓库是干净的：

git reset --hard
git clean -dfx

假定以下所有命令都在本仓库内、且已检出发布分支的情况下执行。

更新发布分支上的 Ozone 版本

使用下列命令或 IDE，将 $VERSION-SNAPSHOT 替换为 $VERSION。

更新并提交版本变更

mvn versions:set -DgenerateBackupPoms=false -DnewVersion=$VERSION
mvn versions:set-property -DgenerateBackupPoms=false -Dproperty=ozone.version -DnewVersion=$VERSION

git commit -am "Update Ozone version to $VERSION"

如果你使用 IDE 或其他命令来更新版本，请在继续之前确认没有遗留 pom.xml.versionsBackup 文件。

为发布候选版本打标签

该操作会使用与 git 邮件地址相匹配的 GPG 密钥对标签进行签名。请确保 git config user.email 提供的邮箱与 gpg --list-secret-keys 中显示的、你要使用的密钥的邮箱一致。

git tag -s "ozone-$VERSION-RC$RC"

::: tip

如果命令失败，你可能需要执行以下额外步骤：

告诉 git 使用该程序进行签名，并指定用于签名的密钥：

git config --global gpg.program "$(which gpg)"
git config --global user.signingKey $CODESIGNINGKEY

然后执行以下依赖于平台的步骤。

Mac
Linux

告诉 GPG 使用该程序来提示输入口令：

echo "pinentry-program $(which pinentry-mac)" > ~/.gnupg/gpg-agent.conf

重新加载 gpg-agent：
```
gpgconf --kill gpg-agent
```

执行基本检查

运行 rat 检查，确保没有失败项。
```
./hadoop-ozone/dev-support/checks/rat.sh
```
清除仓库中所有 rat 检查产生的输出
```
git reset --hard
git clean -dfx
```
在开始发布构建之前，确认仓库处于干净状态。
```
git status --short
find . -name 'pom.xml.versionsBackup'
```

两条命令均不应产生任何输出。

构建项目

构建项目以获取依赖项。

mvn clean install -DskipTests -Psign,dist,src -Dtar -Dgpg.keyname="$CODESIGNINGKEY" -Drocks_tools_native

构建 RPM 和 DEB 包（Ozone 2.1.0 及以上版本）

从 Ozone 2.1.0 起，发布分支还可以为部分发行版构建原生 Linux 软件包（HDDS-13439）。

构建 RPM 软件包

mvn clean package -Prpm -DskipTests=true -Drpm.release=<number> [-Drpm.needArch=<bool>]

此处，rpm.release 用于设置 RPM 的 release 字段（例如，某个 Ozone 版本的首次构建设为 1），而可选标志 rpm.needArch 则控制构建时是否自动检测目标架构（详见 HDDS-14052）。

生成的 RPM 将位于以下路径：

hadoop-ozone/dist/target/rpm/ozone/RPMS/

文件名形如：

ozone-<ozone_version>-1.noarch.rpm

构建 Debian 软件包
```
mvn clean package -Pdeb
```

.deb 文件将生成在以下目录：

hadoop-ozone/dist/target/

文件名模式由 Maven 构建派生：

ozone_<ozone_version>-<linux_distro>_<deb_arch>.deb

这些软件包是为方便 Linux 用户而提供的。官方发布产物仍然是后面几节中介绍的源码与二进制 tar 包以及 Maven 构件。

创建并上传 Maven 构件

执行最终构建并上传发布产物。

mvn deploy -DdeployAtEnd=true -DskipTests -Psign,dist,src -Dtar -Dgpg.keyname="$CODESIGNINGKEY" -Drocks_tools_native

访问 https://repository.apache.org/#stagingRepositories，并关闭（close）新创建的 orgapacheozone 仓库。

计算校验和并签名构件

发布产物构建完成后，将它们复制到发布目录。
```
cp hadoop-ozone/dist/target/ozone-*.tar.gz "$RELEASE_DIR"/
```

运行以下命令，为所有发布产物生成校验和文件：

cd "$RELEASE_DIR"
for i in $(ls -1 *.tar.gz); do gpg -u "$CODESIGNINGKEY" --armor --output "$i.asc" --detach-sig "$i"; done

for i in $(ls -1 *.tar.gz); do sha512sum "$i" > "$i.sha512"; done

for i in $(ls -1 *.tar.gz); do gpg --print-mds "$i" > "$i.mds"; done

现在每个 .tar.gz 文件都应该有对应的 .mds 文件、.asc 文件和 .sha512 文件。

检查制品

在上传制品之前，请对它们运行一些基本测试，这与其他开发者在对发布投赞成票之前所进行的测试类似。

解压源码压缩包的内容，验证其中不包含任何 pom.xml.versionsBackup 文件，并在构建之前重命名你的 ~/.m2 目录，以便在空的 Maven 缓存下完成构建。
```
find ozone-$VERSION-src -name 'pom.xml.versionsBackup'
```

该命令不应产生任何输出。
2. 检查输出的二进制 tar 包大小，与上一个发行版本相比是否出现明显增长。

体积显著增加可能意味着存在依赖问题，需要加以修复。
Apache svn 仓库对发行构件有大小限制。如果因为 tar 包过大导致上传 svn 失败，我们需要联系 INFRA 增加仓库配额。详情参见此处。

验证签名
- 从 https://dist.apache.org/repos/dist/release/ozone/KEYS 下载 KEYS 文件
- 导入其内容（其中应当包含你的公钥 GPG key）：
```
gpg --import KEYS
```
- 验证每个 .tar.gz 构件：
```
for x in *.tar.gz; do gpg --verify $x.asc $x; done
```
校验校验和
- 对每个构件，验证 shasum 命令给出的校验和与 .sha512 文件的内容以及其 .mds 文件中的 SHA512 行是否一致。
```
shasum -a 512 *.tar.gz
```
确认发行 tar 包中包含文档
- 解压发行包并在浏览器中打开 docs/index.html，检查文档网站是否显示正常。
在解压后的发行包中运行 bin/ozone version。该命令的输出应包含：
- 正确的发行版本
- 正确的国家公园标签
- 非 snapshot 版本的 Ratis。
- 指向 apache/ozone GitHub 仓库的链接（而不是你的 fork）。
- 该发行版本所基于的最后一个提交的 git 哈希值。
在解压后的发行包中进入 compose/upgrade 目录并运行 test.sh，执行升级兼容性验收测试。

注意

提交到 master 分支的 test.sh 文件出于节省构建时间的考虑，只会针对上一个已发布的 Ozone 版本检查升级兼容性。若要检查与所有历史版本的兼容性，应在运行前取消 test.sh 文件中所有 run_test 行的注释。这个测试矩阵可能需要很长时间才能运行完毕，因此最好在 GitHub Actions 上运行而不是在本地运行。

将构件上传到开发暂存区

将 $RELEASE_DIR 中的所有内容上传到开发暂存区。

svn checkout https://dist.apache.org/repos/dist/dev/ozone
cd ozone
mkdir "$VERSION-rc$RC"
cp -v "$RELEASE_DIR"/* "$VERSION-rc$RC"/
svn add "$VERSION-rc$RC"
svn commit -m "Ozone $VERSION RC$RC"

将候选发行版本标签推送到 GitHub

git push origin "ozone-$VERSION-RC$RC"

投票

向 dev@ozone.apache.org 邮件列表发送投票邮件。邮件中需包含以下内容：

GitHub 上发布候选标签（release candidate tag）的链接
Jira 查询链接，用于展示本次发布所有已解决的问题。可以类似这个。
源码和二进制 tar 包的位置。该链接类似 https://dist.apache.org/repos/dist/dev/ozone/2.0.0-rc0
Maven 构件的暂存（staging）位置。该链接类似 https://repository.apache.org/content/repositories/orgapacheozone-1029/
用于签名构件的公钥链接。该公钥始终包含在 KEYS 文件中，你可以直接链接到它：https://dist.apache.org/repos/dist/release/ozone/KEYS
用于签名构件的密钥指纹。

如果构件没有发现问题，让投票进行 7 天。请查阅 ASF 全站发布投票政策，并注意具约束力（binding）投票的要求——只有 PMC 成员才能投出具约束力的票。有时回复者不会指明自己的投票是否具约束力。如有疑问，请查阅 ASF 提交者索引。所属组包含 ozone-pmc 的用户可以投出具约束力的票。

投票结束后，发送一封邮件汇总结果（具约束力的 +1、非具约束力的 +1、-1、0），如果投票通过，则说明发布构件将会被发布。

如果发布候选存在问题

如果发现构件存在问题：

从 Subversion 中删除被放弃的发布候选。

svn delete -m "Abandon Ozone $VERSION RC$RC" https://dist.apache.org/repos/dist/dev/ozone/"$VERSION-rc$RC"

在 https://repository.apache.org/#stagingRepositories 处丢弃暂存仓库。
对发布分支应用修复。
从为发布候选打标签这一步开始重复上述步骤，其中所有步骤中的 $RC 变量都加 1。

投票之后

发布构件

如果你是 PMC 成员，将构件在 Subversion 中移动到最终位置；否则，请请求 PMC 执行同样的操作：

svn mv -m "Release ozone-$VERSION-rc$RC as ozone-$VERSION" \
  https://dist.apache.org/repos/dist/dev/ozone/"$VERSION-rc$RC" \
  https://dist.apache.org/repos/dist/release/ozone/"$VERSION"

要将构件发布到 Maven Central，请登录 https://repository.apache.org/#stagingRepositories，选择你的 staging 仓库并执行 release。

写一首俳句

从 Ozone Roadmap 页面检查标签（它是一座国家公园）。找一张使用 CC 许可的图片，用 Future 字体为这张图片写一首俳句。

更新 Ozone 网站

编写发布说明，并将其连同你的俳句图片一起添加到 Ozone 网站。这里有一个展示如何操作的示例拉取请求：示例。请注意，目标分支是 master。请按照 Keep a Changelog 格式编写发布说明。特别要注意，发布说明必须便于人阅读，而不能只是简单的提交日志差异。
从发布 tar 包中解压 docs 文件夹，并将其内容添加到网站。这方面的示例拉取请求是：示例。请注意，目标分支是 asf-site，并且 docs/current 符号链接已更新为指向最新发布版本的目录。
检出 master 分支后，在仓库根目录运行 hugo serve，在本地测试网站。检查指向新版本的链接是否正常工作。在指向 asf-site 分支的 PR 被合并之前，文档链接将无法工作。

添加最终 Git 标签并推送

git checkout "ozone-$VERSION-RC$RC"
git tag -s "ozone-$VERSION" -m "Ozone $VERSION release"
git push origin "ozone-$VERSION"

更新 GitHub Releases 页面

使用发布信息更新 GitHub Releases 页面。示例可参见 1.4.1 发布页面。

发布该版本的 Docker 镜像

Ozone Docker 镜像仅用于测试目的，不适用于生产环境。更新 Docker 镜像的拉取请求示例见此处。拉取请求的目标分支应为 latest。拉取请求合并后，可以通过更新与 Docker 镜像标签对应的分支，将其发布到 Docker Hub。

通过将 ozone-latest 分支快进合并到与 latest 分支一致，发布带有 latest 标签的镜像。
```
git checkout ozone-latest
git pull
git merge --ff-only origin/latest
git push origin ozone-latest
```
通过从 latest 分支创建一个名称类似 ozone-1.5.0（请替换为当前版本号）的新分支，并将其推送到 GitHub，来发布带有特定版本标签的镜像。
```
git checkout ozone-latest
git checkout -b "ozone-$VERSION"
git push origin "ozone-$VERSION"
```

更新 Helm Chart（可选）

Docker 镜像发布之后，我们也可以更新 Helm Chart。可以参考这个拉取请求作为示例。

更新 Master 分支上的验收测试

更新升级测试和客户端交叉兼容性验收测试，使其针对新版本进行检查。可参考这个拉取请求作为示例。