贡献概览#

本地 git 约定#

如果您在本地跟踪 Arrow 源代码仓库，这里是一个使用 git 的检查清单

  • 在您 个人 fork 的 apache/arrow 上工作，并提交 pull requests 到“upstream”。

  • 保持您的 fork 的 main 分支 与 upstream/main 同步。

  • 在分支上开发，而不是您自己的“main”分支。

  • 您如何命名您的分支并不重要。有些人喜欢使用 GitHub issue 编号作为分支名称，另一些人则使用描述性名称。

  • 定期将您的分支与 upstream/main 同步，因为每天都有许多提交合并到 main。

  • 建议使用 git rebase 而不是 git merge。

  • 如果存在冲突，并且您的本地提交历史记录有多个提交，您可以通过将您的本地提交合并为单个提交来简化冲突解决过程。保留提交历史记录并不重要，因为当您的特性分支被合并到上游时，会自动进行 squash。

    如何合并本地提交？

    使用以下命令中止 rebase

    $ git rebase --abort

    之后，可以通过运行以下命令以交互方式合并本地提交

    $ git rebase --interactive ORIG_HEAD~n

    其中 n 是您的本地分支中的提交数。 squash 后，您可以再次尝试合并，这次冲突解决应该相对简单。

    在您更新了本地副本后，您可以推送到您的远程仓库。请注意，由于您的远程仓库仍然保存着旧的历史记录，因此您需要进行强制推送。大多数推送应该使用 --force-with-lease

    $ git push --force-with-lease origin branch

    如果远程仓库有本地不可用的提交（例如，如果同事进行了其他提交），则选项 --force-with-lease 将失败。通过使用 --force-with-lease 而不是 --force，您可以确保这些提交不会被覆盖，并且可以根据需要获取这些更改。

    将 rebase 设置为默认值

    如果在您的仓库的 .git/config 中设置了以下内容，则可以从 git pull 命令中省略 --rebase 选项，因为默认情况下会隐式执行 rebase。

    [pull]
      rebase = true

Pull request 和审查#

在贡献补丁时，请使用此列表作为 Apache Arrow 工作流程的检查清单

  • 将补丁作为 GitHub pull request 提交到 main 分支。

  • 为了使您的 pull request 与 GitHub issue 同步，请在您的 pull request 标题前加上 GitHub issue id（例如：GH-14866: [C++] Remove internal GroupBy implementation）。

  • 给 pull request 一个 清晰、简短的描述：当 pull request 被合并时，这将保留在扩展的提交消息中。

  • 确保您的代码 通过单元测试。您可以在每个 Arrow 组件各自的 README 文件中找到有关如何运行单元测试的说明。

核心开发人员和其他在您的更改影响的项目部分中拥有权益的人员将进行审查、请求更改，并最终表示他们的批准。为了使审查过程对每个人都顺利，请尝试

  • 如果可能，将您的工作分解为小的、单用途的补丁。

    合并具有大量不相交功能的大型更改要困难得多，特别是如果您是该项目的新手，维护人员更容易接受较小的更改。

  • 为您的代码添加新的单元测试。

  • 遵循您正在修改的项目部分的样式指南。

    一些语言（例如 C++ 和 Python）在持续集成中运行 lint 检查。对于所有语言，请参阅各自的开发人员文档和 README 以获取样式指南。

  • 尽量使代码库看起来好像只有一个作者，并模仿您看到的任何约定，无论它们是否经过官方记录或检查。

当测试通过并且 pull request 已获得相关方的批准时，committer 将合并 pull request。这是通过一个 命令行实用程序完成的，该实用程序会进行 squash merge。

有关 squash merge 的详细信息

pull request 通过 squash merge 合并，以便您的所有提交都将注册为 main 分支的单个提交；这简化了 GitHub issue 和提交之间的连接，使得 bisect 历史记录以识别引入更改的位置变得更加容易，并帮助我们能够将单个补丁 cherry-pick 到维护分支上。

您的 pull request 将在 GitHub 界面中显示为已“合并”。在该提交的提交消息中，合并工具会添加 pull request 描述、返回 pull request 的链接以及对贡献者和任何共同作者的署名。

实验性仓库#

Apache Arrow 在 rules for revolutionaries 的上下文中对开发实验性仓库有明确的策略。

此策略的主要动机是提供一种轻量级的机制来在 ASF 和 Apache Arrow 治理模型内进行实验性工作，并具有必要的创作自由。此策略允许 committers 在新的仓库上工作，因为它们提供了许多重要的工具来管理它（例如，github issues，“watch”，“github stars”来衡量整体兴趣）。

流程#

  • committer *可以* 通过在 Apache Arrow 中创建一个单独的 git 仓库（例如，通过 selfserve）并在邮件列表中宣布它及其目标以及指向新创建的仓库的链接来启动实验性工作。

  • committer *必须* 启动一个电子邮件线程，其唯一目的是向社区介绍有关仓库状态的更新。

  • 仓库 *不得* 有官方发布。

  • 以任何方式（无论是通过合并还是迁移）使实验性仓库正式化的任何决定 *必须* 在邮件列表中进行讨论和投票。

  • committer 负责管理仓库的问题、文档、CI，包括许可检查。

  • committer 决定何时存档仓库。

仓库管理#

  • 仓库 *必须* 位于 apache/ 下

  • 仓库的名称 *必须* 以 arrow-experimental- 为前缀

  • committer 对仓库拥有完整的权限（在 ASF 中可能范围内）

  • 推送/合并权限 *只能* 授予 Apache Arrow committers

开发流程#

  • 仓库必须遵循 ASF 关于第三方代码的要求。

  • committer 决定如何管理 issues、PR 等。

偏差#

  • 如果上述任何“必须”事项未能实现，并且提交者在收到请求后未采取纠正措施，PMC应该取得所有权并决定如何处理。

特定功能的指南#

社区不时会讨论他们希望支持的特定类型的功能和改进。本节概述了在这方面做出的决定。

字节序#

Arrow 格式允许设置字节序。由于小端架构的普及，大多数实现默认假设为小端。也已经做出了一些努力来支持大端平台。根据邮件列表讨论，新平台的要求是

  1. 一个健壮的（非不稳定的，在合理时间内返回结果的）持续集成设置。

  2. 用于性能关键代码部分的基准测试，以证明没有回归。

此外，对于大端支持，实现可以支持两个级别

  1. 原生字节序（所有 Arrow 通信都发生在相同字节序的进程中）。这包括辅助功能，例如读取和写入各种文件格式，例如 Parquet。

  2. 跨字节序支持（实现将在适当的时候为 IPC 和 Flight 消息进行字节重排）。

关于支持哪个级别的决定基于维护者对复杂性和技术风险的偏好。通常，所有实现都应该对原生字节序支持持开放态度（前提是满足 CI 和性能要求）。跨字节序支持是各个维护者需要考虑的问题。

当前致力于跨字节序支持的实现是

  1. C++

不打算实现跨字节序支持的实现

  1. Java

对于其他库，在提交 PR 之前，应该在邮件列表上进行讨论以达成共识。