prepare for cran
1.0.0
在将包裹提交给 CRAN 之前必须检查的开放协作列表。
这个 repo 是在 Twitter 上就 CRAN 提交过程（尤其是这个帖子）进行交流后诞生的。
这里的想法是收集基本规则，通过列出他们要求维护者更改的常见（或不常见）内容，以帮助 CRAN 更轻松地开展工作，以便不受 CRAN 的影响。
CRAN提交严格，CRAN团队自愿做工作，有超过15K个包需要维护。
我们相信我们可以通过提供一些有关包开发和 CRAN 提交的良好实践来帮助他们，以便包作者可以在 CRAN 团队要求他们这样做之前解决这些问题。因此，我们可以通过阻止 CRAN 团队向您发送电子邮件来节省每个人的时间，因为您的描述标题中有“with R”。因为，正如彼得·达尔加德所说：
太多人没有意识到，CRAN 维护者群体一只手就能数过来，有时甚至一根手指头就能数得过来。
仍然需要添加步骤来列出自动化测试，如以下各节所述，但您可以将其添加到“dev/dev_history.R”文件中，以便在每次向 CRAN 发送内容时运行它们。
# Prepare for CRAN ----
# Update dependencies in DESCRIPTION
# install.packages('attachment', repos = 'https://thinkr-open.r-universe.dev')
attachment :: att_amend_desc()
# Check package coverage
covr :: package_coverage()
covr :: report()
# Run tests
devtools :: test()
testthat :: test_dir( " tests/testthat/ " )
# Run examples
devtools :: run_examples()
# autotest::autotest_package(test = TRUE)
# Check package as CRAN using the correct CRAN repo
withr :: with_options( list ( repos = c( CRAN = " https://cloud.r-project.org/ " )),
{ callr :: default_repos()
rcmdcheck :: rcmdcheck( args = c( " --no-manual " , " --as-cran " )) })
# devtools::check(args = c("--no-manual", "--as-cran"))
# Check content
# install.packages('checkhelper', repos = 'https://thinkr-open.r-universe.dev')
# All functions must have either `@noRd` or an `@export`.
checkhelper :: find_missing_tags()
# Check that you let the house clean after the check, examples and tests
# If you used parallel testing, you may need to avoid it for the next check with `Config/testthat/parallel: false` in DESCRIPTION
all_files_remaining <- checkhelper :: check_clean_userspace()
all_files_remaining
# If needed, set back parallel testing with `Config/testthat/parallel: true` in DESCRIPTION
# Check spelling - No typo
# usethis::use_spell_check()
spelling :: spell_check_package()
# Check URL are correct
# install.packages('urlchecker', repos = 'https://r-lib.r-universe.dev')
urlchecker :: url_check()
urlchecker :: url_update()
# check on other distributions
# _rhub v2
rhub :: rhub_setup() # Commit, push, merge
rhub :: rhub_doctor()
rhub :: rhub_platforms()
rhub :: rhub_check() # launch manually
# _win devel CRAN
devtools :: check_win_devel()
# _win release CRAN
devtools :: check_win_release()
# _macos CRAN
# Need to follow the URL proposed to see the results
devtools :: check_mac_release()
# Check reverse dependencies
# remotes::install_github("r-lib/revdepcheck")
usethis :: use_git_ignore( " revdep/ " )
usethis :: use_build_ignore( " revdep/ " )
devtools :: revdep()
library( revdepcheck )
# In another session because Rstudio interactive change your config:
id <- rstudioapi :: terminalExecute( " Rscript -e 'revdepcheck::revdep_check(num_workers = 4)' " )
rstudioapi :: terminalKill( id )
# if [Exit Code] is not 0, there is a problem !
# to see the problem: execute the command in a new terminal manually.
# See outputs now available in revdep/
revdep_details( revdep = " pkg " )
revdep_summary() # table of results by package
revdep_report()
# Clean up when on CRAN
revdep_reset()
# Update NEWS
# Bump version manually and add list of changes
# Add comments for CRAN
usethis :: use_cran_comments( open = rlang :: is_interactive())
# Upgrade version number
usethis :: use_version( which = c( " patch " , " minor " , " major " , " dev " )[ 1 ])
# Verify you're ready for release, and release
devtools :: release()devtools::check()返回 0 0 0首先要做的是运行devtools::check() ，并确保没有错误、没有警告、没有注释。
如果您在 RStudio 中，还可以单击“构建”>“检查”。
如果您认为这些警告或注释不合理，请在提交时留下评论，并说明您认为不合理的原因。
您可以在包内调用usethis::use_spell_check()来添加拼写测试。如果需要运行拼写检查，请随时调用spelling::spell_check_package() 。
{rhub} {rhub}包允许使用 GitHub Actions 在具有 CRAN 默认配置的多个平台上检查您的包。
运行rhub::rhub_setup()并按照说明进行操作。
有关{rhub}的更多信息：https://github.com/r-hub/rhub
使用 win-builder 工具或devtools::check_win_devel()测试您的包是否构建。
在此处构建并手动提交您的存档：https://mac.r-project.org/macbuilder/submit.html
请参阅 https://github.com/DavisVaughan/extrachecks
这些检查可能无法捕获 CRAN 团队将捕获的所有内容，因此以下是良好实践的列表：
请注意，如果这是您第一次提交，您将自动获得一个“注释”，表示New submission 。
CRAN 提交新版本不应过于频繁。每 30 天一次似乎是一般规则（除非您在 CRAN 团队成员反馈后重新提交）。
在 CRAN 反馈后重新提交时，请务必注明这是在反馈后重新提交，并描述您所做的事情。
如果您在 CRAN 反馈后重新提交，请在版本号的补丁部分添加 1（例如，如果您的第一次提交是 0.3.1，则您的重新提交应为 0.3.2）。
CRAN 可以拒绝DESCRIPTION中有语法错误的包。一些常见的拼写错误：
'之间（例如： Lorem-Ipsum Helper Function for 'shiny' Prototyping ）API ，而不是Api ） DESCRIPTION文件应有一个cph （版权所有者）。它可以是第一作者，也可以是作者工作的公司。
这可能不会被 CRAN 捕获，但请确保您已填写此文件中的所有内容。
在 GitHub 上的存储库标题中编写类似“R 的友好条件处理程序”或“R 的简单 Dockerfile 创建”之类的内容很诱人（而且似乎很合适）。 CRAN 团队会要求您删除它，因为它是多余的（您只处理 CRAN 上的 R 包）。
编写详细的描述字段。
标题应采用标题格式
标题中的大写和小写字母（标题大小写）
注意：这应该被 r-hub 捕获。
一个 CRAN 证明包应该有一个很长的描述，解释该包的用途、优点、新内容以及它与 CRAN 上已有的包有何不同。
标题和描述都不应以“A package...”或包的名称开头。
如果您引用另一个包、文章/书籍或网站/API，请将其名称放在单引号'之间。此外，包名称区分大小写。例如“闪亮”-->“闪亮”。
如果描述中使用了函数名称，请确保其后带有括号。例如，“为‘base’包中的 cat() 提供直接替代。”
如果您编写 API 的 R 接口或实现已发表的文章/书籍中的算法，请在“描述”字段中添加对出版物的引用作为 DOI、ISBN 或类似的规范链接，或者 API 或文章的 URL您的描述文件。
在描述中链接到文章或网站时，请使用尖括号进行自动链接。
API name <http:...> or <https:...>
authors (year) <DOI:...> (see <https://en.wikipedia.org/wiki/Digital_object_identifier> )
authors (year) <arXiv:...>
authors (year, ISBN:...)
https: 、 doi: 、 arXiv:和用于自动链接的尖括号后没有空格。
包中的所有导出函数都应该有一个@return值。如果函数不返回值，也记录下来。
如果存在带有部分文档（标题和.或@param ）的内部函数（未导出），请使用标签#' @noRd以避免生成文档。
您可以使用checkhelper::find_missing_tags()来帮助您查找文档中缺少的标签。从 GitHub 安装 {checkhelper}：https://github.com/ThinkR-open/checkhelper
dontrun{}示例中的dontrun{}元素实际上可能由 CRAN 运行。如果您不想运行示例，请将其包含在if (interactive()) {}之间。不要将示例包含在if (FALSE) {}之间。
仅当用户确实无法执行示例时（例如，由于缺少附加软件、缺少 API 密钥等），才应使用dontrun{} 。这就是为什么在dontrun{}中包装示例会添加注释（“# Not run:”）作为对用户的警告。
如果示例可以在 < 5 秒内执行，则将其解开，或者将dontrun{}替换为donttest{} 。
请注意， donttest{}将由check()运行，也可能由 CRAN 运行...
如果您的文档中有一些 URL，请务必：
您可以使用 {urlchecker} 来帮助：https://github.com/r-lib/urlchecker
README.md 、 NEWS.md 、 LICENSE.md ）例如，如果您有指向README.md中的NEWS.md或CODE_OF_CONDUCT.md等文件的相对 URI：
Code is distributed under the [GPL-3.0-License](LICENSE.md).
他们会抛出以下 CRAN 错误：
Found the following (possibly) invalid file URIs:
URI: LICENSE.md
From: README.md
将相对链接更改为指向 {pkgdown} 网站的绝对链接即可解决问题（请参阅{dplyr}自述文件中的行为准则）
Code is distributed under the [GPL-3.0-License](https://USERNAME.github.io/MY_PACKAGE/LICENSE.html).
指向外部资源以获得许可证也是可行的（请参阅{golem}自述文件）：
Code is distributed under the [GPL-3.0-License](https://www.gnu.org/licenses/gpl-3.0.en.html).
如果您有每个运行时间超过几秒的示例，请将它们包装在donttest{}中，不要使用dontrun{} 。
#' @example
#' donttest{x <- foo(y)}
文档中不应有空标签（对于需要值的标签）。 devtools::check()检测空的@param和@return输出。
同样，您可以使用checkhelper::find_missing_tags()来帮助您查找文档中缺少的标签。从 GitHub 安装 {checkhelper}：https://github.com/ThinkR-open/checkhelper
如果你在 CRAN 上遇到这个问题
Warning: <img> attribute "align" not allowed for HTML5
您可以按照以下步骤操作：
https://github.com/DavisVaughan/extrachecks-html5
CRAN 存储库政策状态：
包不应写入用户的主文件空间（包括剪贴板），也不应写入文件系统上除 R 会话临时目录之外的任何其他位置（或在安装期间写入 TMPDIR 指向的位置：并且应清除此类使用）。不允许安装到系统的 R 安装中（例如，将脚本安装到其 bin 目录中）。
您可能不知道什么是临时目录/文件或如何使用它们。这些临时文件是为当前 R 会话创建的，并在会话关闭时删除。
您可以使用以下方法创建它们：
file <- tempfile()
添加扩展名
tmp <- tempfile(fileext = ".csv")
tmp
[1] "/var/folders/lz/thnnmbpd1rz0h1tmyzgg0mh00000gn/T//Rtmpnh8kAc/fileae1e28878432.csv"
所以你可以：
write.csv(iris, file = tmp)
请参阅：为临时文件创建名称
如果包依赖于您的包，您应该对devtools::revdep()列出的包运行反向依赖项测试。
使用 {revdepcheck}：https://github.com/r-lib/revdepcheck
# Check reverse dependencies
# remotes::install_github("r-lib/revdepcheck")
usethis :: use_git_ignore( " revdep/ " )
usethis :: use_build_ignore( " revdep/ " )
devtools :: revdep()
library( revdepcheck )
# In another session
id <- rstudioapi :: terminalExecute( " Rscript -e 'revdepcheck::revdep_check(num_workers = 4)' " )
rstudioapi :: terminalKill( id )
# See outputs
revdep_details( revdep = " pkg " )
revdep_summary() # table of results by package
revdep_report() # in revdep/
# Clean up when on CRAN
revdep_reset()创建 cran-comments.md，这是提交包时与 CRAN 通信的模板。目标是清楚地传达您在各种操作系统上检查软件包所采取的步骤。如果您要提交对其他包使用的包的更新，您还需要总结反向依赖性检查的结果。
usethis::use_cran_comments(open = rlang::is_interactive())
您可以运行devtools::release()自动从 R 发送到 CRAN。
您将在邮箱中收到一个链接。单击此链接确认上传。
根据包裹的不同，可能需要一小时到几周的时间，如果需要人工检查，可能需要一些时间。
您可以使用{cransays}查看包裹的状态：https://lockedata.github.io/cransays/articles/dashboard.html
CRAN 提交清单
CRAN 存储库政策
R 包 - 由 Hadley Wickham 和 Jennifer Bryan 编写
编写 R 扩展 - 官方文档
掌握 R 语言软件开发 - 作者：Roger D. Peng、Sean Kross 和 Brooke Anderson。
如何开发良好的 R 包（用于开放科学）- 作者：Maëlle Salmon（包括教程列表）
Sinew：简单的 R 包文档 - 作者：Jonathan Sidi
rOpenSci 包：开发、维护和同行评审 - 由 rOpenSci 入门编辑提供
