发布管理指南#

本页面提供有关执行发布的步骤的详细信息。它既可以用作学习 Apache Arrow 发布过程的指南，也可以用作发布经理执行发布时的综合检查清单。担任发布经理的人员必须至少具有提交者身份才能执行以下任务。如果发布经理是提交者但不是 PMC 的成员，则某些任务需要委派给 PMC 成员，这些任务在下面进行了标记。

原则#

Apache Arrow 发布遵循 Apache 软件基金会发布策略中定义的准则。

为发布做准备#

在创建源发布之前，发布经理必须确保任何已解决的 GitHub 问题都已设置适当的里程碑，以便正确生成变更日志。

请注意，没有相应 GitHub 问题的 pull request 将无法被 cherry-pick 脚本检测到，并且必须由发布经理手动 cherry-pick 到维护分支上。 示例包括 MINOR 和 Dependabot pull request。 因此，建议为合并到默认分支后的任何 pull request 创建 issue，以避免需要手动 cherry-pick，默认分支是指在创建发布维护分支之后合并的。

要求

发布的某些步骤需要成为提交者或 PMC 成员。

  • 安装 Archery 实用程序，这是发布所必需的。

  • 您不得定义任何 arrow-cpp 或 parquet-cpp 环境变量，除非您想使用 GCC 以外的其他工具（例如 clang）进行构建，CC 或 CXX 除外。

  • Apache Web of Trust 中的一个 GPG 密钥，用于签署工件。 这将需要由其他 Apache 提交者/PMC 成员交叉签名。 如果您有多个 GPG 密钥，则必须通过添加以下内容在 ~/.gnupg/gpg.conf 中设置正确的 GPG 密钥 ID

default-key ${YOUR_GPG_KEY_ID}

  • GPG 密钥需要添加到此 SVN 仓库 和 这个仓库。

  • 安装 cpp 和 c_glib 的构建要求。

  • 设置 CROSSBOW_GITHUB_TOKEN 环境变量以自动创建验证发布 Pull Request。

  • 安装 en_US.UTF-8 区域设置。您可以通过 locale -a 确认可用的区域设置。

  • 将 Python 3 安装为 python

  • 从 dev/release/.env.example 创建 dev/release/.env。 有关如何设置每个变量，请参阅 dev/release/.env.example 中的注释。

  • 如定义的那样设置 Crossbow。

  • 安装 Docker 和 Docker Compose。

在创建发布候选版本之前#

确保删除本地标签，设置 gpg-agent 并正确分配 GitHub 问题。

# Delete the local tag for RC1 or later
git tag -d apache-arrow-<version>

# Setup gpg agent for signing artifacts
source dev/release/setup-gpg-agent.sh

# Curate the release
# The end of the generated report shows any GitHub issues with the wrong
# version number assigned.
archery release curate <version>

确保在 GitHub 上为后续版本创建主要版本里程碑。 这将自动被我们的合并脚本用作维护分支创建时关闭的问题的新版本。

补丁发布#

一旦发现主要的中断问题，我们通常会创建补丁发布。 被确定为主要中断问题的问题可能是安全修复、特定构建的损坏包等等。

任何开发人员都可以通过向 Arrow 开发邮件列表 发送电子邮件，说明为什么需要发布新版本，来要求生成补丁发布。 如果达成共识并且有发布经理愿意付出努力来创建发布，则可以创建补丁发布。

提交者可以使用 backport-candidate 标签标记应包含在下一个补丁版本中的问题。 作者或提交者有责任将标签添加到问题，以帮助发布经理识别应该反向移植的问题。

如果某个特定问题被确定为创建补丁版本的原因，则发布经理应验证至少此问题是否已正确标记并包含在补丁版本中。

请务必仔细检查以下清单

  1. 创建里程碑

  2. 创建维护分支

  3. 包含请求作为需要新的补丁版本的问题

  4. 向带有 backport-candidate 标签的问题添加新的里程碑

  5. 将问题 cherry-pick 到维护分支中

创建发布候选版本#

以下是创建发布候选版本所需的各个步骤。

对于主要版本上的初始发布候选版本，我们将从 main 创建一个维护分支。

后续发布候选版本将通过 cherry-pick 特定提交来更新维护分支。

对于次要版本或补丁版本的初始发布候选版本，我们将从之前的相应版本创建维护分支。 例如，对于 15.0.1 补丁，我们将从 maint-15.0.0 创建 maint-15.0.1 分支，对于 maint-15.0.2，我们将从 maint-15.0.1 创建。 创建维护分支后，我们将通过 cherry-pick 特定提交来更新已创建的维护分支。

我们在发布候选版本之间实施了功能冻结策略。 这意味着通常我们应该仅在发布候选版本之间添加错误修复。 在极少数情况下，如果社区达成共识，则可以在发布候选版本之间添加关键功能。

创建或更新相应的维护分支#

# Execute the following from an up to date main branch.
# This will create a branch locally called maint-X.Y.Z.
# X.Y.Z corresponds with the Major, Minor and Patch version number
# of the release respectively. As an example 9.0.0
archery release cherry-pick X.Y.Z --execute
# Push the maintenance branch to the remote repository
git push -u apache maint-X.Y.Z

# First run in dry-mode to see which commits will be cherry-picked.
# If there are commits that we don't want to get applied, ensure the
# milestone on GitHub is set to the following release.
archery release cherry-pick X.Y.Z --continue
# Update the maintenance branch with the previous commits
archery release cherry-pick X.Y.Z --continue --execute
# Push the updated maintenance branch to the remote repository
git push -u apache maint-X.Y.Z

可选：在创建发布候选版本之前进行测试#

一些发布经理更喜欢在创建第一个发布候选版本之前执行测试，以避免在给定的版本中需要创建多个发布候选版本。

在创建发布候选版本之前进行测试

  • 从最新的 maint-X.Y.Z 分支创建到 main 的 pull request

  • 将 pull request 标题命名为 “WIP: Dummy PR to check maint-X.Y.Z status”

  • 评论 pull request 以触发相关的 Crossbow 作业

    • @github-actions crossbow submit --group verify-rc-source

    • @github-actions crossbow submit --group packaging

从更新后的维护分支创建发布候选分支#

# Start from the updated maintenance branch.
git checkout maint-X.Y.Z

# The following script will create a branch for the Release Candidate,
# place the necessary commits updating the version number and then create a git tag
# on OSX use gnu-sed with homebrew: brew install gnu-sed (and export to $PATH)
#
# <rc-number> starts at 0 and increments every time the Release Candidate is created
# so for the first RC this would be: dev/release/01-prepare.sh 4.0.0 5.0.0 0
dev/release/01-prepare.sh <version> <next-version> <rc-number>

# Push the release candidate tag
git push -u apache apache-arrow-<version>-rc<rc-number>
# Push the release candidate branch in order to trigger verification jobs later
git push -u apache release-<version>-rc<rc-number>

构建源和二进制文件并提交它们#

# Build the source release tarball and create Pull Request with verification tasks
#
# NOTE: This must be run by a PMC member
# NOTE: You need to have GitHub CLI installed to run this script.
dev/release/02-source.sh <version> <rc-number>

# Submit binary tasks using crossbow, the command will output the crossbow build id
dev/release/03-binary-submit.sh <version> <rc-number>

# Wait for the crossbow jobs to finish
archery crossbow status <crossbow-build-id>

# Download the produced binaries
# This will download packages to a directory called packages/release-<version>-rc<rc-number>
dev/release/04-binary-download.sh <version> <rc-number>

# Sign and upload the binaries
#
# NOTE: This must be run by a PMC member
#
# On macOS the only way I could get this to work was running "echo "UPDATESTARTUPTTY" | gpg-connect-agent" before running this comment
# otherwise I got errors referencing "ioctl" errors.
dev/release/05-binary-upload.sh <version> <rc-number>

# Sign and upload MATLAB artifacts to the GitHub Releases area.
#
# NOTE: This must be run by a PMC member
# NOTE: You need to have GitHub CLI installed to run this script.
dev/release/06-matlab-upload.sh <version> <rc-number>

# Start verifications for binaries and wheels
dev/release/07-binary-verify.sh <version> <rc-number>

验证发布#

# Once the automatic verification has passed start the vote thread
# on dev@arrow.apache.org. To regenerate the email template use
SOURCE_DEFAULT=0 SOURCE_VOTE=1 dev/release/02-source.sh <version> <rc-number>

有关详细信息，请参阅 发布验证过程。

投票和批准#

在 dev@arrow.apache.org 上启动投票线程，并提供验证发布完整性的说明。 批准需要 PMC 成员的 3 个 +1 净票数。 发布不能被否决。

发布后任务#

在发布投票之后，我们必须执行许多任务来更新源代码构件、二进制构建和 Arrow 网站。

请务必仔细检查以下清单

  1. 更新 GitHub 上已发布里程碑的日期并将其设置为“已关闭”

  2. 将发布分支上的更改合并到维护分支，以便进行补丁发布

  3. 将新版本添加到 Apache Reporter 系统

  4. 推送发布标签

  5. 上传源代码

  6. 上传二进制文件

  7. 更新网站

  8. 更新 GitHub 版本说明

  9. 更新 Homebrew 包

  10. 更新 MSYS2 包

  11. 上传 RubyGems

  12. 上传 JavaScript 包

  13. 上传 C# 包

  14. 更新 conda 配方

  15. 上传 wheels/sdist 到 pypi

  16. 更新 R 包

  17. 更新 vcpkg port

  18. 更新 Conan 配方

  19. 更新版本号

  20. 更新文档

  21. 更新 Apache Arrow Cookbook 中的版本

  22. 发布新版本

  23. 发布版本相关的博客文章

  24. 在 Twitter 上发布版本

  25. 删除旧的构件

将发布分支上的更改合并到维护分支，以便进行补丁发布

将 release-X.Y.Z-rcN 合并到 maint-X.Y.Z

# git checkout maint-10.0.0
git checkout maint-X.Y.Z
# git merge release-10.0.0-rc0
git merge release-X.Y.Z-rcN
# git push -u apache maint-10.0.0
git push -u apache maint-X.Y.Z
将新版本添加到 Apache Reporter 系统

将相关的 Arrow 版本数据添加到 Apache reporter。

推送发布标签并创建 GitHub 版本

一个提交者必须将发布标签推送到 GitHub

# dev/release/post-01-tag.sh 0.1.0 0
dev/release/post-01-tag.sh <version> <rc>
上传源代码发布构件到 Subversion

一个 PMC 成员必须将源代码发布构件提交到 Subversion

# dev/release/post-02-upload.sh 0.1.0 0
dev/release/post-02-upload.sh <version> <rc>
上传二进制发布构件到 Artifactory

一个提交者必须将二进制发布构件上传到 Artifactory 并创建 GitHub 版本

# dev/release/post-03-binary.sh 0.1.0 0
dev/release/post-03-binary.sh <version> <rc number>
更新网站

为新版本添加版本说明到我们的网站并更新最新的版本信息

## Prepare your fork of https://github.com/apache/arrow-site .
## You need to do this only once.
# git clone git@github.com:kou/arrow-site.git ../
git clone git@github.com:<YOUR_GITHUB_ID>/arrow-site.git ../
cd ../arrow-site
## Add git@github.com:apache/arrow-site.git as "apache" remote.
git remote add apache git@github.com:apache/arrow-site.git
cd -

## Generate a release note for the new version, update the
## latest release information automatically.
# dev/release/post-04-website.sh 9.0.0 10.0.0
dev/release/post-04-website.sh OLD_X.OLD_Y.OLD_Z X.Y.Z

此脚本将 release-note-X.Y.Z 分支推送到你的 apache/arrow-site fork。 你需要在你的 Web 浏览器上从 release-note-X.Y.Z 分支打开一个 pull request。

更新 apache/arrow GitHub 版本中的版本说明

一个提交者必须运行以下脚本。 这必须在合并来自更新网站脚本的 Pull Request 后执行

# dev/release/post-05-update-gh-release-notes.sh 17.0.0
dev/release/post-05-update-gh-release-notes.sh <version>
更新 Homebrew 包

打开一个到 Homebrew 的 pull request

## You need to run this on macOS or Linux that Homebrew is installed.

## Fork https://github.com/Homebrew/homebrew-core on GitHub.
## You need to do this only once.
##
## Prepare your fork of https://github.com/Homebrew/homebrew-core .
## You need to do this only once.
cd "$(brew --repository homebrew/core)"
# git remote add kou git@github.com:kou/homebrew-core.git
git remote add <YOUR_GITHUB_ID> git@github.com:<YOUR_GITHUB_ID>/homebrew-core.git
cd -

# dev/release/post-14-homebrew.sh 10.0.0 kou
dev/release/post-14-homebrew.sh X.Y.Z <YOUR_GITHUB_ID>

此脚本将 apache-arrow-X.Y.Z 分支推送到你的 Homebrew/homebrew-core fork。 你需要在你的 Web 浏览器上从 apache-arrow-X.Y.Z 分支创建一个标题为 apache-arrow, apache-arrow-glib: X.Y.Z 的 pull request。

更新 MSYS2 包

打开一个到 MSYS2 的 pull request

## Fork https://github.com/msys2/MINGW-packages on GitHub.
## You need to do this only once.
##
## Prepare your fork of https://github.com/msys2/MINGW-packages .
## You need to do this only once.
# git clone git@github.com:kou/MINGW-packages.git ../
git clone git@github.com:<YOUR_GITHUB_ID>/MINGW-packages.git ../
cd ../MINGW-packages
## Add https://github.com/msys2/MINGW-packages.git as "upstream" remote.
git remote add upstream https://github.com/msys2/MINGW-packages.git
cd -

# dev/release/post-13-msys2.sh 10.0.0 ../MINGW-packages
dev/release/post-13-msys2.sh X.Y.Z <YOUR_MINGW_PACKAGES_FORK>

此脚本将 arrow-X.Y.Z 分支推送到你的 msys2/MINGW-packages fork。 你需要在你的 Web 浏览器上从 arrow-X.Y.Z 分支创建一个标题为 arrow: Update to X.Y.Z 的 pull request。

更新 RubyGems

你需要在 https://rubygems.org.cn/ 上拥有一个帐户才能发布 Ruby 包。

如果你在 https://rubygems.org.cn/ 上拥有一个帐户，你需要加入我们的 gem 的所有者。

现有的所有者可以通过以下命令行将一个新帐户添加到他们的所有者中

# dev/release/account-ruby.sh raulcd
dev/release/account-ruby.sh NEW_ACCOUNT

在 Homebrew 包和 MSYS2 包更新后更新 RubyGems

# dev/release/post-06-ruby.sh 10.0.0
dev/release/post-06-ruby.sh X.Y.Z
更新 JavaScript 包

为了将二进制构建发布到 npm，你需要通过询问当前在 https://npmjs.net.cn/package/apache-arrow 包中列出的合作者来获得对项目的访问权限。

包上传需要安装 npm 和 yarn，并在你的帐户上配置 2FA。

当你拥有访问权限时，你可以通过运行以下脚本将版本发布到 npm

# Login to npmjs.com (You need to do this only for the first time)
npm login --registry=https://registry.yarnpkg.com/

# dev/release/post-07-js.sh 10.0.0
dev/release/post-07-js.sh X.Y.Z
更新 C# 包

你需要在 https://nuget.net.cn/ 上拥有一个帐户。 你需要加入 Apache.Arrow 包的所有者。 现有的所有者可以在 https://nuget.net.cn/packages/Apache.Arrow/Manage 邀请你成为所有者。

你需要在 https://nuget.net.cn/account/apikeys 创建一个 API 密钥才能从命令行上传。

从 https://dotnet.microsoft.com/download 安装最新的 .NET Core SDK。

# NUGET_API_KEY=YOUR_NUGET_API_KEY dev/release/post-08-csharp.sh 10.0.0
NUGET_API_KEY=<your NuGet API key> dev/release/post-08-csharp.sh X.Y.Z
上传 wheels/sdist 到 PyPI

pip 二进制包（称为“wheels”）和源代码包（称为“sdist”）是使用我们在发布候选版本创建过程中使用的 crossbow 工具构建的，然后上传到 PyPI（Python 包索引）下的 pyarrow 包。

我们使用 twine 工具将 wheels 上传到 PyPI

# dev/release/post-11-python.sh 10.0.0
dev/release/post-11-python.sh <version>
更新 R 包

为了在 CRAN 上发布 R 包，我们需要首先执行一些步骤，以确保 Windows 和 macOS 的二进制文件可用于 CRAN。 Jeroen Ooms <jeroenooms@gmail.com> 维护着几个项目，这些项目为 macOS 和 Windows 的 R 包构建 C++ 依赖项。 我们在我们的 CI 中测试这些相同构建脚本的副本，在发布时，我们需要发送我们所做的任何更改并更新上游的版本/哈希。

当发布候选版本时，使用 rc 创建到每个仓库的草稿拉取请求，更新版本和 SHA，以及来自 apache/arrow 中相应文件的任何 cmake 构建更改。 Jeroen 可以在发布投票通过之前合并这些 PR，构建二进制文件，并将它们发布在正确的位置，以便我们可以进行提交前检查（见下文）。在发布候选版本投票通过后，更新这些 PR 以指向官方（非 rc）URL，并将它们标记为准备好进行审查。Jeroen 将合并、构建二进制文件，并将它们发布在正确的位置。有关在提交到 CRAN 之前必须进行的拉取请求的精确列表，请参阅打包清单。

一旦满足了这些二进制先决条件，我们就可以提交到 CRAN。鉴于该过程的复杂性，最好由项目中的 R 开发人员在提交之前验证软件包是否符合 CRAN 的标准。我们的 CI 系统为 CRAN 检查的内容提供了一些覆盖，但我们应该进行一些最终测试，以确认发布二进制文件可以工作，并且一切都在与 CRAN 相同的基础设施上运行，这很难/不可能用 Docker 完全模拟。 有关检查的精确列表，请参阅打包清单。

一旦所有检查都通过，我们就提交到 CRAN，它有一个用于上传软件包的 Web 表单。发布过程需要 R 软件包维护者（目前是 Neal Richardson）的电子邮件确认。

更新 vcpkg port

打开一个拉取请求到 vcpkg

## Fork https://github.com/microsoft/vcpkg on GitHub.
## You need to do this only once.
##
## Prepare your fork of https://github.com/microsoft/vcpkg .
## You need to do this only once.
# git clone git@github.com:kou/vcpkg.git ../
git clone git@github.com:<YOUR_GITHUB_ID>/vcpkg.git ../
cd ../vcpkg
./bootstrap-vcpkg.sh
## Add https://github.com/microsoft/vcpkg.git as "upstream" remote.
git remote add upstream https://github.com/microsoft/vcpkg.git
cd -

# dev/release/post-15-vcpkg.sh 10.0.0 ../vcpkg
dev/release/post-15-vcpkg.sh X.Y.Z <YOUR_VCPKG_FORK>

这个脚本将一个 arrow-X.Y.Z 分支推送到你的 microsoft/vcpkg fork。 你需要在你的 Web 浏览器上从 arrow-X.Y.Z 分支创建一个标题为 [arrow] Update to X.Y.Z 的拉取请求。

更新 Conan port

打开一个拉取请求到 Conan

## Fork https://github.com/conan-io/conan-center-index on GitHub.
## You need to do this only once.
##
## Prepare your fork of https://github.com/conan-io/conan-center-index .
## You need to do this only once.
# git clone git@github.com:kou/conan-center-index.git ../
git clone git@github.com:<YOUR_GITHUB_ID>/conan-center-index.git ../
cd ../conan-center-index
## Add https://github.com/conan-io/conan-center-index.git as "upstream" remote.
git remote add upstream https://github.com/conan-io/conan-center-index.git
cd -

# dev/release/post-16-conan.sh 10.0.1 ../conan-center-index
dev/release/post-16-conan.sh X.Y.Z <YOUR_CONAN_CENTER_INDEX_FORK>

这个脚本将一个 arrow-X.Y.Z 分支推送到你的 conan-io/conan-center-index fork。 你需要在你的 Web 浏览器上从 arrow-X.Y.Z 分支创建一个拉取请求。

Bump versions
# You can run the script with BUMP_TAG=0 and BUMP_PUSH=0
# this will avoid default pushing to main and pushing the tag
# but you will require to push manually after reviewing the commits.
# dev/release/post-12-bump-versions.sh 10.0.0 11.0.0
dev/release/post-12-bump-versions.sh X.Y.Z NEXT_X.NEXT_Y.NEXT_Z
更新文档

文档是在发布过程中生成的。 我们只需要上传生成的文档

## Prepare your fork of https://github.com/apache/arrow-site .
## You need to do this only once.
# git clone git@github.com:kou/arrow-site.git ../
git clone git@github.com:<YOUR_GITHUB_ID>/arrow-site.git ../
cd ../arrow-site
## Add git@github.com:apache/arrow-site.git as "apache" remote.
git remote add apache git@github.com:apache/arrow-site.git
cd -

# dev/release/post-10-docs.sh 10.0.0 9.0.0
dev/release/post-10-docs.sh X.Y.Z PREVIOUS_X.PREVIOUS_Y.PREVIOUS_Z

这个脚本将一个 release-docs-X.Y.Z 分支推送到你的 arrow-site fork。 你需要创建一个 Pull Request，并使用 asf-site 分支作为它的基础。

更新 Apache Arrow Cookbook 中的版本

按照 Apache Arrow Cookbook 仓库中的文档进行操作

发布新版本

撰写版本发布公告 (参见 示例) 并发送到 announce@apache.org 和 dev@arrow.apache.org.

必须从你的 apache.org 电子邮件地址发送到 announce@apache.org 的公告才能被接受。

发布发行说明博客文章

博客文章过程不是自动的。 我们通常采取的大致步骤是

  • 克隆 apache/arrow-site。

  • 从 main 创建一个新的分支，用于我们正在创建的博客文章拉取请求。

  • 在 _posts 子文件夹中复制最近的博客文章条目，并更新文件名和 YAML 元数据。

    • 将文件名和 YAML 元数据中的日期设置为发布候选版本投票线程关闭的日期（以 GMT 为准）。

  • 仅对于次要版本，删除有关社区更新（新提交者、PMC 成员等）的任何部分。

  • 根据需要更新其余文本

  • 创建拉取请求

  • 在拉取请求中，ping 每个部分中的贡献者，请求帮助填写每个部分的详细信息。

在社交媒体上宣布发布

在社交媒体上发布有关发布的帖子，并链接到博客文章。 该项目有两个官方帐户

PMC 成员有权访问或可以请求访问以在这些帐户下发布。

删除旧构件

删除 https://dist.apache.org/repos/dist/dev/arrow/ 上的 RC 构件和 https://dist.apache.org/repos/dist/release/arrow 上的旧版本构件，以遵循 ASF 政策

dev/release/post-09-remove-old-artifacts.sh

注意：此步骤必须由 PMC 成员完成。