prepare for cran
1.0.0
パッケージを CRAN に送信する前に確認する必要がある事項をまとめたオープンで協力的なリスト。
このリポジトリは、CRAN の提出プロセス、特にこのスレッドに関する Twitter でのやり取りを経て誕生しました。
ここでの考え方は、CRAN が耐性を持たせるためにメンテナーに変更を求める一般的な (または珍しい) ものをリストすることで、CRAN がより簡単に作業できるようにするための基本ルールを収集することです。
CRAN の提出は厳格で、CRAN チームは自発的に作業を行っており、保守する必要のあるパッケージは 15,000 個以上あります。
私たちは、パッケージ開発と CRAN 提出に関するいくつかのグッド プラクティスを提供することで、パッケージ作成者が CRAN チームに依頼される前にこれらの問題に取り組むことができるように支援できると信じています。したがって、DESCRIPTION のタイトルに「R が含まれる」という理由で CRAN チームが電子メールを送信しないようにすることで、全員の時間を節約できます。なぜなら、ピーター・ダルガードが次のように述べているからです。
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 を使用している場合は、[Build] > [Check] をクリックすることもできます。
これらの警告や注意が正当でないと思われる場合は、送信時にコメントを残して、正当でないと思われる理由を明記してください。
パッケージ内で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用の「NOTE」が自動的に表示されることに注意してください。
新しいバージョンの CRAN 提出は、あまり頻繁に行わないでください。 30 日に 1 回が一般的なルールのようです (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...」やパッケージ名で始めてはなりません。
別のパッケージ、記事/書籍、Web サイト/API を引用する場合は、その名前を一重引用符'で囲んでください。また、パッケージ名では大文字と小文字が区別されます。例: 「光沢のある」 --> 「光沢のある」。
説明の中で関数名を使用する場合は、必ず括弧で囲んでください。例: 「'base' パッケージの cat() のドロップイン置換を提供します。」
API への R インターフェイスを作成する場合、または出版された論文/書籍からアルゴリズムを実装する場合は、出版物への参照を DOI、ISBN、または同様の正規リンク、または API または論文の URL として「説明」フィールドに追加します。 DESCRIPTION ファイルの。
「説明」内の記事または Web サイトにリンクする場合は、山かっこを使用して自動リンクしてください。
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) {}の間で例をラップしないでください。
dontrun{}ユーザーがサンプルを実際に実行できない場合にのみ使用してください (追加のソフトウェアが不足している、API キーが不足しているなどの理由で)。 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}の README の行動規範を参照)
Code is distributed under the [GPL-3.0-License](https://USERNAME.github.io/MY_PACKAGE/LICENSE.html).
ライセンスのために外部リソースを指定することもできます ( {golem} README を参照)。
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 と通信するためのテンプレートである cran-comments.md を作成します。目的は、さまざまなオペレーティング システムでパッケージをチェックするために実行した手順を明確に伝えることです。他のパッケージで使用されているパッケージに更新を送信する場合は、逆依存性チェックの結果を要約する必要もあります。
usethis::use_cran_comments(open = rlang::is_interactive())
devtools::release()を実行して、R から CRAN に自動的に送信できます。
メールボックスにリンクが届きます。このリンクをクリックしてアップロードを確認します。
パッケージによっては 1 時間から数週間かかる場合があり、手動検査が必要な場合は時間がかかる場合があります。
{cransays}でパッケージのステータスを確認できます: https://lockedata.github.io/cransays/articles/dashboard.html
CRAN 提出用のチェックリスト
CRAN リポジトリ ポリシー
R パッケージ - ハドリー・ウィカムとジェニファー・ブライアン著
R 拡張機能の作成 - 公式ドキュメント
R でのソフトウェア開発のマスタリング - Roger D. Peng、Sean Kross、Brooke Anderson 著。
優れた R パッケージを開発する方法 (オープン サイエンス用) - Maëlle Salmon 著 (チュートリアルのリストを含む)
Sinew: シンプルな R パッケージのドキュメント - Jonathan Sidi 著
rOpenSci パッケージ: 開発、メンテナンス、およびピア レビュー - rOpenSci オンボーディング エディターによる
