Agent-almanac submit-to-cran

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/zh-CN/skills/submit-to-cran" ~/.claude/skills/pjt222-agent-almanac-submit-to-cran-9de4ac && rm -rf "$T"

manifest: i18n/zh-CN/skills/submit-to-cran/SKILL.md

source content

提交至 CRAN

执行完整的 CRAN 提交工作流，从预检查到正式提交。

适用场景

软件包已准备好首次发布至 CRAN
提交已有 CRAN 包的更新版本
收到 CRAN 审核反馈后重新提交

输入

必需：R 包在本地
```
R CMD check
```
中通过，零错误、零警告
必需：DESCRIPTION 中已更新版本号
必需：NEWS.md 已包含本版本的变更记录
可选：CRAN 审核人员的历史意见（用于重新提交）

步骤

第 1 步：版本与 NEWS 检查

确认 DESCRIPTION 中的版本号正确：

desc::desc_get_version()

确认 NEWS.md 包含本版本的条目，条目应概括面向用户的变更内容。

预期结果： 版本号遵循语义化版本规范。NEWS.md 有与本版本匹配的条目。

失败处理： 使用

usethis::use_version()

（选择 "major"、"minor" 或 "patch"）更新版本号。在 NEWS.md 中添加概述面向用户变更的条目。

第 2 步：本地 R CMD Check

devtools::check()

预期结果： 0 个错误、0 个警告、0 个注记（首次提交时 1 个注记"New submission"可接受）。

失败处理： 继续之前修复所有错误和警告。查阅

<pkg>.Rcheck/00check.log

获取详情。在 cran-comments.md 中说明各项注记。

第 3 步：拼写检查

devtools::spell_check()

将合法单词添加至

inst/WORDLIST

（每行一个，按字母排序）。

预期结果： 无意外拼写错误。所有被标记的词已被更正或添加至

inst/WORDLIST

。

失败处理： 修正真正的拼写错误。对于合法的技术术语，将其添加至

inst/WORDLIST

（每行一个，按字母排序）。

第 4 步：URL 检查

urlchecker::url_check()

预期结果： 所有 URL 返回 HTTP 200。无失效或被重定向的链接。

失败处理： 替换失效的 URL。对 DOI 链接使用

\doi{}

而非裸 URL。删除指向已不存在资源的链接。

第 5 步：Win-Builder 检查

devtools::check_win_devel()
devtools::check_win_release()

等待邮件返回结果（通常需 15–30 分钟）。

预期结果： Win-builder release 和 devel 均为 0 个错误、0 个警告。结果在 15–30 分钟内通过邮件送达。

失败处理： 处理平台特定问题。常见原因：不同编译器警告、缺少系统依赖、路径分隔符差异。在本地修复后重新提交至 Win-builder。

第 6 步：R-hub 检查

rhub::rhub_check()

此步骤在多个平台（Ubuntu、Windows、macOS）上进行检查。

预期结果： 所有平台通过，0 个错误、0 个警告。

失败处理： 若某特定平台失败，查看 R-hub 构建日志中的平台特定错误。对平台相关行为使用

testthat::skip_on_os()

或条件代码。

第 7 步：准备 cran-comments.md

在包根目录创建或更新

cran-comments.md

：

## R CMD check results
0 errors | 0 warnings | 1 note

* This is a new release.

## Test environments
* local: Windows 11, R 4.5.0
* win-builder: R-release, R-devel
* R-hub: ubuntu-latest (R-release), windows-latest (R-release), macos-latest (R-release)

## Downstream dependencies
There are currently no downstream dependencies for this package.

对于更新提交，应包括：

变更概述（简要）
对此前审核人员反馈的回应
若适用，提供反向依赖检查结果

预期结果：

cran-comments.md

准确概述所有测试环境的检查结果，并对各项注记作出说明。

失败处理： 若不同平台检查结果存在差异，记录所有差异。CRAN 审核人员会对照自己的测试来核实这些信息。

第 8 步：最终预检

# 最后一次检查
devtools::check()

# 验证构建的 tarball
devtools::build()

预期结果： 最终

devtools::check()

通过且无异常。在上级目录中生成

.tar.gz

压缩包。

失败处理： 若最后时刻出现问题，修复后从第 2 步重新执行所有检查。存在已知失败时不得提交。

第 9 步：提交

devtools::release()

此命令运行交互式检查并执行提交。如实回答所有问题。

也可手动提交：访问 https://cran.r-project.org/submit.html 上传 tarball 文件。

预期结果： 几分钟内收到 CRAN 确认邮件。点击邮件中的确认链接完成提交。

失败处理： 查看邮件中的拒绝原因。常见问题：示例运行过慢、缺少

\value

标签、代码不可移植。修复问题后重新提交，并在 cran-comments.md 中说明所做更改。

第 10 步：提交后处理

获得接受后：

# 打标签创建发布版本
usethis::use_github_release()

# 切换至开发版本
usethis::use_dev_version()

预期结果： GitHub release 以已接受版本的标签创建。DESCRIPTION 已切换至开发版本（

x.y.z.9000

）。

失败处理： 若 GitHub release 创建失败，使用

gh release create

手动创建。若 CRAN 接受有延迟，等待确认邮件后再打标签。

验证清单

```
R CMD check
```
在本地机器上返回 0 个错误、0 个警告
Win-builder 通过（release + devel）
R-hub 在所有测试平台上通过
```
cran-comments.md
```
准确描述各检查结果
所有 URL 有效
无拼写错误
版本号正确且已递增
NEWS.md 已更新
DESCRIPTION 元数据完整且准确

常见问题

示例运行过慢：将耗时示例包裹在
```
\donttest{}
```
中。CRAN 执行时间限制严格。
非标准文件或目录名：避免触发 CRAN 注记的文件（检查
```
.Rbuildignore
```
）
文档缺少
\value
：所有导出函数需要
```
@return
```
标签
Vignette 构建失败：确保 vignette 能在不依赖
```
.Renviron
```
的干净环境中构建
DESCRIPTION 标题格式：必须为标题大小写（Title Case），末尾无句点，不以"A Package for..."开头
忘记反向依赖检查：对于更新提交，运行
```
revdepcheck::revdep_check()
```

示例

# 完整的提交前工作流
devtools::spell_check()
urlchecker::url_check()
devtools::check()
devtools::check_win_devel()
rhub::rhub_check()
# 等待结果...
devtools::release()