贡献概述#

本地 Git 约定#

如果您在本地跟踪 Arrow 源代码存储库，以下是如何使用 git 的清单

  • 基于您 apache/arrow 的**个人分支**进行工作，并提交“上游”的拉取请求。

  • 使您的分支的**主分支与 upstream/main 同步**。

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

  • 您为分支命名的方式无关紧要。有些人喜欢使用 GitHub 问题编号作为分支名称，其他人则使用描述性名称。

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

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

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

    如何压缩本地提交？

    使用以下命令中止变基

    $ 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，您可以确保不会覆盖这些提交，并且可以根据需要获取这些更改。

    将变基设置为默认值

    如果在存储库的 .git/config 中设置以下内容，则可以从 git pull 命令中省略 --rebase 选项，因为它默认为隐式。

    [pull]
      rebase = true

拉取请求和审查#

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

  • 将补丁作为**针对主分支的 GitHub 拉取请求**提交。

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

  • 为拉取请求提供**清晰简洁的描述**：合并拉取请求后，此描述将保留在扩展的提交消息中。

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

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

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

    合并包含大量不相关功能的大型更改要困难得多，特别是如果您是项目的初学者，维护人员更容易接受较小的更改。

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

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

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

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

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

压缩合并的详细信息

使用压缩合并合并拉取请求，以便所有提交都将注册为主分支中的单个提交；这简化了 GitHub 问题与提交之间的关联，使查找引入更改的位置的历史记录更容易，并帮助我们能够将单个补丁挑选到维护分支上。

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

实验性存储库#

Apache Arrow 有一项关于在 革命者规则 的上下文中开发实验性存储库的明确策略。

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

流程#

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

  • 提交者必须启动一个电子邮件线程，其唯一目的是向社区提供有关存储库状态的更新。

  • 存储库不得有官方版本。

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

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

  • 提交者决定何时存档存储库。

存储库管理#

  • 存储库必须位于 apache/ 下

  • 存储库的名称必须以 arrow-experimental- 为前缀

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

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

开发流程#

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

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

差异#

  • 如果上述任何“必须”未能实现，并且提交者未根据请求采取纠正措施，则 PMC应该承担所有权并决定采取什么措施。

特定功能的指南#

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

字节序#

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

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

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

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

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

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

支持哪个级别的决定是基于维护者对复杂性和技术风险的偏好。一般来说，所有实现都应开放本机字节序支持（只要满足 CI 和性能要求）。跨端支持是各个维护者的问题。

当前旨在实现跨端支持的实现是

  1. C++

不打算实现跨端支持的实现

  1. Java

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

本页内容
在 GitHub 上编辑