开发者指南

• 1: 子项目
• 2: 构建 Parquet
• 3: 贡献 Parquet-Java
• 4: 发布 Parquet-Java

1 - 子项目

parquet-format 项目包含正确读取 Parquet 文件所需的格式规范和元数据的 Thrift 定义。

parquet-java 项目是一个用于读写 Parquet 文件的 Java 库。它由多个子模块组成，这些子模块实现了读写嵌套的、面向列的数据流的核心组件，以及 Hadoop Input/Output Formats、Pig loaders 和其他用于与 Parquet 交互的基于 Java 的实用程序。

parquet-cpp 项目是一个用于读写 Parquet 文件的 C++ 库。它是 Apache Arrow C++ 实现的一部分，具有 Python、R、Ruby 和 C/GLib 的绑定。

parquet-rs 项目是一个用于读写 Parquet 文件的 Rust 库。

parquet-go 项目是一个用于读写 Parquet 文件的 Golang 库。它是 Apache Arrow Go 实现的一部分。

parquet-compatibility 项目（已弃用）包含兼容性测试，可用于验证不同语言的实现是否可以读写彼此的文件。截至 2022 年 1 月，兼容性测试仅存在到版本 1.2.0。

2 - 构建 Parquet

构建 Java 资源可以使用 mvn package 构建。当前稳定版本应该始终可以从 Maven Central 获得。

C++ thrift 资源可以通过 make 生成。

Thrift 也可以代码生成到任何其他 thrift 支持的语言。

3 - 贡献 Parquet-Java

Pull Requests

我们更愿意以 GitHub pull request 的形式接收贡献。请向 github.com/apache/parquet-java 仓库发送 pull request。如果您之前从旧位置 fork 了 Parquet，您需要添加一个 remote 或将您的 origin remote 更新为 https://github.com/apache/parquet-java.git。以下是一些让您的贡献被接受的技巧：

1. 如果可能，将您的工作分解成小的、单一目的的补丁。合并包含大量不相关功能的大型更改要困难得多。
2. 在 Parquet-Java issues 上创建一个 Issue。
3. 将补丁作为 GitHub pull request 提交到 master 分支。有关教程，请参阅关于 fork 仓库和发送 pull request 的 GitHub 指南。用 Issue 号 GH-2935 作为您的 pull request 名称前缀：（例如：https://github.com/apache/parquet-java/pull/2951）。
4. 确保您的代码通过单元测试。您可以在根目录中使用 mvn test 运行测试。
5. 为您的代码添加新的单元测试。
6. 所有 Pull Request 都会在 GitHub Actions 上自动测试。

如果您想报告 bug 但没有时间修复它，您仍然可以提交 issue，或发送电子邮件到邮件列表（[email protected]）。

Committers

合并 Pull Request

合并 pull request 需要是项目的 committer，并且需要非作者的 committer 批准该 PR。

Pull request 可以通过 GitHub UI 合并。默认情况下，项目仅启用了 squash and merge。

当 PR 解决现有 issue 时，确保在 Pull-Request 模板中引用该 issue Closes #1234。这样 issue 就会链接到 PR，当 PR 被合并时，GitHub 会自动关闭相关 issue。

语义版本控制

Parquet-Java 利用语义版本控制来确保库的 API 和实现演进时开发人员和用户的兼容性。Maven 插件 japicmp 强制执行此规则，当 API 在没有经过正确的弃用周期的情况下被更改时会失败。这适用于所有模块，不包括：parquet-benchmarks、parquet-cli、parquet-tools、parquet-format-structures、parquet-hadoop-bundle 和 parquet-pig-bundle。

所有计划弃用的接口、类和方法必须包括以下内容：

• 在适当的元素上添加 @Deprecated 注解
• @deprecated javadoc 注释，包括：移除版本、使用的适当替代方案
• 替换使用已弃用行为的现有代码路径

/**
 * @param c the current class
 * @return the corresponding logger
 * @deprecated will be removed in 2.0.0; use org.slf4j.LoggerFactory instead.
 */
@Deprecated
public static Log getLog(Class<?> c) {
    return new Log(c);
}

可以通过运行 mvn verify -Dmaven.test.skip=true japicmp:cmp 来检查 API 违规。

使用 Milestones 跟踪问题

当提交修复 bug 或您想针对某个版本的功能的 PR 时，请确保附加一个 milestone。这样其他 committer 可以跟踪某些版本，并查看仍在等待的内容。有关实际发布的信息，请查看发布页面。

维护分支

一旦 PR 合并到 master，可能需要将提交 backport 到维护分支（例如：1.14.x）。最简单的方法是在本地执行：

确保 remote 设置正确：

git remote add github-apache [email protected]:apache/parquet-java.git

现在您可以将 PR cherry-pick 到以前的分支：

git fetch --all
git checkout parquet-1.14.x
git reset --hard github-apache/parquet-1.14.x
git cherry-pick <hash-from-the-commit>
git push github-apache/parquet-1.14.x

网站

发布文档

要为 parquet-format 的新版本创建文档，请在 content/en/blog/parquet-format 下创建一个新的 .md 文件。请参阅该目录中的现有文件作为示例。

要为 parquet-java 的新版本创建文档，请在 content/en/blog/parquet-java 下创建一个新的 .md 文件。请参阅该目录中的现有文件作为示例。

网站开发和部署

Staging

要对网站的 staging 版本进行更改：

1. 向仓库的 staging 分支发送 PR
2. PR 合并后，部署工作流中的 Build and Deploy Parquet Site 作业将运行，用必要的文件填充此仓库的 asf-staging 分支。

不要直接编辑此仓库的 asf-staging 分支

Production

要对网站的 production 版本进行更改：

1. 向仓库的 production 分支发送 PR
2. PR 合并后，部署工作流中的 Build and Deploy Parquet Site 作业将运行，用必要的文件填充此仓库的 asf-site 分支。

不要直接编辑此仓库的 asf-site 分支

4 - 发布 Parquet-Java

设置

注：发布 parquet-format 的机制是相同的（例如设置密钥、分支、投票等）

您将需要：

• PGP 代码签名密钥，发布在 KEYS 中。
• 在 Nexus 中暂存工件的权限。

通过推送快照确保您有权限将 Parquet 工件部署到 Nexus：

mvn deploy

如果遇到问题，请阅读发布 Maven 工件文档。

发布流程

Parquet 使用 maven-release-plugin 来标记发布并将二进制工件推送到 Nexus 中的暂存区。maven 完成发布后，从标签构建官方源码 tarball。

0. 在开始发布流程之前

1. 验证发布已完成（里程碑上没有待处理的计划 Issues/PRs）
2. 构建并测试项目
3. 如果这是新的次要版本，则为发布创建一个新分支。例如，如果新的次要版本是 1.14.0，则创建一个新分支 parquet-1.14.x

1. 运行准备脚本

./dev/prepare-release.sh <version> <rc-number>

这将使用一致的标签名称运行 maven 的 release prepare。此步骤后，发布标签将存在于 git 仓库中。

如果此步骤失败，您可以通过运行以下命令回滚更改。

find ./ -type f -name '*.releaseBackup' -exec rm {} \;
find ./ -type f -name 'pom.xml' -exec git checkout {} \;

2. 运行 release:perform 暂存二进制文件

将发布标签的二进制工件上传到 Nexus：

mvn release:perform -DskipTests -Darguments=-DskipTests

3. 在 Nexus 中关闭暂存仓库

关闭暂存仓库使二进制文件在暂存区可用，但不发布它们。

1. 转到 Nexus。
2. 在左侧菜单中，选择"Staging Repositories"。
3. 选择 Parquet 仓库。
4. 在顶部，点击"Close"并按照说明操作。评论使用"Apache Parquet [Format] “。

4. 运行源码 tarball 脚本

dev/source-release.sh <version> <rc-number>

此脚本从发布标签的 SHA1 构建源码 tarball，签名它，并使用 SVN 上传必要的文件。

源码发布推送到 https://dist.apache.org/repos/dist/dev/parquet/

脚本的最后一条消息是发布提交的 SHA1 哈希和用于 VOTE 电子邮件的 URL。

5. 准备预发布

创建预发布将为用户提供 changelog，以查看他们是否需要验证某些功能。首先选择新创建的 rc（例如：apache-parquet-1.15.0-rc0）标签，然后选择上一个版本（例如 apache-parquet-1.14.1）。点击 Generate release notes 按钮自动生成说明。您可以通过删除不相关的更改（空格、仅测试更改）并对其进行排序来策划说明，使其更易于理解。确保选中 Set as pre-release 复选框，因为这是一个候选版本。

5. 向 [email protected] 发送 VOTE 电子邮件

这是您可以使用的模板。确保所有内容都适用于您的发布。

Subject: [VOTE] Release Apache Parquet <VERSION> RC<NUM>


Hi everyone,

I propose the following RC to be released as official Apache Parquet <VERSION> release.

The commit id is <SHA1>
* This corresponds to the tag: apache-parquet-<VERSION>-rc<NUM>
* https://github.com/apache/parquet-java/tree/<SHA1>

The release tarball, signature, and checksums are here:
* https://dist.apache.org/repos/dist/dev/parquet/<PATH>

You can find the KEYS file here:
* https://downloads.apache.org/parquet/KEYS

You can find the changelog here:
https://github.com/apache/parquet-java/releases/tag/apache-parquet-<VERSION>-rc<NUM>

Binary artifacts are staged in Nexus here:
* https://repository.apache.org/content/groups/staging/org/apache/parquet/

This release includes important changes that I should have summarized here, but I'm lazy.

Please download, verify, and test.

Please vote in the next 72 hours.

[ ] +1 Release this as Apache Parquet <VERSION>
[ ] +0
[ ] -1 Do not release this because...

投票通过后发布

候选版本通过投票后，需要将候选版本作为最终版本发布。

1. 标记最终版本并设置开发版本

./dev/finalize-release <release-version> <rc-num> <new-development-version-without-SNAPSHOT-suffix>

这将为 RC 标签添加最终发布标签，并在 pom 文件中设置新的开发版本。如果一切正常，将更改和新标签推送到 GitHub：git push --follow-tags

2. 在 Nexus 中发布二进制仓库

发布二进制仓库将二进制文件发布到公共区。

1. 转到 Nexus。
2. 在左侧菜单中，选择"Staging Repositories”。
3. 选择 Parquet 仓库。
4. 在顶部，点击 Release 并按照说明操作。评论使用"Apache Parquet [Format] “。

3. 在 SVN 中将发布工件复制到 releases

首先，在 SVN 中检出 candidates 和 releases 位置：

svn mv https://dist.apache.org/repos/dist/dev/parquet/apache-parquet-<VERSION>-rcN/ https://dist.apache.org/repos/dist/release/parquet/apache-parquet-<VERSION> -m "Parquet: Add release <VERSION>"

4. 更新 parquet.apache.org

更新 parquet.apache.org 上的下载页面。更新网站的说明在贡献页面上。

5. 将发布添加到 GitHub

向 GitHub 添加新版本。首先选择新标签（例如：apache-parquet-1.15.0），然后选择上一个版本（例如 apache-parquet-1.14.1）。您可以从通过投票的 RC 复制发布说明。

6. 向 [email protected] 和开发列表发送 ANNOUNCE 电子邮件

[ANNOUNCE] Apache Parquet release <VERSION>


I'm pleased to announce the release of Parquet <VERSION>!

Parquet is a general-purpose columnar file format for nested data. It uses
space-efficient encodings and a compressed and splittable structure for
processing frameworks like Hadoop.

Changes are listed at: https://github.com/apache/parquet-java/releases/tag/apache-parquet-<VERSION>

This release can be downloaded from: https://parquet.apache.org/downloads/

Java artifacts are available from Maven Central.

Thanks to everyone for contributing!

6. 用功能启用指导更新 parquet-format

其他功能启用的建议通常与 parquet-java 的发布相关（详细信息在 parquet-format 仓库中）。随着发布的进行，应更新规范以指示何时可以启用新功能的建议日期。

发布节奏

如果有足够的志愿者，Parquet 社区的目标是每季度发布一次（目标月份是 1 月、4 月、7 月和 10 月）。如果需要新的主要版本，将针对 10 月发布。