r-cran-extrachecks

CRAN 追加チェック

CRAN のレビュアーが求める一般的な個別要件のうち、devtools::check() では検出できないものを体系的に確認し、R パッケージ開発者が CRAN への提出に備えられるよう支援します。

ワークフロー

1. 初期評価：初回提出か再提出かをユーザーに確認します
2. 標準チェックリストの実施：各項目を順に確認します（下記参照）
3. 問題の特定：ファイルを確認しながら、具体的な問題を記録します
4. 修正案の提示：見つかった問題ごとに、具体的な変更を提案します
5. 変更の実施：ユーザーの承認を得てから編集します
6. 検証：すべての変更が完了したことを確認します

CRAN 提出準備の標準チェックリスト

以下の項目を順に確認します。

1. NEWS.md を作成する：まだ存在しない場合は usethis::use_news_md() を実行します
2. cran-comments.md を作成する：まだ存在しない場合は usethis::use_cran_comments() を実行します
3. README を確認する：
   • パッケージが CRAN に受理された時点で有効なインストール手順が記載されていることを確認します（通常は install.packages("pkgname") です）。
   • 相対リンクが含まれていないことを確認します。GitHub では機能しますが、CRAN では指摘されます。パッケージドキュメントへの完全な URL を使用するか、リンクを削除してください。
   • README でパッケージの目的と機能が明確に説明されていますか？
   • 重要：README.Rmd が存在する場合は、README.Rmd のみを編集してください（README.md は上書きされます）。その後、devtools::build_readme() を実行して README.md を再生成します。
4. DESCRIPTION を校正する：Title: フィールドと Description: フィールドを注意深く確認します（詳しい説明は下記を参照）。
5. 関数のドキュメントを確認する：エクスポートされるすべての関数に @return と @examples があることを確認します（詳しい説明は下記を参照）。#' @export のみでドキュメント化された S3 メソッドは .Rd ファイルを生成しないため、いずれのタグも必須ではない点に注意してください。
6. 著作権者を確認する：Authors@R: に [cph] ロールを持つ著作権者が含まれていることを確認します。
7. 同梱ファイルのライセンスを確認する：サードパーティ製ファイルが含まれている場合、そのライセンスを確認します。
8. URL を確認する：urlchecker::url_check() を使用し、問題があれば修正します。

CRAN の詳細チェック

ドキュメント要件

戻り値のドキュメント化（厳格に適用）

CRAN では現在、エクスポートされたすべての関数に @return によるドキュメント化が厳格に求められています。roxygen2 タグ @return を使って、関数が返す値を記述してください。

• @keywords internal が付いた関数にも必要です
• 関数が何も返さない場合にも必要です。その場合は @return None などと記述してください
• エクスポートされたすべての関数に記述してください

このルールは .Rd ファイルがある関数にのみ適用されます。roxygen2 は、ブロックにドキュメントの内容（タイトルまたは説明）がある場合にのみ .Rd ファイルを作成します。#' @export だけを含むブロックは、関数を NAMESPACE に追加しますが、.Rd ファイルは生成しません。そのため、CRAN のドキュメントチェックの対象となるものはありません。これは S3 メソッドで一般的なパターンです。

#' @export
print.my_class <- function(x, ...) {
  cat("my_class object\n")
  invisible(x)
}

このようなメソッドには @return や @examples は不要であり、R CMD check でもドキュメント不足として指摘されません（登録済みの S3 メソッドは、ドキュメント化されていないオブジェクトのチェック対象から除外されます）。

• この適用除外は、ブロックに @export（または @exportS3Method）以外が含まれていない場合に限られます。タイトル、@param、@rdname、@describeIn、その他のドキュメントを追加すると、roxygen2 は .Rd ファイルを生成するため、その関数は @return を含むすべてのドキュメント要件を満たす必要があります。
• これらを S3 の ジェネリック 自体（例：my_print <- function(x, ...) UseMethod("my_print")）と混同しないでください。新たにエクスポートされたジェネリックは、ドキュメントが必要な通常のエクスポート関数であるため、引き続き @return と @examples が必要です。
• @rdname または @describeIn を使ってジェネリックと同じページを共有するメソッドには、ジェネリックと同じルールが適用されます。必要なタグはメソッドごとではなく、統合された .Rd に一度記述してください。

例：

# Missing @return - WILL BE REJECTED
#' Calculate sum
#' @export
my_sum <- function(x, y) {
  x + y
}

# Correct - includes @return
#' Calculate sum
#' @param x First number
#' @param y Second number
#' @return A numeric value
#' @export
my_sum <- function(x, y) {
  x + y
}

# For functions with no return value
#' Print message
#' @param msg Message to print
#' @return None, called for side effects
#' @export
print_msg <- function(msg) {
  cat(msg, "\n")
}

エクスポートされた関数の例

エクスポートされた関数に意味のある戻り値がある場合、ほぼ確実に @examples セクションが必要です。roxygen2 タグ @examples を使ってください。

• @keywords internal が付いた関数にも必要です
• ディレクトリの作成など、副作用のみを目的とする関数には例外があります
• 例は実行可能でなければなりません
• @export だけを含む roxygen ブロックを持つ S3 メソッドには .Rd ファイルがないため、例は不要です（上記を参照）

エクスポートされていない関数の例

エクスポートされていない関数の roxygen 例を書く場合は、次のいずれかを行ってください。

1. ::: 表記で呼び出します：pkg:::my_fun()
2. @noRd タグを使って .Rd ファイルの作成を抑制します

\dontrun{} の使用は必要最小限に

\dontrun{} は、追加ソフトウェアや API キーがないなど、例を本当に実行できない場合にのみ使用してください。

• エラーを示す場合は、代わりに呼び出しを try() で囲みます
• if () ブロックで、カスタム述語（例：googlesheets4::sheets_has_token()）を使うことを検討してください
• 条件として interactive() を使える場合もあります
• 長時間かかる例（5 秒超）には \donttest{} を使用できます

例のコードをコメントアウトしない

# BAD - Will be rejected
#' @examples
#' # my_function(x)  # Don't do this!

CRAN のガイダンス：「例やコードの行をコメントアウトしてはいけません。理想的には、定期的に実行して検証できる、小さな例を見つけてください。」

推奨パッケージが必要な例のガード

推奨パッケージが必要な例のセクション全体には @examplesIf を使用してください。

#' @examplesIf rlang::is_installed("dplyr")
#' library(dplyr)
#' my_data %>% my_function()

例の個別のコードブロックには、次のようにします。

#' @examples
#' if (rlang::is_installed("dplyr")) {
#'   library(dplyr)
#'   my_data %>% my_function()
#' }

DESCRIPTION の Title フィールド

CRAN は Title の要件を厳格に適用します。

タイトルケースを使用する

'a' や 'the' のような冠詞を除き、すべての単語を大文字で始めてください。書式の調整には tools::toTitleCase() を使用できます。

重複を避ける

次の一般的な表現は指摘の対象になります。

• "A Toolkit for" → 削除してください
• "Tools for" → 削除してください
• "for R" → 削除してください

例：

# BAD
Title: A Toolkit for the Construction of Modeling Packages for R

# GOOD
Title: Construct Modeling Packages

# BAD
Title: Command Argument Parsing for R

# GOOD
Title: Command Argument Parsing

ソフトウェア名／パッケージ名を引用符で囲む

すべてのソフトウェア名と R パッケージ名を単一引用符で囲んでください。

# GOOD
Title: Interface to 'Tiingo' Stock Price API

文字数制限

タイトルは 65 文字未満にしてください。

DESCRIPTION Description フィールド

禁止されている語句で始めないでください

CRAN は、次の語句で始まる説明を拒否します。

• "This package"
• パッケージ名
• "Functions for"

# BAD
Description: This package provides functions for rendering slides.
Description: Functions for rendering slides to different formats.

# GOOD
Description: Render slides to different formats including HTML and PDF.

3～4文に拡充してください

1文だけの説明では不十分です。次の内容を含む、より詳しい説明を記載してください。

• パッケージの機能
• 役立つ理由
• 解決に役立つ問題の種類

# BAD (too short)
Description: Render slides to different formats.

# GOOD
Description: Render slides to different formats including HTML and PDF.
    Supports custom themes and progressive disclosure patterns. Integrates
    with 'reveal.js' for interactive presentations. Designed for technical
    presentations and teaching materials.

ソフトウェア名は引用符で囲み、関数名は囲まないでください

# BAD
Description: Uses 'case_when()' to process data.

# GOOD
Description: Uses case_when() to process data with 'dplyr'.

ソフトウェア名、パッケージ名、API 名は（'R' を含め）シングルクォートで囲みます。関数名は囲みません。

すべての頭字語を展開してください

すべての頭字語は、初出時に正式名称を記載する必要があります。

# BAD
Description: Implements X-SAMPA processing.

# GOOD
Description: Implements Extended Speech Assessment Methods Phonetic
    Alphabet (X-SAMPA) processing.

二重引用符は出版物のタイトルにのみ使用してください

二重引用符は出版物のタイトルにのみ使用し、語句や強調表現には使わないでください。

# BAD
Description: Handles dates like "the first Monday of December".

# GOOD
Description: Handles dates like the first Monday of December.

URL とリンクの検証

すべての URL で HTTPS を使用してください

CRAN では、すべての URL に https:// プロトコルを使用する必要があります。HTTP リンクは拒否されます。

# BAD
URL: http://paleobiodb.org/

# GOOD
URL: https://paleobiodb.org/

リダイレクトする URL は使用しないでください

CRAN は、別の場所にリダイレクトする URL を拒否します。拒否例：

Found the following (possibly) invalid URLs:
URL: https://h3geo.org/docs/core-library/coordsystems#faceijk-coordinates
     (moved to https://h3geo.org/docs/core-library/coordsystems/)

urlchecker パッケージを使用してください

# Find redirecting URLs
urlchecker::url_check()

# Automatically update to final destinations
urlchecker::url_update()

公開後に利用可能になる URL は無視してください

現在は解決されないものの、パッケージが CRAN で公開されると利用可能になる URL があります。これらは変更しないでください。

• CRAN バッジ URL（例：https://cran.r-project.org/package=pkgname）
• CRAN ステータスバッジ（例：https://www.r-pkg.org/badges/version/pkgname）
• CRAN チェック結果（例：https://cranchecks.info/badges/pkgname）
• リリース後にデプロイされる、r-universe または pkgdown サイト上のパッケージドキュメント URL

urlchecker::url_check() がこれらの URL を警告しても、そのままにしてください。これらは、パッケージが CRAN に登録されると機能する予定の URL です。

無効なファイル URI がないか確認してください

README の相対リンク先は、パッケージのビルド後も存在している必要があります。よくある問題：

Found the following (possibly) invalid file URI:
     URI: CODE_OF_CONDUCT.md
       From: README.md

これは、ファイルが .Rbuildignore に含まれている場合に発生します。解決策：

1. ファイルを .Rbuildignore から削除する
2. 相対リンクを含まないセクションを生成する usethis::use_code_of_conduct() を使用する

管理上の要件

著作権者のロール

作成者が自分ひとりの場合でも、必ず Authors フィールドに [cph] ロールを追加してください。

# Required
Authors@R: person("John", "Doe", role = c("aut", "cre", "cph"))

Posit がサポートするパッケージ

Posit 関連の GitHub 組織（posit-dev、rstudio、r-lib、tidyverse、tidymodels）に属するパッケージ、または @posit.co のメールアドレスを持つ人がメンテナンスするパッケージでは、Posit Software, PBC を著作権者および資金提供者として記載してください。

Authors@R: c(
  person("Jane", "Doe", role = c("aut", "cre"),
         email = "[email protected]"),
  person("Posit Software, PBC", role = c("cph", "fnd"),
         comment = c(ROR = "03wc8by49"))
)

LICENSE の年

LICENSE の年を、今回の申請年に更新してください。

# If LICENSE shows 2024 but submitting in 2026
# Update: 2024 → 2026

メソッドに関する参考文献

CRAN から次のように求められる場合があります。

パッケージ内のメソッドを説明する参考文献がある場合は、Description フィールドに追加してください...

参考文献がない場合は、その旨をメールで説明してください。cran-comments.md にあらかじめ注記を追加することも検討してください。

## Method References

There are no published references describing the methods in this package.
The package implements original functionality for [brief description].

確認すべき主要ファイル

次のファイルを順に確認してください。

• DESCRIPTION：タイトル、Description、Authors@R、URL、ライセンスの年
• R/*.R：関数ドキュメント（@return、@examples、@examplesIf、@noRd）
• README.Rmd（存在する場合）：このファイルを編集して（README.md ではなく）、その後 devtools::build_readme() を実行する
• README.md：インストール手順、相対リンク、URL を確認する。README.Rmd が存在しない場合に限り、直接編集する
• cran-comments.md：レビュアー向けの事前注記
• NEWS.md：今回のリリースに関するバージョン情報
• .Rbuildignore：README で参照されているファイル

よくある修正パターン

DESCRIPTION の Title：

# Before
Title: A Toolkit for the Construction of Modeling Packages for R

# After
Title: Construct Modeling Packages

DESCRIPTION の Description：

# Before
Description: This package provides functions for rendering slides.

# After
Description: Render slides to different formats including HTML and PDF.
    Supports custom themes and progressive disclosure. Integrates with
    'reveal.js' for interactive presentations.

関数ドキュメント：

# Before - Missing @return
#' Calculate total
#' @param x Values
#' @export
calc_total <- function(x) sum(x)

# After - Complete documentation
#' Calculate total
#' @param x Numeric values to sum
#' @return A numeric value representing the sum
#' @examples
#' calc_total(1:10)
#' @export
calc_total <- function(x) sum(x)

便利なツール

• tools::toTitleCase() - タイトルを適切な大文字・小文字表記に整えます
• urlchecker::url_check() - 問題のある URL を見つけます
• urlchecker::url_update() - リダイレクトする URL を修正します
• usethis::use_news_md() - NEWS.md を作成します
• usethis::use_cran_comments() - cran-comments.md を作成します
• devtools::build_readme() - README.Rmd から README.md を再生成します
• usethis::use_code_of_conduct() - 相対リンクなしで CoC を追加します
• usethis::use_build_ignore() - R パッケージのビルドでファイルを無視します
• usethis::use_package() - DESCRIPTION にパッケージ依存関係を追加します
• usethis::use_tidy_description() - DESCRIPTION の書式を整えます

最終確認チェックリスト

提出前に見落としがないことを確認するため、このチェックリストを使用してください。

ファイルと構成

• NEWS.md が存在し、このバージョンでの変更が記載されている
• cran-comments.md が存在し、提出時の注記が記載されている
• README.Rmd が存在する場合は、README.md ではなく README.Rmd を編集し、devtools::build_readme() を実行した
• README に有効なインストール手順（install.packages("pkgname")）が記載されている
• README に相対リンクがない（すべてのリンクが完全な URL であるか、削除されている）

DESCRIPTION ファイル

• Title: がタイトルケースになっている
• Title: に冗長な表現（「A Toolkit for」、「Tools for」、「for R」）が含まれていない
• Title: のすべてのソフトウェア名／パッケージ名が一重引用符で囲まれている
• Title: が 65 文字未満である
• Description: が「This package」、パッケージ名、または「Functions for」で始まっていない
• Description: が目的と有用性を説明する 3～4 文で構成されている
• Description: のソフトウェア名／パッケージ名／API 名（「R」を含む）が引用符で囲まれているが、関数名は囲まれていない
• Description: ですべての頭字語が初出時に展開されている
• Description: で二重引用符が使われているのは出版物のタイトルのみである
• Authors@R: に [cph] ロールを持つ著作権者が含まれている
• Posit パッケージの場合：person("Posit Software, PBC", role = c("cph", "fnd"), comment = c(ROR = "03wc8by49")) が含まれている
• LICENSE の年が現在の提出年と一致している

関数のドキュメント

• .Rd ファイルを持つすべてのエクスポート関数に @return のドキュメントがある
• 意味のある戻り値を持つ、ドキュメント化されたすべてのエクスポート関数に @examples がある
• @export のみの roxygen ブロックを持つ S3 メソッドは、適切に例外扱いされている（.Rd ファイルは不要で、@return／@examples も不要）
• パッケージが追加する S3 ジェネリックには、通常のエクスポート関数と同様に完全なドキュメント（@return、@examples）がある
• コメントアウトされたコードを使う例のセクションがない
• 本当に必要な場合を除き、例で \dontrun{} を使用していない
• 提案パッケージを必要とする例では、@examplesIf または if ガードを使用している
• 例を含む非エクスポート関数では、::: 記法または @noRd を使用している

URL とリンク

• urlchecker::url_check() を実行した
• すべての URL が https プロトコルを使用している（http リンクがない）
• リダイレクトする URL がない（CRAN バッジなど、将来の実現を目指す URL を除く）
• 将来の実現を目指す URL（CRAN バッジなど）はそのままにしてある
• README に .Rbuildignore ファイルを参照する相対リンクがない

任意ですが推奨

• メソッド参照に懸念がある場合は、予防的な注記を cran-comments.md に追加した
• サードパーティのファイルを含める場合は、同梱ファイルのライセンスを確認した