贡献 Parquet-Java

如何为 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，或发送电子邮件到邮件列表（dev@parquet.apache.org）。

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 git@github.com: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 分支