贡献概述#

本地 git 约定#

如果您在本地跟踪 Arrow 源代码仓库，这里有一份使用 git 的核对清单

  • 在您 **个人的 apache/arrow 复刻（fork）** 上工作，并向上游提交拉取请求（pull requests）。

  • 保持您复刻的 **main 分支** 与 upstream/main **同步**。

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

  • 分支的命名无关紧要。有些人喜欢使用 GitHub issue 编号作为分支名，另一些人则使用描述性的名称。

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

  • 推荐使用 git rebase 而不是 git merge。

  • 如果出现冲突，并且您的本地提交历史包含多个提交，您可以通过**将本地提交压缩（squash）成一个单独的提交**来简化冲突解决过程。保留提交历史并不那么重要，因为当您的功能分支合并到上游时，会自动进行压缩。

    如何压缩本地提交？

    使用以下命令中止 rebase：

    $ git rebase --abort

    之后，可以通过运行以下命令以交互方式压缩本地提交：

    $ git rebase --interactive ORIG_HEAD~n

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

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

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

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

    将 rebase 设置为默认

    如果您在仓库的 .git/config 文件中进行如下设置，那么在 git pull 命令中就可以省略 --rebase 选项，因为它已是默认设置。

    [pull]
      rebase = true

拉取请求和审查#

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

  • 以**针对 main 分支的 GitHub 拉取请求**的形式提交补丁。

  • 为了让您的拉取请求与 GitHub issue 同步，请在**拉取请求的标题前加上 GitHub issue ID**（例如：GH-14866: [C++] Remove internal GroupBy implementation）。

  • 为拉取请求提供一个**清晰、简洁的描述**：当拉取请求被合并时，这个描述将被保留在扩展的提交信息中。

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

核心开发者以及项目中与您的更改相关的其他利益相关者将进行审查、请求修改，并希望最终表示批准。为了让审查过程对每个人都顺利，请尝试：

  • 如果可能，将您的工作分解成小的、单一目的的补丁。

    合并一个包含许多不相关功能的大型更改要困难得多，特别是如果您是项目的新手，维护者更容易接受较小的更改。

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

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

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

  • 努力让代码库看起来像是由单一作者编写的，并模仿您看到的任何约定，无论它们是否被正式记录或检查。

当测试通过并且拉取请求得到相关方的批准后，committer 将会合并该拉取请求。这是通过一个**执行压缩合并（squash merge）的命令行工具**完成的。

关于压缩合并的详情

拉取请求会通过压缩合并的方式进行合并，这样您所有的提交都会被记录为对 main 分支的单个提交；这简化了 GitHub issues 和提交之间的联系，使得通过二分法查找历史记录以确定更改引入的位置变得更容易，并帮助我们能够将单个补丁挑选（cherry-pick）到维护分支上。

您的拉取请求在 GitHub 界面上将显示为“已合并”。在该提交的提交信息中，合并工具会添加拉取请求的描述、一个指回拉取请求的链接，以及贡献者和任何共同作者的署名。

实验性仓库#

Apache Arrow 在革命者规则的背景下，对开发实验性仓库有明确的政策。

该政策的主要动机是提供一种轻量级机制，以便在 ASF 和 Apache Arrow 的治理模型内，以必要的创作自由度进行实验性工作。该政策允许 committer 在新的仓库上工作，因为这些仓库提供了许多重要的管理工具（例如 GitHub issues、“watch”、“github stars”来衡量整体兴趣）。

流程#

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

  • committer *必须*发起一个邮件线程，其唯一目的是向社区通报该仓库的状态更新。

  • 该仓库*不得*有正式的发布版本。

  • 任何将实验性仓库以任何方式转为正式的决定，无论是通过合并还是迁移，*必须*在邮件列表中讨论并投票决定。

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

  • committer 决定何时将仓库归档。

仓库管理#

  • 仓库*必须*在 apache/ 下。

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

  • committer 对仓库拥有完全权限（在 ASF 允许的范围内）。

  • 推送/合并权限*只能*授予 Apache Arrow 的 committer。

开发流程#

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

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

分歧#

  • 如果上述任何“必须”项未能实现，且 committer 在被要求后未采取纠正措施，PMC *应*接管并决定如何处理。

特定功能指南#

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

字节序（Endianness）#

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

  1. 一个稳健（非易变、在合理时间内返回结果）的持续集成（CI）设置。

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

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

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

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

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

当前旨在实现跨字节序支持的实现有：

  1. C++

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

  1. Java

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