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 or
authors (year) (see )
authors (year)
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: ![]()
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 入門編輯提供
