KnowForge/Apache Gluten 简体中文
开发者概览

如何发布

qianmoQqianmoQ· 更新于 2026-10-02· 阅读 26 分钟· 0 次阅读
登录后可跨设备保存划线和私人笔记登录

创建发布源码与二进制文件

本文档提供了为 Apache Gluten 项目（使用 Velox 后端）创建发布所需源码与二进制文件的标准流程。

前置条件

  1. x86-64
  2. Linux
  3. Docker

发布前检查

请在打发布候选标签之前完成以下所有检查。每一项都对应此前在发布投票过程中曾被提出的问题；跳过这些检查通常会导致多消耗一个发布候选版本。

标记本次发布所构建依赖的 Velox 版本

ep/build-velox/src/get-velox.sh 固定了原生构建所使用的 Velox fork 与分支：

VELOX_REPO=https://github.com/IBM/velox.git
VELOX_BRANCH=branch-1.7-dft

构建会通过 git ls-remote 将该分支解析为其当时所指向的任意提交。该分支会不断向前移动，因此日后重新构建同一个 Gluten 标签时，将会纳入不同的 Velox 代码。

请针对本次发布所依据的提交，在 IBM/velox 仓库中创建一个标签，只要该 Gluten 发布版本仍然存在，就能保证原生部分始终可复现。

设置发布版本并移除遗留的 -SNAPSHOT 字符串

bash dev/release/bump-version.sh 1.7.0

bump-version.sh 会在仓库根目录下的 POM 文件上执行 versions:set，涉及 tools/gluten-it、tools/qualification-tool 和 gluten-flink。它不会修改其他地方硬编码的版本号，例如 dev/info.sh 以及 gluten-flink/docs/ 下的文档。请检查是否有遗漏之处：

git grep -nIE '[0-9]+\.[0-9]+\.[0-9]+-SNAPSHOT'

Gluten 自身的版本号在结果中不得出现为 -SNAPSHOT。对第三方快照版本的引用，例如 velox4j 和 spark-sql-perf，应当保留。

此前某个 RC 因为源码分发包中仍带有 -SNAPSHOT 版本（包括早前发布遗留下来的过期版本）而被投了 +0 票。所有此类版本都要清理干净，而不仅仅是当前版本。

版本号的更新必须在创建发布候选标签之前提交，因为源码归档包是根据该标签生成的。仍然带有 -SNAPSHOT 的标签无法发布，必须重新切出一个新的候选版本。

更新 LICENSE-binary 与 NOTICE-binary

Bundle JAR 静态链接了第三方代码，而 package-release.sh 会在每个二进制 tarball 中以 LICENSE 和 NOTICE 的形式附带 LICENSE-binary 和 NOTICE-binary。每当新增或启用某个被打包的组件时，都必须在此处记录其版权声明和许可证。

此前某个 RC 因为在二进制包中启用了 Hudi 和 Paimon，却没有将它们添加到 NOTICE-binary 中，而被投了 -1 票。

检查许可证头

# Requires the `regex` Python package: pip install regex
python3 dev/check.py header main

评审者还会对源码归档运行 Apache RAT](https://creadur.apache.org/rat/)。请注意，RAT 会标记 .ipynb 笔记本文件，而这类文件无法添加注释头；惯例是将许可证文本放置在笔记本的第一个 markdown 单元格中。

创建发布版本的步骤

可以按照以下步骤创建标准发布分发包。

拉取并运行 dev docker 镜像

拉取并下载构建环境的 docker 镜像。该 docker 镜像由定期运行的 GitHub Actions 作业周期性构建并上传至 DockerHub。

docker pull apache/gluten:vcpkg-centos-7-gcc13
docker run -it apache/gluten:vcpkg-centos-7-gcc13 bash

克隆仓库

在上一步创建的 docker 容器中，执行以下命令，克隆 Gluten 仓库并检出你想要构建的特定 git 标签。

本指南以 v1.7.0-rc0 作为示例 git 标签。

git clone --branch v1.7.0-rc0 https://github.com/apache/gluten.git /workspace

构建

为所有受支持的 Spark 版本构建该项目。

cd /workspace
bash dev/release/build-release.sh

或者，可以让 CI 来完成。.github/workflows/build_release.yml 会在相同的容器中运行同样的 dev/release/build-release.sh，并且在推送符合 v* 的标签时自动触发——包括发布候选标签，例如 v1.7.0-rc0。请从该次工作流运行中下载 build-velox-backend-release-packages 制品，而不是在本地构建。

将 bundle JAR 收集到发布目录

package-release.sh 从 $GLUTEN_HOME/release/ 中读取，而该目录并不会由构建过程创建。请自行创建它，并将每个受支持 Spark 版本对应的一个 bundle JAR 放入其中，这些 JAR 可以来自本地构建，也可以来自上述工作流制品。

cd /workspace
mkdir -p release
cp -R package/target/* release/

该目录最终应包含这四个 JAR 文件，与 package-release.sh 所期望的 Spark 和 Scala 组合相匹配：

gluten-velox-bundle-spark3.4_2.12-linux_amd64-1.7.0.jar
gluten-velox-bundle-spark3.5_2.12-linux_amd64-1.7.0.jar
gluten-velox-bundle-spark4.0_2.13-linux_amd64-1.7.0.jar
gluten-velox-bundle-spark4.1_2.13-linux_amd64-1.7.0.jar

缺失或命名错误的 JAR 会使 package-release.sh 报错，提示找不到对应的 Spark 版本。

打包发布源码与二进制文件

按照本步骤操作，即可创建符合 ASF 项目发布流程通用命名规范的发布分发包。

注意：运行此脚本时需指定当前标签（tag）。

cd /workspace
bash dev/release/package-release.sh v1.7.0-rc0

检查创建的发布分发包

确认所有必需的源码和二进制文件都已在发布目录 $GLUTEN_HOME/release/ 中成功生成。

ls -1 release/*.tar.gz
release/apache-gluten-1.7.0-src.tar.gz
release/apache-gluten-1.7.0-bin-spark-3.4.tar.gz
release/apache-gluten-1.7.0-bin-spark-3.5.tar.gz
release/apache-gluten-1.7.0-bin-spark-4.0.tar.gz
release/apache-gluten-1.7.0-bin-spark-4.1.tar.gz

每个二进制 tar 包都包含一个带版本号的顶层目录，其中存放着捆绑的 JAR，以及涵盖其中静态链接的第三方代码的 LICENSE 和 NOTICE。

tar -tzf release/apache-gluten-1.7.0-bin-spark-3.5.tar.gz
apache-gluten-1.7.0-bin-spark-3.5/
apache-gluten-1.7.0-bin-spark-3.5/LICENSE
apache-gluten-1.7.0-bin-spark-3.5/NOTICE
apache-gluten-1.7.0-bin-spark-3.5/gluten-velox-bundle-spark3.5_2.12-linux_amd64-1.7.0.jar

发布 Release

本节依照 Apache 发布指南，说明发布 Apache Gluten 的步骤。Apache 伞下所有项目都必须遵守 Apache 发布策略。本指南旨在帮助你理解该策略，并顺利完成 Apache 上的项目发布流程。

发布流程

请按顺序依次完成以下步骤。这些步骤的前提是：上一节生成的 tar 包已存放于 $GLUTEN_HOME/release/ 之下。

在全文中，请将 <asf-id> 替换为你的 ASF id，将 <asf-id>@apache.org 替换为你的 ASF 邮箱，将 1.7.0 / 1.7.0-rc0 替换为本次发布的版本号。

请注意，产物的文件名不带 rc 后缀——package-release.sh 会将其去除。发布候选版本仅由其暂存所在的 SVN 目录来标识，即 1.7.0-rc0。这正是投票通过后无需重新签名的原因：同样的文件只需移动到 release/gluten/1.7.0/ 即可。

1. 确认标签并记录 commit id

标签必须已经存在于 GitHub 上，并附有草案版发布说明，因为源码 tar 包就是基于它构建的。请记录下 commit id，用于投票邮件：

git rev-parse v1.7.0-rc0

2. 构件预检

构件一旦签名并上传，任何修改都需要重新生成新的发布候选版本，因此请先检查其结构：

cd $GLUTEN_HOME/release/

# Each binary tarball: a versioned top-level directory holding the JAR, LICENSE and NOTICE.
for f in apache-gluten-1.7.0-bin-spark-*.tar.gz; do echo "== $f"; tar -tzf "$f"; done

# Source tarball: check the top-level directory name and that dot directories are gone.
tar -tzf apache-gluten-1.7.0-src.tar.gz | head -20
tar -tzf apache-gluten-1.7.0-src.tar.gz | grep -E '/\.(git|github|idea)' || echo "  clean"

3. 准备签名密钥

如果你已有密钥，请直接复用；新建密钥意味着每位审阅者都必须重新导入 KEYS。要将密钥迁移到另一台机器，请用 gpg --export-secret-keys --armor <KEYID> 导出密钥，通过安全通道传输，然后在目标机器上 gpg --import。

仅在原有密钥无法恢复时才创建新密钥：

gpg --full-generate-key

选择 RSA and RSA、4096 位，并设置为永不过期。UID 中请使用你的 ASF 邮箱：评审人员会据此核验该签名密钥对应某位提交者。设置一个足够长的口令，并将其记录在密码管理器中——一把你无法解锁的密钥，与一把你已不再拥有的密钥同样等于丢失。

gpg --list-keys --keyid-format SHORT <asf-id>@apache.org
gpg --keyserver keyserver.ubuntu.com --send-key <asf-id>@apache.org

# Confirm the key can sign.
echo test > /tmp/t \
  && gpg --local-user <asf-id>@apache.org --armor --detach-sig /tmp/t \
  && gpg --verify /tmp/t.asc /tmp/t

在附带精简版 GnuPG 的发行版上，gpg --full-generate-key 会因 can't connect to the gpg-agent 而失败。在 Amazon Linux 2023 上，请安装完整软件包：

sudo dnf swap gnupg2-minimal gnupg2 -y

4. 备份密钥

gpg --export-secret-keys --armor <asf-id>@apache.org > ~/gluten-signing-key.asc

将该文件移动到离线存储介质，并从本机删除。连同你密码管理器中的口令，二者共同确保下一次发布可以复用该密钥。

5. 在发起投票之前，将密钥追加到 KEYS 文件中

svn co --depth files --username <asf-id> \
  https://dist.apache.org/repos/dist/release/gluten/ ~/svn-gluten-release
cd ~/svn-gluten-release
(gpg --list-sigs <asf-id>@apache.org && gpg --export --armor <asf-id>@apache.org) >> KEYS
svn ci --username <asf-id> -m "Add GPG key for <asf-id>@apache.org"

SVN 密码是你的 ASF LDAP 密码，见 https://id.apache.org，而不是 GPG 口令。

只追加，绝不覆盖。旧的密钥块必须保留，因为它们仍用于校验先前发布的构件。

KEYS 存放在 release 目录中，而不是 dev，因此它由 https://downloads.apache.org/gluten/KEYS 提供服务。在开始投票前请确认它已出现在该处，并在投票邮件中引用该 URL：此前有一次投票不得不在讨论中途更正，因为它把评审者引向了一个 dist.apache.org/repos/dist/dev/ 链接。同步需要几分钟。

6. 对构件签名

cd $GLUTEN_HOME/release/
for i in *.tar.gz; do
  echo "$i"
  gpg --local-user <asf-id>@apache.org --armor --output "$i.asc" --detach-sig "$i"
done

gpg-agent 会缓存口令，因此只需输入一次，而不必逐个文件输入。

7. 生成校验和

for i in *.tar.gz; do echo "$i"; sha512sum "$i" > "$i.sha512"; done

8. 验证你自己的构件

for i in *.tar.gz; do gpg --verify "$i.asc" "$i"; done
for i in *.tar.gz; do sha512sum --check "$i.sha512"; done
ls -1 | wc -l

每个压缩包应包含三个文件：tarball、其 .asc 以及其 .sha512。

9. 上传至开发暂存区

--depth immediates 可以避免下载所有历史版本，考虑到每个 tarball 约 100 MB，这一点很重要：

svn co --depth immediates --username <asf-id> \
  https://dist.apache.org/repos/dist/dev/gluten/ ~/svn-gluten-dev
cd ~/svn-gluten-dev
mkdir 1.7.0-rc0
cp $GLUTEN_HOME/release/*.tar.gz* 1.7.0-rc0/
svn add 1.7.0-rc0
svn ci --username <asf-id> -m "Add Apache Gluten 1.7.0-rc0 release artifacts"

项目目录 https://dist.apache.org/repos/dist/dev/gluten/ 只需创建一次，即首次发布时创建即可。

10. 确认上传

访问 https://dist.apache.org/repos/dist/dev/gluten/1.7.0-rc0/，并确认源码压缩包以及每个受支持 Spark 版本对应的二进制压缩包，且它们各自都带有 .asc 和 .sha512：

apache-gluten-1.7.0-src.tar.gz{,.asc,.sha512}
apache-gluten-1.7.0-bin-spark-3.4.tar.gz{,.asc,.sha512}
apache-gluten-1.7.0-bin-spark-3.5.tar.gz{,.asc,.sha512}
apache-gluten-1.7.0-bin-spark-4.0.tar.gz{,.asc,.sha512}
apache-gluten-1.7.0-bin-spark-4.1.tar.gz{,.asc,.sha512}

验证发布候选版本

本节面向所有对候选版本进行投票的人员，包括在发起投票前的发布经理。

  1. 检查下载链接是否有效。
  2. 检查校验和与 GPG 签名是否有效。
  3. 检查发布构件的名称是否规范，且与当前发布版本一致。
  4. 检查 LICENSE 和 NOTICE 文件是否正确。
  5. 检查所有需要的文件中是否都包含许可证头部。
  6. 源码归档中不得捆绑任何未授权的编译归档文件。

如何验证签名

请按照以下步骤验证签名。

# download KEYS
$ curl https://downloads.apache.org/gluten/KEYS > KEYS

# import KEYS and trust the key, please replace the email address with the one you want to trust.
$ gpg --import KEYS
$ gpg --edit-key xxx@apache.org
gpg> trust
gpg> 5
gpg> y
gpg> quit

# enter the directory where the release artifacts are located
$ cd /path/to/release/artifacts

# verify the signature
$ for i in *.tar.gz; do echo $i; gpg --verify $i.asc $i ; done

# if you see 'Good signature' in the output, it means the signature is valid.

如何校验和验证

请按照以下步骤验证校验和。

# verify the checksums
$ for i in *.tar.gz; do echo $i; sha512sum --check  $i.sha512; done

投票与发布

11. 发起发布投票

向 dev@gluten.apache.org 发送投票请求邮件，需要至少 3 位 PMC 成员投 +1 票。投票期至少保持 72 小时，或直到收集到足够的票数。Gluten 是一个顶级项目（Top-Level Project），因此这是唯一需要的投票；没有 general@incubator.apache.org 环节。

如果候选版本使用了与此前发布不同的密钥签名，请在邮件中说明这一点，否则缓存了旧密钥的审查者会遇到验证失败。

投票邮件模板

[VOTE] Release Apache Gluten 1.7.0 (RC0)

Hello everyone,

This is a call for a vote to release Apache Gluten version 1.7.0 (RC0).

The release candidates:
https://dist.apache.org/repos/dist/dev/gluten/1.7.0-rc0/

Release notes:
https://github.com/apache/gluten/releases/tag/v1.7.0-rc0

Git commit id for the release:
https://github.com/apache/gluten/commit/{commit-id}

Keys to verify the Release Candidate:
https://downloads.apache.org/gluten/KEYS

The vote will be open for at least 72 hours or until the necessary number
of votes are reached.

Please vote accordingly:

[ ] +1 approve
[ ] +0 no opinion
[ ] -1 disapprove (please provide reason)

Checklist for reference:

[ ] Download links are valid
[ ] Checksums and PGP signatures are valid
[ ] Source code distributions have correct names, matching the current release
[ ] LICENSE and NOTICE files are correct
[ ] All files have license headers if necessary
[ ] No unlicensed compiled archives are bundled in the source archive
[ ] Other (please specify):

To compile from the source, please refer to:
https://github.com/apache/gluten/tree/v1.7.0-rc0#build-from-source

Thanks,
{YOUR NAME}

当候选版本使用新密钥签名时，在 KEYS 链接下方添加以下这一行：

Note: this release is signed with a new GPG key. Please re-import KEYS
before verifying the signatures.

构建引用固定到候选版本的标签，而非 main，这样说明就与正在投票的代码保持一致。

12. 公布投票结果

向 dev@gluten.apache.org 发送一封 [RESULT][VOTE] 邮件，总结具有约束力和不具有约束力的投票，并附上投票讨论串的链接。

如果投票未通过，请处理发现的问题、为下一个候选版本打标签，并从第 6 步开始，在一个新的 1.7.0-rc1 暂存目录中重复该流程。签名密钥及其 KEYS 条目可以继续沿用。

13. 公布结果并发布版本

公告邮件模板

[ANNOUNCE] Apache Gluten 1.7.0 released

Hello everyone,

The Apache Gluten 1.7.0 has been released!

A Middle Layer for Offloading JVM-Based SQL Execution to Native Engines

Download Links: https://downloads.apache.org/gluten/

Release Notes: https://github.com/apache/gluten/releases/tag/v1.7.0

Website: https://gluten.apache.org/

Resources:
- Issue: https://github.com/apache/gluten/issues
- Mailing list: dev@gluten.apache.org

Thanks,
<YOUR NAME>

14. 将候选版本迁移至 Apache SVN 发布目录

投票通过后，将候选版本提升为正式发布：把构件从 Apache SVN 的 dev 目录移动到 release 目录。注意，目录名中的 rc 后缀会被移除；文件名和签名保持不变，因此无需重新签名。

svn mv --username <asf-id> \
  https://dist.apache.org/repos/dist/dev/gluten/1.7.0-rc0 \
  https://dist.apache.org/repos/dist/release/gluten/1.7.0 \
  -m "Transfer packages for Apache Gluten 1.7.0"

15. 收尾工作

  • 为该标签发布 GitHub release。
  • 更新网站上的下载页面。
  • 使用 bash dev/release/bump-version.sh <next-version>-SNAPSHOT 在发布分支上提升开发版本号。

评论

登录后参与评论

正在加载评论…