企业官网建设流程全解析

• 数据工程
• 大数据
• 序列化
• 数据分析

本文是一份面向 Apache Arrow 项目贡献者的实战指南。全文以仓库内 docs/source/developers/index.rst 为核心骨架，系统梳理了从零开始的开发环境准备、各语言（C++/Java/Python/R/Ruby）开发入口、Bug 报告与 Issue 生命周期、本地 git 规范、Pull Request 与评审流程、持续集成（CI）与 Archery 工具链，以及发布、基准测试与文档构建等关键环节。读完本文，你将掌握在 Arrow 仓库中完成一次“发现 Issue → 本地构建 → 提交 PR → 通过评审 → 合并”全流程的具体操作，并了解如何参与代码评审与发布验证。

面向开发者的一站式入口

Apache Arrow 是一个跨语言的列式内存数据格式与处理平台，包含 C++、Java、Python、R、Ruby、Go、C#、JavaScript 等多种语言的实现。正因为语言矩阵庞大，开发者文档首页 采用了按语言分栏（tab）导航的设计：每个语言入口指向该语言专属的开发指南，方便开发者直接进入自己关心的实现。

此外，该页面同时是贡献指南的总门户，聚合了以下核心文档（均位于docs/source/developers/下）：

• bug_reports.rst：Bug 报告与功能请求规范；
• guide/index.rst：新贡献者指南（含架构概览、沟通渠道、分步教程）；
• overview.rst：贡献流程总览（git 规范、PR 与评审、特定功能指引）；
• reviewing.rst：代码评审原则与标签体系；
• continuous_integration/index.rst：持续集成（含 Archery、Crossbow、Docker）；
• benchmarks.rst：基准测试；
• documentation.rst：文档改进与构建；
• release.rst 与 release_verification.rst：发布流程与发布验证。

加入社区：沟通渠道与行为准则

在写任何代码之前，官方文档给出的建议是先从社区参与开始。Arrow 的所有参与行为都受 ASF（Apache 软件基金会）行为准则约束，参与讨论、提交 Issue、评审 PR 均适用。

邮件列表是决策的公开记录

ASF 项目通过公开、可归档的邮件列表记录开发活动与决策过程。虽然邮件列表没有聊天工具即时，但它给参与者留出了深思熟虑的空间，也让分布在不同时区的开发者能够更平等地参与。相关的沟通渠道细节可以在 guide/communication.rst 中查看。

两条低门槛贡献路径

1. Bug 报告与功能请求：即使你无法自己解决问题，反馈也能帮助维护者理解问题并排定工作优先级。规范见下文“Bug 报告与功能请求”一节。
2. 改进文档：这是新手熟悉提交与评审流程的低成本方式，很多纯文档改动甚至可以直接在 GitHub 网页界面上点击 “edit” 完成——系统会自动为你处理 fork 和 pull request。

Bug 报告与功能请求：写一份高质量 Issue

bug_reports.rst 详细规定了 Issue 的创建规范。Arrow 使用GitHub Issues统一跟踪 Bug 与功能请求。

创建前的准备：先搜索

创建新 Issue 之前，务必先搜索是否有未关闭的既有 Issue 描述了同一问题或功能请求，避免重复。

一份有效 Issue 的描述要素

• 清晰、最小的复现步骤，并尽可能减少非 Arrow 依赖。例如文件读取问题应提供尽量小的示例文件或生成该文件的代码——官方文档明确指出：如果报告写“读我的文件时崩溃，但我不能分享文件”，开发者几乎无法调试。
• 相关的操作系统、语言、库版本信息；
• 若不明显，需明确写出期望行为与实际行为；
• 一个 Issue 只处理一个 Bug 或功能，不要把多个问题堆叠进同一 Issue。

文档中给出了两个高质量 Bug 报告示例，本文摘录其一（Python 侧）：

import pyarrow as pa a = pa.array([0], pa.timestamp('s', tz='+02:00')) print(a) # representation not correct? # <pyarrow.lib.TimestampArray object at 0x7f834c7cb9a8> # [ # 1970-01-01 00:00:00 # ] print(a[0]) #Traceback (most recent call last): # File "<stdin>", line 1, in <module> # ... #ValueError: fromutc: dt.tzinfo is not self

这个示例的价值在于：代码可直接运行、输出完整、异常堆栈清晰，开发者拿到后能立刻定位到pyarrow/scalar.pxi中TimestampScalar.as_py的时区处理逻辑。

标注所属组件

Arrow 组件众多（Component: Python、Component: C++ 等），正确标注组件能让 Issue 更快被相关维护者看到：

• 提交时在 Issue 标题前用方括号加组件名作为前缀，例如[Python] issue summary；
• 三个特例的前缀与组件名不同：
  • Continuous Integration组件 → 前缀[CI]；
  • Developer Tools组件 → 前缀[Dev]；
  • Documentation组件 → 前缀[Docs]。

Issue 生命周期与认领

Bug 与功能请求都遵循定义好的生命周期：正在处理中的 Issue 应有指派的开发者；关闭时有两种终态：

• Closed as completed：问题已解决，关联的 PR 会被 GitHub 自动链接（前提是 PR 正确引用了 Issue 编号）。合并 PR 时建议在被解决的 Issue 上留言说明由哪个 PR 解决，这样 GitHub 会通知所有协作过的人；
• Closed as not planned：Issue 被关闭且不再更新，但没有采取任何行动。

认领规则：当贡献者开始工作时，可在 Issue 下评论take实现自指派，这向社区传递了“我正在处理”的信号。

本地 git 规范与 Pull Request 流程

overview.rst 给出了贡献者在本地使用 git 的推荐做法。

git 约定清单

• 基于apache/arrow 的个人 fork工作，PR 向上游提交；
• 保持 fork 的main 分支与 upstream/main 同步；
• 在分支上开发，不要直接在自己的 main 上开发（分支名随意，可以用 Issue 编号，也可以用描述性名字）；
• 定期与 upstream/main 同步分支，因为 main 每天都会合入大量提交；
• 推荐使用git rebase而非git merge；
• 冲突且本地提交历史较长时，把本地提交 squash 成一个提交——因为上游合并时本来就会自动 squash，保留历史意义不大。

冲突处理与 squash 实操

冲突时可以先用git rebase --abort中止 rebase，再交互式压缩本地提交：

$ git rebase --interactive ORIG_HEAD~n

其中n是本地分支的提交数。squash 后重新 merge，冲突解决会简单很多。由于本地历史已改写，推送时需要强制推送，官方推荐使用更安全的--force-with-lease：

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

--force-with-lease在远端存在本地没有的提交时（例如同事又提交了新内容）会失败，从而避免覆盖他人的提交；这比裸用--force安全得多。

如果希望git pull默认使用 rebase，可在仓库.git/config中配置：

[pull] rebase = true

提交 PR 的检查清单

• 针对main 分支提交GitHub Pull Request；
• PR 标题前缀使用 GitHub Issue id（如GH-14866: [C++] Remove internal GroupBy implementation）；若 Issue 仍在 Jira 中，则使用 JIRA id 前缀（如ARROW-767: [C++] Filesystem abstraction），这样 PR 能与 Issue 自动同步；
• 给出清晰、简短的 PR 描述——合并后它会保留在扩展提交信息中；
• 确保代码通过单元测试（各 Arrow 组件 README 中有对应运行说明）。

让评审更顺畅的实践

• 尽量把工作拆成小而单一用途的补丁——大型多功能的改动很难合入，对新贡献者尤其如此；
• 为新代码补充单元测试；
• 遵循风格指南（C++、Python 等语言在 CI 中会跑 lint 检查，其他语言见各自的开发者文档与 README）；
• 尽量让代码看起来像出自同一作者之手——模仿代码库中已有的约定，无论是否被正式文档记录。

squash merge 的细节

评审通过后，committer 使用命令行工具进行squash merge：PR 的所有提交在主分支上合并为一个提交。好处是：简化 GitHub Issue 与提交之间的对应关系、便于用git bisect定位引入变更的提交、也便于将单个补丁 cherry-pick 到维护分支。合并后的提交信息会包含 PR 描述、PR 链接、贡献者及共同作者的署名。

新贡献者指南：从零到第一个 PR

guide/index.rst 为新贡献者提供了快速参考清单和完整的分步指引。

Quick Reference 六个步骤

1. 安装配置 Git，fork Arrow 仓库：详见 guide/step_by_step/set_up.rst；
2. 构建 Arrow：Arrow 库功能庞大，取决于启用的构建选项和组件可能需要安装第三方包。C++ 构建问题可参考 cpp/building.rst，卡住时通过沟通渠道求助；
3. 运行测试：例如在终端运行 Python 测试pytest pyarrow，或在 R 控制台运行devtools::test()；
4. 找到 Issue（如需）、创建新分支并开始工作：找灵感可看 finding_issues.rst，了解代码结构可读 arrow_codebase.rst；
5. 实现完成后编写并运行测试：参考 testing.rst，并运行 linter 确保代码符合风格规范；
6. 推送分支并创建 Pull Request：详见 pr_lifecycle.rst。

不止写代码：其他贡献方式

• 改进文档是最佳起点之一，详见 guide/documentation.rst；
• Apache Arrow Cookbook（菜谱集合）同样欢迎贡献。

各语言开发指南与源码构建

C++：多环境构建矩阵

C++ 开发指南位于 docs/source/developers/cpp/index.rst，包含 6 个子主题：

• building：构建 Arrow C++（含依赖管理与 CMake 选项）；
• development：开发环境与调试；
• windows：Windows 平台构建；
• emscripten：WebAssembly/Emscripten 构建；
• conventions：代码规范；
• fuzzing：模糊测试（见 cpp/fuzzing.rst，评审指南中专门提到对处理不可信数据的 API 应配置 fuzz testing）。

仓库中cpp/CMakeLists.txt是构建入口，cpp/CMakePresets.json提供了现成的构建预设，ci/scripts/cpp_build.sh封装了 CI 中的构建命令，可作为本地构建的参考。相关高级主题还包括 cpp/conventions.rst（代码风格）与 cpp/windows.rst。

Java：Maven 多模块工程

Java 开发指南位于 docs/source/developers/java/index.rst，包含 building 与 development 两个子页面。Java 实现采用 Maven 多模块结构，根pom.xml管理所有模块；仓库内 java/README.md 与ci/scripts/java_build.sh、ci/scripts/java_test.sh提供了构建与测试的落地脚本，可与文档配合使用。

Python：PyArrow 完整构建流程

python.rst 是最详尽的语言级开发指南之一，覆盖 Linux、macOS、Windows 三大平台的 PyArrow 源码构建。

编码风格与 lint

PyArrow 采用与 pandas 项目类似的 PEP8 风格，使用 Archery 的lint子命令检查：

$ pip install -e "arrow/dev/archery[lint]" $ archery lint --python

部分问题可自动修复（--fix），Python 代码库中的 C++ 文件可用--clang-format修正格式：

$ archery lint --python --fix $ archery lint --python --clang-format --fix

单元测试与测试分组

使用 pytest，构建后运行：

$ pushd arrow/python $ python -m pytest pyarrow $ popd

测试依赖在python/requirements-test.txt中，可用pip install -r requirements-test.txt安装。若出现pyarrow._lib导入错误，检查可编辑安装是否正确。

PyArrow 用 pytest marks 对测试分组，很多分组默认禁用：

• dataset：Arrow Dataset 测试；
• flight：Flight RPC 测试；
• gandiva：Gandiva 表达式编译器测试（依赖 LLVM）；
• hdfs：libhdfs 访问 Hadoop 文件系统；
• hypothesis：基于 hypothesis 生成随机用例（注意需用--enable-hypothesis，--hypothesis因 pytest 限制不可用）；
• large_memory：需要大量系统内存；
• orc、parquet、s3、tensorflow：对应组件测试。

启用/禁用/仅运行某组：--parquet、--disable-parquet、--only-parquet。所有自定义选项可通过python -m pytest pyarrow --help查看 “custom options” 一节。文档还支持 doctest 检查：python -m pytest --doctest-modules（.py 文件）与python -m pytest --doctest-cython（.pyx/.pxi 文件，需安装 pytest-cython 插件）。此外还有少量直接以 C++ 编写的底层测试（python/pyarrow/src/python_test.cc），它们被包装进 pytest 测试模块自动随套件运行。

Linux/macOS 构建：Conda 方式

先克隆仓库并初始化测试数据子模块：

$ git clone https://github.com/apache/arrow.git $ pushd arrow $ git submodule update --init $ export PARQUET_TEST_DATA="${PWD}/cpp/submodules/parquet-testing/data" $ export ARROW_TEST_DATA="${PWD}/testing/data" $ popd

创建 conda 开发环境（目标 Python 3.10），依赖来自仓库内的ci/conda_env_*.txt：

$ conda create -y -n pyarrow-dev -c conda-forge \ --file arrow/ci/conda_env_unix.txt \ --file arrow/ci/conda_env_cpp.txt \ --file arrow/ci/conda_env_python.txt \ --file arrow/ci/conda_env_gandiva.txt \ compilers \ python=3.10 \ pandas $ conda activate pyarrow-dev $ export ARROW_HOME=$CONDA_PREFIX

Linux/macOS 构建：系统依赖 + venv 方式

macOS 可用 Homebrew：brew update && brew bundle --file=arrow/cpp/Brewfile；Debian/Ubuntu 最小依赖为build-essential cmake python3-dev。然后：

$ python3 -m venv pyarrow-dev $ source ./pyarrow-dev/bin/activate $ pip install -r arrow/python/requirements-build.txt $ mkdir dist $ export ARROW_HOME=$(pwd)/dist $ export LD_LIBRARY_PATH=$(pwd)/dist/lib:$LD_LIBRARY_PATH $ export CMAKE_PREFIX_PATH=$ARROW_HOME:$CMAKE_PREFIX_PATH

构建 C++ 核心并安装

$ cmake -S arrow/cpp -B arrow/cpp/build \ -DCMAKE_INSTALL_PREFIX=$ARROW_HOME \ --preset ninja-release-python $ cmake --build arrow/cpp/build --target install

预设（preset）是便捷方式，常见选项包括：

• ninja-release-python：默认开发构建；
• ninja-release-python-maximal：启用更多功能（CUDA、Flight、Gandiva 等）；
• ninja-release-python-minimal：更少功能（去掉 ORC、dataset 等）；
• 将release换成debug即得到 Debug 构建。

也可以放弃预设，直接显式指定组件（部分示例）：

$ cmake -S arrow/cpp -B arrow/cpp/build \ -DCMAKE_INSTALL_PREFIX=$ARROW_HOME \ -DCMAKE_BUILD_TYPE=Debug \ -DARROW_BUILD_TESTS=ON \ -DARROW_COMPUTE=ON \ -DARROW_CSV=ON \ -DARROW_DATASET=ON \ -DARROW_FILESYSTEM=ON \ -DARROW_HDFS=ON \ -DARROW_JSON=ON \ -DARROW_PARQUET=ON \ -DARROW_WITH_LZ4=ON \ -DARROW_WITH_SNAPPY=ON \ -DARROW_WITH_ZLIB=ON \ -DARROW_WITH_ZSTD=ON \ -DPARQUET_REQUIRE_ENCRYPTION=ON $ cmake --build arrow/cpp/build --target install -j4

可切换的可选组件包括：ARROW_CUDA（CUDA GPU 支持）、ARROW_DATASET（Dataset）、ARROW_FLIGHT（Flight RPC）、ARROW_GANDIVA（LLVM 表达式编译器）、ARROW_ORC（ORC 格式）、ARROW_PARQUET（Parquet）、PARQUET_REQUIRE_ENCRYPTION（Parquet 模块化加密）。CMAKE_BUILD_TYPE可选Release（默认，开优化关调试信息）、Debug（关优化开调试信息）、RelWithDebInfo（两者都开）。若系统装有多个 Python，可加-DPython3_EXECUTABLE=<path/to/bin/python>指定解释器；Linux 多架构环境下建议-DCMAKE_INSTALL_LIBDIR=lib（Python 构建脚本假定库目录为 lib）。

构建 PyArrow

$ pushd arrow/python $ export PYARROW_PARALLEL=4 $ python setup.py build_ext --inplace $ popd

说明：

• C++ 中启用的可选组件会默认启用对应的 PyArrow 组件，可用PYARROW_WITH_$COMPONENT覆盖；
• PYARROW_PARALLEL控制编译 C++/Cython 组件的线程数；
• 清理过期构建产物：git clean -Xfd .（在arrow/python下）；
• PyArrow 默认按 release 构建，即使 C++ 是 debug；要生成 debug 构建，先执行export PYARROW_BUILD_TYPE=debug；
• 自包含 wheel：python setup.py build_ext --build-type=$ARROW_BUILD_TYPE --bundle-arrow-cpp bdist_wheel；
• 可编辑安装：在arrow/python目录执行pip install -e . --no-build-isolation。

Windows 构建

Windows 需要 VS2017 Build Tools 或 Visual Studio 2017（安装时至少选择一个 Windows SDK）。使用 conda 引导环境后：

$ set ARROW_HOME=%CONDA_PREFIX%\Library $ mkdir arrow\cpp\build $ pushd arrow\cpp\build $ cmake -G "Ninja" ^ -DCMAKE_INSTALL_PREFIX=%ARROW_HOME% ^ -DCMAKE_UNITY_BUILD=ON ^ -DARROW_COMPUTE=ON ^ -DARROW_CSV=ON ^ -DARROW_CXXFLAGS="/WX /MP" ^ -DARROW_DATASET=ON ^ -DARROW_FILESYSTEM=ON ^ -DARROW_HDFS=ON ^ -DARROW_JSON=ON ^ -DARROW_PARQUET=ON ^ -DARROW_WITH_LZ4=ON ^ -DARROW_WITH_SNAPPY=ON ^ -DARROW_WITH_ZLIB=ON ^ -DARROW_WITH_ZSTD=ON ^ .. $ cmake --build . --target install --config Release $ popd $ pushd arrow\python $ set CONDA_DLL_SEARCH_MODIFICATION_ENABLE=1 $ python setup.py build_ext --inplace $ popd

之后运行python -m pytest pyarrow。注意：Windows 开发构建默认不捆绑C++ 库，便于独立重建 C++；若不用 conda，需将 DLL 目录加入PATH，或设置PYARROW_BUNDLE_ARROW_CPP=1捆绑（捆绑后重建 C++ 不会自动更新）。

PyArrow 环境变量速查表

PyArrow 组件默认跟随 C++ 的ARROW_$COMPONENT标志，但可用PYARROW_WITH_$COMPONENT覆盖，对应关系（摘录）：ARROW_GCS→PYARROW_WITH_GCS、ARROW_S3→PYARROW_WITH_S3、ARROW_AZURE→PYARROW_WITH_AZURE、ARROW_HDFS→PYARROW_WITH_HDFS、ARROW_CUDA→PYARROW_WITH_CUDA、ARROW_SUBSTRAIT→PYARROW_WITH_SUBSTRAIT、ARROW_FLIGHT→PYARROW_WITH_FLIGHT、ARROW_ACERO→PYARROW_WITH_ACERO、ARROW_DATASET→PYARROW_WITH_DATASET、ARROW_PARQUET→PYARROW_WITH_PARQUET、PARQUET_REQUIRE_ENCRYPTION→PYARROW_WITH_PARQUET_ENCRYPTION、ARROW_ORC→PYARROW_WITH_ORC、ARROW_GANDIVA→PYARROW_WITH_GANDIVA。

清理过期构建产物

当 Arrow C++ 或 PyArrow 结构变化后，清理是修复构建错误的首选手段（典型错误如 “Unknown CMake command arrow_keep_backward_compatibility”）：

$ rm -rf arrow/cpp/build $ git clean -Xfd python

conda 环境下$ARROW_HOME（即$CONDA_PREFIX）中的构建产物（如lib/cmake/Arrow*、include/arrow、lib/libarrow*）可手动删除，或直接重建环境：conda remove -n pyarrow-dev。

夜间包（Nightly Packages）

PyArrow 提供供测试的夜间 wheel 和 conda 包（非正式发布，使用风险自负），适合下游库在 CI 中提前验证兼容性：

$ conda install -c arrow-nightlies pyarrow $ pip install --extra-index-url https://pypi.fury.io/arrow-nightlies/ \ --prefer-binary --pre pyarrow

（使用 conda 方式时需将其他包来源配置为 conda-forge。）

持续集成（CI）：从 GitHub Actions 到 Crossbow

Arrow 的 CI 需要在包管理器、编译器、多个软件库版本、操作系统等大量组合上运行，因此相当复杂。continuous_integration/index.rst 及其子页面给出了整体视图。

核心文件与目录

• docker-compose.yml：定义 Docker 服务，可通过环境变量或其默认值配置；
• .env：定义docker-compose.yml中服务的默认配置值；
• appveyor.yml：定义在 Appveyor 上运行的工作流；
• .github/workflows：GitHub Actions 工作流，由 PR 提交/合并等动作触发；
• dev/tasks：由archery crossbow submit ...触发的扩展任务（多为夜间构建或发布相关）；
• ci/：脚本、Dockerfile 及补充文件（补丁、conda 环境文件、vcpkg triplet 文件等）。

两大类构建

• 动作触发构建（action-triggered builds）：由 GitHub 上的具体动作（打开 PR、合并 PR 等）触发。多数工作流是各语言实现专属的（仅当改动影响该语言时运行）；值得注意的还有：
  • archery.yml：Archery 工具或其任务有改动时运行校验；
  • comment_bot.yml：监听 PR 评论中的特定字符串触发动作——@github-actions crossbow submit ...运行指定 Crossbow 命令、@github-actions autotune运行一系列风格格式化并构建部分文档、@github-actions rebase将 PR rebase 到 main 分支；
  • dev.yml：PR 有活动或被合并时运行，执行 linter 并检查 PR 是否可合并；
  • dev_pr.yml：PR 打开或更新时运行，检查 PR 标题格式、为对应 GitHub Issue 添加指派者（或提醒在标题中包含 Issue id）、添加相关标签。
  • appveyor.yml：针对 Python/C++ 相关提交运行。
• 扩展构建（extended builds）：手动触发，多数按夜间节奏运行。Crossbow 是 Archery 的子组件，其任务配置在dev/tasks/tasks.yml中，子目录按语言/包管理系统划分任务模板（jinja2 语法）。任务定义中记录了要运行的docker-compose.yml服务、CI 服务以及使用的模板文件。多数任务随夜间构建运行，也可通过在 PR 下评论@github-actions crossbow submit <任务名>手动触发。

Docker 与 Archery

Arrow 使用Docker获得可移植、可复现的 Linux 构建（Windows 构建则使用 Windows 容器），用Archery与Crossbow协调各种 CI 任务。docker-compose.yml中部分服务存在依赖关系，本地运行时需先手动构建依赖，或使用archery docker run ...（会自动查找并构建依赖）。

Archery：日常开发工具

archery.rst 介绍了这个用 Python 编写的开发者工具。安装要求 Python 3.8+，推荐以 editable 模式安装以便随仓库更新：

$ pip install -e "dev/archery[all]"

Archery 的许多操作依赖 Docker 与 docker-compose。其顶层命令（archery --help）包括：

每个子命令都有独立帮助，例如archery docker --help显示images（列出可用的 docker-compose 镜像）、push（推送生成的镜像）、run（执行 docker-compose 构建），以及--src选项指定 Arrow 源码目录。

代码评审：原则、指南与标签

reviewing.rst 面向 committer 与评审者，其核心原则是：Arrow 是需要长期演进的基石型项目，严谨评审带来的长期收益大于宽松快速合并。指南明确表示这些不是硬性规则，评审者应基于专业判断灵活调整。

关键评审维度

• 范围与完整性：不引入回归、不合并需要 follow-up 才能正常工作的 PR；大功能按“功能内聚”切分（例如文件系统实现：第一批 PR 做目录元数据操作、第二批做文件读取、第三批做文件写入）；范围取舍由作者与评审者协商。
• 公共 API 设计：公共 API 应引导用户使用最理想的构造（安全 API 应比不安全 API 更显眼）；倾向于产出可读代码（选项多时合理组织而非堆砌在函数签名里，参见 CSV 读取 API）；命名要准确、术语要一致；不确定的 API 应标记为experimental，但不能借此逃避基本设计原则。
• 健壮性：Arrow 会被用在非常广泛的场景（包括在 Jupyter 提示符下摆弄人造数据），公共 API 不应在“异常但合法”的输入上崩溃或产生未定义行为；对复杂算法可用防御式编码（如仅 debug 生效的断言）；处理不可信数据（如磁盘文件格式）的 API 应避免崩溃或静默错误；调用外部 API（尤其是系统函数或 I/O）时要检查并传播错误。
• 性能：思考性能但不过度执着——关注算法复杂度，对性能敏感功能，提升 20% 以上的微优化才有意义；如果性能重要，就要测量而非靠猜测；避免为了“欺骗”编译器/解释器而写花哨代码；避免退化行为（如内存暴涨）比小幅优化常见路径更重要。
• 文档：措辞要信息量大（例如“如果发生错误会抛异常/行为未定义”比“这是一个错误”更有用）；注意拼写、语法、表达与简洁性；善用 Sphinx 的交叉引用能力。
• 测试：新增 API 的所有名义场景都要有测试（是否允许 null、是否支持不同类型等）；精细的方面要测；角落场景要覆盖（空数组、零 chunk 数组、全 null 数组等，尤其 C++ 这类底层语言）；压力测试有用但要权衡 CI 运行成本。

社会协作规范

• 评审是贡献者与评审者之间的沟通：不要长时间不回复（两周可作为一个合理上限），没时间或没答案就明确说出来；
• 知道谁能帮忙解决阻塞问题时，可以温和地 @ 对方加入讨论；
• 贡献者 PR 长时间无更新时，主动询问是否卡住了、是否需要帮助；
• 对真正有价值的贡献，贡献者无进展时也可以接手，但出于礼貌应先询问；
• 有的贡献者只想要快速修复，有的则渴望学习改进，后者更可能成为长期贡献者甚至 committer；
• 对“我以后会修，先合并吧”的请求要谨慎：如果贡献者此前表现出可靠性可以接受，否则最好拒绝；
• PR 只剩琐碎/无争议问题时，评审者可以直接代为修改；
• 评审受 Apache 行为准则约束，对评审者和贡献者都适用。

标签体系（用于发布高亮）

评审 PR 时，要判断对应 Issue 是否需要标记以下标签：

• Critical Fix：修复 (a) 安全漏洞；(b) 产生错误或无效数据的 Bug；(c) 导致崩溃的 Bug（在 API 契约成立的前提下）。崩溃类被视为 Critical，因为可能是拒绝服务（DoS）攻击的向量；
• Breaking Change：破坏公共 API 向后兼容的变更。对 C++ 来说，仅破坏 ABI 不算（除非是明确保证 ABI 的地方，如 C Data Interface）；experimental API 不豁免。

两者的区别：Breaking change 改变 API 契约，Critical fix 让实现与既有契约一致（例如修复 Parquet 读取器跳过含数字 42 的行的 Bug，是 critical fix 而非 breaking change）。这些标签在发布时用于提示用户升级风险。

优先级标签还有：

• Priority: Blocker：下个发布前必须合入（包括导致打包或验证失败的测试/打包修复）；
• Priority: Critical：高优先级，是 “Critical Fix” 的超集。

协作者（Collaborator）角色

协作者拥有 triage 权限，可帮助给 Issue 打标签和指派。持续参与（创建 PR、回答问题、创建 Issue、评审 PR 等）的用户可申请或被提名。提名方式是创建 PR 将用户加入.asf.yaml的 collaborators 列表，由 committer 审核其历史协作后批准；长期不活跃的协作者可能被移除。

特定功能指引：以字节序支持为例

overview.rst 的 “Guidance for specific features” 记录了社区对特定功能方向的决策，其中以字节序（Endianness）为例，展示了此类社区讨论的决策框架：

• Arrow 格式允许设置字节序，但由于小端架构的普及，多数实现默认假设小端；
• 基于邮件列表讨论，新平台支持的两项硬性要求是：1) 稳健（不 flaky、合理时间内返回结果）的 CI 配置；2) 性能关键代码的基准测试以证明无回归；
• 大端支持分两个层次：原生字节序（所有 Arrow 通信发生在同字节序进程间，含读写 Parquet 等文件格式的辅助功能）与跨字节序支持（实现会在 IPC 与 Flight 消息时做字节重排）；
• 支持到哪一层次由维护者对复杂度和技术风险的偏好决定；当前目标是跨字节序支持的实现是 C++，不打算实现跨字节序支持的是 Java；其他库在提交 PR 前应先通过邮件列表讨论达成共识。

文档改进与构建

documentation.rst 说明文档构建流程：使用Doxygen + Sphinx及若干扩展。

依赖安装

$ conda install -c conda-forge --file=arrow/ci/conda_env_sphinx.txt

非 conda 方式需自行安装 Doxygen，再安装 Python 依赖：

$ pip install -r arrow/docs/requirements.txt

构建步骤（按顺序）

1. 用 Doxygen 处理 C++ API：

   $ pushd arrow/cpp/apidoc $ doxygen $ popd

2. 用 Sphinx 构建完整文档：

   $ pushd arrow/docs $ make html $ popd

构建 Python 绑定文档部分前需要环境中已安装pyarrow（否则 Python 部分会缺失且链接失效）；没有 CUDA 支持时部分 Python API 文档也无法构建。构建产物位于arrow/docs/_build/html，浏览器打开arrow/docs/_build/html/index.html即可查看。也可用 Archery 在 Docker 中构建：

$ archery docker run -v "${PWD}/docs:/build/docs" ubuntu-docs

输出位于${PWD}/docs目录。

基准测试、发布与发布验证

开发者文档首页还导航到以下主题（均为docs/source/developers/下的独立页面）：

• 基准测试（benchmarks.rst）：如何使用基准测试套件；
• 发布指南（release.rst）：执行一次发布所遵循的详细步骤；
• 发布验证（release_verification.rst）：如何验证一个发布版本。

在仓库中，发布相关脚本位于 dev/release（多为 shell/Ruby 脚本），配合 dev/archery 中的release子命令使用；ci/scripts/release_test.sh 提供了发布测试的参考实现。

结语：一份完整的贡献行动清单

综合开发者文档首页及全部子页面，一次完整的 Arrow 贡献可以归纳为以下行动清单：

1. 阅读 行为准则 与沟通渠道，加入邮件列表；
2. 在 GitHub Issues 中搜索并创建高质量 Issue（标题加组件前缀，必要时评论take自指派）；
3. fork 仓库、保持 main 同步、基于分支开发，并遵循本地 git 规范；
4. 按目标语言指南完成构建与测试（C++ 参考 cpp/index.rst，Java 参考 java/index.rst），用archery lint保证代码风格；
5. 提交 PR（标题带 Issue id）、主动沟通、根据评审指南修改；
6. 关注 CI 结果（GitHub Actions 工作流 与 Crossbow），必要时用@github-actions crossbow submit触发扩展构建；
7. 合并后持续跟进 Issue 关闭状态，为发布与文档生态贡献力量。

Apache Arrow 官方开发者文档本身即是“按语言分栏 + 分主题聚合”的导航体系，本文以仓库内docs/source/developers/目录的真实内容为据，将所有关键流程、命令与参数逐一还原，可作为你在 Arrow 仓库中从“读者”走向“贡献者”的完整路线图。

• 数据工程
• 大数据
• 序列化
• 数据分析