版本管理指南#

此页面详细介绍了执行发布的步骤。它既可以用作学习 Apache Arrow 发布流程的指南,也可以作为发布管理员执行发布时的全面清单。担任发布管理员的人员必须至少具有提交者状态才能执行以下任务。如果发布管理员是提交者但不是 PMC 成员,则需要将某些任务委派给 PMC 成员,这些任务将在下面进行相应标记。

原则#

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

准备发布#

在创建源代码版本之前,版本管理员必须确保所有已解决的 GitHub 问题都设置了适当的里程碑,以便正确生成变更日志。

请注意,没有相应 GitHub 问题的拉取请求不会被 cherry-pick 脚本检测到,必须由版本管理员手动 cherry-pick 到维护分支上。例如 MINOR 和 Dependabot 拉取请求。因此,建议通过为发布维护分支创建后合并到默认分支的任何拉取请求创建问题,来避免手动 cherry-pick 的需要。

要求

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

  • 安装发布所需的 Archery 实用程序。

  • 除 CC 或 CXX 外,您不得定义任何 arrow-cpp 或 parquet-cpp 环境变量,如果您希望使用默认值以外的其他内容进行构建(例如 clang)。

  • 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 环境变量以自动创建验证发布的拉取请求。

  • 安装 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 到维护分支

创建候选版本#

以下是创建候选版本所需的 fabbricazione步骤。

对于主要版本上的初始候选版本,我们将从主版本创建维护分支。

后续候选版本将通过 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 分支到主分支创建一个拉取请求

  • 将拉取请求命名为“WIP: Dummy PR to check maint-X.Y.Z status”

  • 对拉取请求进行评论以触发相关的 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 [email protected]. 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 报告系统。

  4. 推送发布标签。

  5. 上传源代码。

  6. 上传二进制文件。

  7. 更新网站。

  8. 更新 GitHub 发布说明。

  9. 更新 Homebrew 软件包。

  10. 更新 MSYS2 软件包。

  11. 上传 RubyGems。

  12. 上传 JavaScript 软件包。

  13. 上传 C# 软件包。

  14. 更新 conda 配方。

  15. 将 wheel/sdist 上传到 PyPI。

  16. 更新 R 软件包。

  17. 更新 vcpkg 端口。

  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 报告系统。

将 Arrow 的相关发布数据添加到Apache 报告器

推送发布标签并创建 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 [email protected]:kou/arrow-site.git ../
git clone [email protected]:<YOUR_GITHUB_ID>/arrow-site.git ../
cd ../arrow-site
## Add [email protected]:apache/arrow-site.git as "apache" remote.
git remote add apache [email protected]: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` 分支。您需要在 Web 浏览器上从 `release-note-X.Y.Z` 分支发起一个拉取请求。

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

提交者必须运行以下脚本。“更新网站”脚本的拉取请求合并后,必须执行此操作。

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

向 Homebrew 发起一个拉取请求。

## 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 [email protected]:kou/homebrew-core.git
git remote add <YOUR_GITHUB_ID> [email protected]:<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` 分支。您需要在 Web 浏览器上从 `apache-arrow-X.Y.Z` 分支创建一个标题为 `apache-arrow, apache-arrow-glib: X.Y.Z` 的拉取请求。

更新 MSYS2 软件包。

向 MSYS2 发起一个拉取请求。

## 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 [email protected]:kou/MINGW-packages.git ../
git clone [email protected]:<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` 分支。您需要在 Web 浏览器上从 `arrow-X.Y.Z` 分支创建一个标题为 `arrow: Update to X.Y.Z` 的拉取请求。

更新 RubyGems。

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

如果您在 https://rubygems.org.cn/ 上拥有一个帐户,则需要加入我们 gems 的所有者。

现有所有者可以通过以下命令行将新帐户添加到其所有者中:

# 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
将 wheel/sdist 上传到 PyPI。

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

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

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

要在 CRAN 上发布 R 软件包,我们需要先执行几个步骤,以确保 CRAN 可以使用 Windows 和 macOS 的二进制文件。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,CRAN 有一个用于上传包的 Web 表单。发布过程需要 R 包维护者(目前是 Neal Richardson)的电子邮件确认。

更新 vcpkg 端口

向 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 [email protected]:kou/vcpkg.git ../
git clone [email protected]:<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 分支。您需要在 Web 浏览器上使用 [arrow] 更新到 X.Y.Z 标题从 arrow-X.Y.Z 分支创建一个拉取请求。

更新 Conan 端口

向 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 [email protected]:kou/conan-center-index.git ../
git clone [email protected]:<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 分支。您需要在 Web 浏览器上从 arrow-X.Y.Z 分支创建一个拉取请求。

更新版本
# 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 [email protected]:kou/arrow-site.git ../
git clone [email protected]:<YOUR_GITHUB_ID>/arrow-site.git ../
cd ../arrow-site
## Add [email protected]:apache/arrow-site.git as "apache" remote.
git remote add apache [email protected]: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 分支。您需要创建一个拉取请求,并使用 asf-site 分支作为其基础。

更新 Apache Arrow Cookbook 中的版本

请遵循 Apache Arrow Cookbook 仓库中的文档

宣布新版本

撰写发布公告(请参阅示例)并发送至 announce@apache.orgdev@arrow.apache.org

发送至 announce@apache.org 的公告必须使用您的 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 成员完成。