贡献概述#

本地 Git 约定#

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

  • 基于你**个人 fork** 的 apache/arrow 仓库进行工作，并提交拉取请求到“上游”。

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

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

  • 你的分支叫什么名字并不重要。有些人喜欢使用 GitHub 问题编号作为分支名称，另一些人则使用描述性名称。

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

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

  • 如果发生冲突，并且你的本地提交历史记录有多个提交，你可以通过**将你的本地提交压缩成一个提交**来简化冲突解决过程。保留提交历史记录并不那么重要，因为当你的功能分支合并到上游时，会自动进行压缩。

    如何压缩本地提交？

    使用以下命令中止 rebase:

    $ git rebase --abort

    git rebase --abort

    $ git rebase --interactive ORIG_HEAD~n

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

    git rebase -i HEAD~n

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

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

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

    git push --force-with-lease origin <branch_name>

    [pull]
      rebase = true

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

将 rebase 设置为默认值

  • 如果在你的仓库的 .git/config 中设置以下内容，则可以从 git pull 命令中省略 --rebase 选项，因为它默认情况下是隐含的。

  • [pull]

  • 拉取请求和审查#

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

将补丁作为 **GitHub 拉取请求** 提交到 **main 分支**。

  • 为了使你的拉取请求与 GitHub 问题同步，请**在拉取请求标题前加上 GitHub 问题 ID**（例如：GH-14866: [C++] 删除内部 GroupBy 实现）。

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

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

  • 核心开发人员和其他与你的更改所影响的项目部分相关的利益相关者将进行审查、请求更改，并最终表示批准。为了使每个人的审查过程顺利进行，请尝试

    如果可能，将你的工作分解成小的、单一用途的补丁。

  • 合并一个包含许多不相交功能的大更改要困难得多，尤其是如果你是项目新手，维护者更容易接受小的更改。

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

**遵循你正在修改的项目部分的风格指南**。

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

尝试使代码库看起来像只有一个作者，并模仿你看到的任何约定，无论它们是否正式记录或检查。

当测试通过并且拉取请求获得相关方的批准后，提交者 将合并拉取请求。这是使用**执行压缩合并的命令行实用程序**完成的。

压缩合并的详细信息

拉取请求与压缩合并合并，以便你的所有提交都将注册为对 main 分支的单个提交；这简化了 GitHub 问题与提交之间的连接，更容易 bisect 历史记录以识别引入更改的位置，并帮助我们能够将单个补丁 cherry-pick 到维护分支上。

你的拉取请求将出现在 GitHub 界面中，显示为“已合并”。在该提交的提交消息中，合并工具添加了拉取请求描述、指向拉取请求的链接以及对贡献者和任何共同作者的署名。

  • 实验性仓库#

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

  • 此策略的主要动机是提供一种轻量级机制，以便在 ASF 和 Apache Arrow 治理模型中以必要的创作自由进行实验性工作。此策略允许提交者处理新的仓库，因为它们提供了许多重要的管理工具（例如 github 问题、“watch”、“github stars”来衡量总体兴趣）。

  • 流程#

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

  • 提交者**必须**发起一个电子邮件主题，其唯一目的是向社区 ارائه有关仓库状态的更新。

仓库**不得**有官方版本。

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

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

  • 提交者决定何时归档仓库。

  • 仓库管理#

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

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

  • 提交者对仓库拥有完全权限（在 ASF 中可能的情况下）

推送/合并权限**只能**授予 Apache Arrow 提交者

  • 开发流程#

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

提交者决定如何管理问题、PR 等。

差异#

如果上述任何“必须”未能实现，并且提交者在请求后未采取任何更正措施，PMC **应该**取得所有权并决定该怎么做。

  1. 特定功能的指南#

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

字节序#

  1. Arrow 格式允许设置字节序。由于小端架构的流行，大多数实现默认情况下都采用小端。也一直在努力支持大端平台。根据邮件列表讨论，新平台的要求是

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

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

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

  1. C++

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

  1. Java

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