Apache Arrow R 包 CRAN 发布全流程指南从 Tracking Issue 到 r-universe 标签的 25 步实战【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow导读本文基于 Apache Arrow 仓库中的 CRAN 发布技能文档 .claude/skills/r-cran-release/SKILL.md 及其配套清单 r/PACKAGING.md系统讲解 {arrow} R 包即 Apache Arrow 的 R 语言接口从创建发布追踪 Issue 到最终打上r-universe-release标签的完整 25 步流程。文章以仓库内真实脚本与配置文件r/Makefile、r/tools/update-checksums.R、r/tools/contributor_stats.R、dev/tasks/r/github.linux.arrow.version.back.compat.yml 等为佐证深入剖析每一步背后的原理。读完本文你将掌握 {arrow} R 包在 CRAN 发布中涉及的版本分支策略、跨平台二进制校验、交叉编译Crossbow验证、checksum 机制、NEWS 润色规范与发布后收尾工作的完整执行方案。一、流程总览与核心原则{arrow} R 包是 Apache Arrow 多语言工具链的官方 R 接口核心功能由捆绑vendored的 Arrow C 库提供见 r/DESCRIPTION 中SystemRequirements: C20与Description描述。由于 R 包与 C 库的版本强耦合其 CRAN 发布流程比普通 R 包复杂得多包含 25 个明确步骤。整个流程贯穿三条核心原则严格按序执行不跳步每一步完成并经用户确认后才进入下一步同时在追踪 Issue 上同步勾选状态绝不代跑git push技能文档明确要求 Never rungit pushyourself, under any circumstances所有推送命令需展示给用户、由用户亲自执行并确认提前记录需 cherry-pick 的内容如果前面任何步骤发现需要补丁进发布分支的修改先在追踪 Issue 上评论记录等到第 10 步再统一处理。流程可划分为五个阶段阶段步骤目标准备阶段1–9建 Issue、建分支、清理 README、审查废弃函数、检查构建与 CRAN 状态分支修补10–11cherry-pick 必要修复、创建 Crossbow 验证 PR构建与校验12–16本地构建检查、更新 checksums、多平台二进制验证提交与收尾17–21提交 CRAN、打 r-universe 标签、更新兼容矩阵、社交媒体内容版本特定处理22–25补丁版本号更新、CRAN-only 文档更新、C 变更审查、清单复审二、准备阶段步骤 1–92.1 创建 GitHub 追踪 Issue步骤 1发布流程的第一步是向用户确认版本号VERSION然后用ghCLI 创建追踪 Issue并把 r/PACKAGING.md 中的复选框清单注入为 Issue 正文gh issue create --repo apache/arrow \ --title [R] CRAN packaging checklist for version VERSION \ --body $(cat r/PACKAGING.md | sed -n /^- \[ \]/,$p)该命令利用sed提取 PACKAGING.md 中所有未勾选- [ ]的清单行作为发布期间持续跟踪的状态看板。记录下 Issue 编号后续每一步完成时都要更新对应复选框。2.2 创建 CRAN 发布分支步骤 2分支策略是本流程中最关键的决策点。首先确认最终发布标签是否存在git fetch upstream --tags git tag -l apache-arrow-VERSION*分支来源有两种情况最终标签已存在apache-arrow-VERSION无 rc 后缀说明投票已通过必须从最终标签分支不要询问 RC 号——早期 RC 可能与最终发布处于不同 commit最终标签不存在投票仍在进行询问用户使用哪个 RC 号如 rc1、rc2再从对应 RC 标签分支。git checkout apache-arrow-VERSION # 投票已通过 # 或 git checkout apache-arrow-VERSION-rcN # 投票进行中 git checkout -b maint-VERSION-r # 创建分支先与用户确认 git push upstream maint-VERSION-r # 由用户执行分支统一命名为maint-VERSION-r后续所有操作都在该分支上进行。这种CRAN 专用分支设计使发布流程与 main 主线隔离避免发布期间的修补污染主线开发。2.3 移除 README 徽章步骤 3CRAN 对 README 中的动态徽章badges持谨慎态度因此发布分支上的 r/README.md 需删除!-- badges: start --与!-- badges: end --之间的所有内容sed -i.bak /!-- badges: start --/,/!-- badges: end --/d r/README.md rm r/README.md.bak删除后提交到maint-VERSION-r分支。PACKAGING.md 中特别提醒在 RC 提交上运行 URL 检查时徽章相关的报错可以忽略因为它们会在 CRAN 发布分支中被移除。2.4 审查废弃函数步骤 4R 包的函数生命周期遵循 deprecated → defunct → removed 的推进规则。本步骤扫描r/R/下所有使用.Deprecated()的函数grep -rn \.Deprecated r/R/*.R在当前仓库中可检索到多个实际匹配例如 r/R/feather.R、r/R/ipc-stream.R、r/R/dataset-format.R、r/R/dataset-write.R。维护者需逐条评估本次发布是否应把某些函数推进为.Defunct()报错或直接删除这属于 API 兼容性决策需谨慎判断。2.5 评估夜间构建状态步骤 5{arrow} 的夜间构建nightly builds复现了 CRAN 的大多数检查项其失败虽不必然导致 CRAN 拒绝但必须理解失败原因。发布者需确认 RC 时间点附近 R 夜间构建通过情况可通过 Zulip 或 Crossbow 状态页crossbow.arrow-dev.org核查。注意本仓库的夜间构建任务定义在 dev/tasks/tasks.yml 中其中r分组包含test-r-*、r-binary-packages、r-recheck-most等任务。2.6 检查当前 CRAN 检查结果步骤 6拉取 CRAN 上 arrow 包的检查结果页check_results_arrow.html提取平台、版本、状态三列并留意 Additional issues 部分。判定标准所有平台应为 OK 或 NOTE关于包体积的 NOTE如 installed size is 130 Mb是预期现象——这是捆绑 Arrow C 库的必然结果可以忽略其他 NOTE 以及任何 ERROR/WARN 都必须调查。2.7 确保 README 准确步骤 7逐项核对 r/README.md 的安装说明、功能描述、版本特定说明如 C 版本要求是否与当前功能一致清除过时信息并报告发现的问题。2.8 运行 URL 检查器步骤 8先确认当前在maint-VERSION-r分支git branch --show-current然后在 r 目录运行 URL 检查cd r Rscript -e urlchecker::url_check()由于徽章已在步骤 3 删除所有 URL 应通过检查若有坏链需修复。2.9 润色 NEWS步骤 9NEWS.md 是 CRAN 审核与用户了解变更的核心文档润色需遵循 tidyverse 风格style.tidyverse.org/news.html用现在时写 X now does Y不写 X did Y署名规则非包作者用username署名下列已列作者不再署名nealrichardson、ianmcook、thisisnic、paleolimbot、romainfrancois、jkeane、brycemecum、dragosmg、jeroenooms、assignUser分类使用 New features、Minor improvements and fixes、Installation如相关简洁与历史发布风格保持一致只含用户可见变更不包含 CI 更新和内部重构。当前 r/NEWS.md 即为遵循该规范的实例以# arrow 25.0.1为版本标题下设 Breaking changes、New features、Minor improvements and fixes 等分类条目以-开头并附 issue 编号。查找上一版本与自该版本以来的 R 提交grep ^# arrow r/NEWS.md | head -5 git log --oneline apache-arrow-PREVIOUS_VERSION..HEAD | grep \[R\]不要手动更新版本号——后续流程会自动完成。NEWS 更新通过 fork 上的分支origin 而非 upstream提交 PR 到 main稍后在步骤 10 cherry-pick 进maint-VERSION-r分支。三、分支修补与 Crossbow 验证步骤 10–113.1 Cherry-pick 必要修改步骤 10检查需要 cherry-pick 进发布分支的修复先看追踪 Issue 评论中记录的待补丁项再询问 main 上是否有 RC 之后合并的其他修复。常见 cherry-pick 原因CRAN 检查失败修复、第 9 步的 NEWS 更新、关键 bug 修复。对每个待处理 PR 获取 merge commit SHAgh pr view PR_NUMBER --repo apache/arrow --json mergeCommit,title --jq {sha: .mergeCommit.oid, title: .title}向用户展示提交清单并确认后逐个 cherry-pickgit cherry-pick commit-sha git push upstream maint-VERSION-r # 由用户执行3.2 创建 Crossbow 验证 PR步骤 11Crossbow 是 Apache Arrow 的跨平台构建/测试调度系统。创建一个 draft PR让所有 R 相关 crossbow 任务针对 CRAN 发布分支运行gh pr create --repo apache/arrow \ --base maint-VERSION \ --head maint-VERSION-r \ --title WIP: [R] Verify CRAN release VERSION \ --body Do not merge: Running R crossbow jobs against the CRAN release branch. \ --draft随后添加评论触发 crossbowgh pr comment PR_NUMBER --repo apache/arrow --body github-actions crossbow submit --group r这里的--group r对应 dev/tasks/tasks.yml 中的r分组test-r-*、r-binary-packages、r-recheck-most。将 PR 链接加入追踪 Issue 以便监控所有 crossbow 任务通过之前不得提交 CRAN。四、构建、校验与多平台验证步骤 12–164.1 本地构建与检查包步骤 12确保在maint-VERSION-r分支且工作区干净git fetch upstream git checkout maint-VERSION-r git clean -f -d关键点检查ARROW_HOME环境变量是否设置。若已设置必须unset ARROW_HOME使构建使用捆绑的 C 版本而非外部安装的 Arrow C——这是保证包自洽的核心约束PACKAGING.md 也强调 configure 脚本可用的 Arrow C 版本必须与 vendored 进 R 包的版本一致。echo ARROW_HOME${ARROW_HOME:-not set} unset ARROW_HOME cd r make buildmake build实际由 r/Makefile 定义展开后依次执行clean、doc、sync-cpp和R CMD build清理旧产物、用 roxygen2 重新生成文档、同步 C 源文件sync-cpp会把 cpp/ 目录同步到tools/cpp/并复制 NOTICE/LICENSE见 Makefile 第 43-49 行注释、最终构建 tarball。构建后检查文档变更并提交git status git add r/man/ r/inst/NOTICE.txt git commit -m [R] Update generated documentation随后运行检查生成物为arrow_VERSION.tar.gzdevtools::check_built(arrow_VERSION.tar.gz)4.2 等待发布投票步骤 13检查 Apache Arrow 发布投票是否通过。若步骤 2 是从最终apache-arrow-VERSION标签创建的分支投票已通过本步骤为 no-op。4.3 更新校验和步骤 14这是 {arrow} R 包区别于普通 R 包的关键机制。预编译二进制libarrow的 SHA512 校验和从 ASF artifactory 下载供安装时校验下载的二进制。运行前先向用户确认 libarrow 版本通常与发布版本一致cd r Rscript tools/update-checksums.R LIBARROW_VERSION git add -f tools/checksums/ git commit -m [CRAN] Add checksums从 r/tools/update-checksums.R 源码可见其工作原理从 dev/tasks/tasks.yml 中 grep 出所有r-libarrow-*.zip二进制路径用{no_rc_r_version}占位符替换为实际版本对每个路径构造 GitHub Release 下载 URLhttps://github.com/apache/arrow/releases/download/apache-arrow-VERSION/path.sha512并下载.sha512文件到tools/checksums/目录镜像 artifactory 的目录结构对 Windows 平台路径特殊处理用sedmacOS 上为gsed把 UNIX 风格换行转成 Windows 风格避免 msys2 的sha512sum报错源码第 68-75 行。这些 checksum 文件随后由 r/tools/nixlibs.R 在安装时读取并校验下载的二进制源码注释明确 uses these files to validate the downloaded binaries when installing the package确保用户安装的预编译 libarrow 与官方发布产物一致。4.4 重建包步骤 15加入 checksums 后重建 tarballcd r make build git status # 检查重建后是否有新文档变更提交任何变更并由用户推送。4.5 检查二进制分发步骤 16验证包在不同平台与预编译 Arrow C 二进制配合工作16.1 Windowswin-builder上传r/arrow_VERSION.tar.gz到 win-builder.r-project.org仅 r-devel。结果会邮件通知包维护者 JonJonathan Keane见 r/DESCRIPTION 中role c(aut, cre)需等其确认检查干净——无 ERROR、WARNING 或意外 NOTE体积 NOTE 属预期16.2 macOS Builder上传到 mac.r-project.org/macbuilder检查结果链接16.3 Ubuntu 二进制安装测试验证安装走托管二进制而非源码编译install.packages(r/arrow_VERSION.tar.gz, repos NULL)16.4 最终本地检查再跑一次devtools::check_built(r/arrow_VERSION.tar.gz)。五、提交 CRAN 与发布后收尾步骤 17–215.1 提交 CRAN步骤 17上传r/arrow_VERSION.tar.gz到 CRAN 提交页面xmpalantir.wu.ac.at/cransubmit并确认提交邮件到达PACKAGING.md 明确此步必须由当前包维护者执行。5.2 打 r-universe 标签步骤 18CRAN 接受后为 r-universe 自动构建打标签r-universe 是 R 生态的持续构建平台靠该标签触发 {arrow} 的自动构建git tag -f r-universe-release maint-VERSION-r git push upstream r-universe-release --force5.3 更新向后兼容矩阵步骤 19在 dev/tasks/r/github.linux.arrow.version.back.compat.yml 的 matrix 中添加上一版本的新行并创建 PR 到 main。从该文件可见其机制write-files作业用当前 R 包写入 parquet 文件read-files作业则用矩阵中每个历史版本当前覆盖 6.0.1 到 24.0.0 共 20 个版本每行还配对对应时代的 R 版本读取这些文件验证新版本写的文件能被旧版本读取。5.4 等待 CRAN 二进制步骤 20监控 CRAN 包页面直至 CRAN 托管的二进制反映新版本。5.5 社交媒体内容步骤 21仅主版本主版本major release需准备社媒发布内容格式为一系列帖子toots开场帖宣布 {arrow} 发布并给出新特性概览每个主要用户可见特性一条帖子附 carbon.now.sh 生成的代码截图跳过小修复与 CI/内部变更贡献者统计总贡献者数、仅 C、仅 R、两者都参与、首次贡献者。统计脚本位于 r/tools/contributor_stats.R在仓库根目录执行source(r/tools/contributor_stats.R) release_contributor_stats(apache-arrow-PREVIOUS_VERSION, apache-arrow-VERSION)该脚本通过 git log 分析两个发布标签之间的提交release_contributor_stats()返回 total、cpp_only、r_only、both、first_timers、first_timers_r 六项统计源码第 94-110 行print_new_contributors()则用集合差集setdiff找出给定范围内的首次贡献者源码第 75-85 行。六、版本特定处理与清单复审步骤 22–256.1 补丁版本更新版本号步骤 22仅补丁版本如 X.Y.1需要更新三处版本号ci/scripts/PKGBUILDr/DESCRIPTIONr/NEWS.md6.2 CRAN-only 版本更新文档步骤 23仅当发布是 CRAN-only无对应 Arrow 主发布时执行。重建新闻页并提交到 docs 站点arrow-site 仓库的asf-site分支必要时同步更新r/pkgdown/assets/versions.json中的版本号pkgdown::build_news(./r)6.3 检查 C 更新步骤 24审查本次发布的 C 变更为需要 R 绑定bindings的项创建 GitHub Issuegit log --oneline apache-arrow-PREVIOUS_VERSION..apache-arrow-VERSION -- cpp/ | head -506.4 复审清单步骤 25根据本次发布遇到的问题复审并更新 r/PACKAGING.md 这份打包清单模板使其持续反映最新流程。七、流程关键要点总结分支纪律maint-VERSION-r是唯一发布分支最终标签存在则绝不从 RC 分支所有 push 由用户执行版本一致性发布构建必须 unsetARROW_HOME使用捆绑 C避免与外部 C 版本错配校验和先行checksums 必须在构建 tarball之前加入步骤 14 先于 15否则提交的包不含校验文件安装时 r/tools/nixlibs.R 会据此校验预编译二进制三重验证本地devtools::check_built、Crossbow 全 R 任务、win-builder/macOS builder/Ubuntu 二进制安装测试共同构成发布质量防线发布后闭环r-universe 标签、向后兼容矩阵、CRAN 二进制监控、社媒内容、版本号同步一个都不能少。该技能文档本身位于仓库 .claude/skills/r-cran-release/SKILL.md设计为 Claude Code 技能使用——发布维护者可在流程开始时让技能打印完整清单逐步确认执行。而 r/PACKAGING.md 作为精简版清单模板两者互为补充共同构成了 {arrow} R 包稳定、可复现、可审计的 CRAN 发布体系。【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考