cran-extrachecks

CRAN の追加チェック

devtools::check() では検出されないものの、CRAN のレビュアーが適用する一般的な臨時要件を体系的に確認し、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 があることを確認します（詳しいガイダンスは以下を参照してください）
6. 著作権者の確認：Authors@R: に [cph] 役割の著作権者が含まれていることを確認します
7. 同梱ファイルのライセンス確認：含まれているサードパーティ製ファイルのライセンスを確認します
8. URL チェックの実行：urlchecker::url_check() を使用し、問題を修正します

CRAN の詳細チェック

ドキュメントの要件

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

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

• @keywords internal とマークされた関数にも必要です
• 関数が何も返さない場合にも必要です。「@return None」などと記述してください
• エクスポートされたすべての関数に記載する必要があります

例：

# 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 とマークされた関数にも必要です
• ディレクトリの作成など、副作用のみを目的とする関数には例外があります
• 例は実行可能でなければなりません

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

エクスポートされていない関数の roxygen 例を書く場合は、次のいずれかを行う必要があります。

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

\dontrun{} の使用は控えめに

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

• エラーを示す場合は、代わりに呼び出しを try() で囲みます
• カスタム述語（例：googlesheets4::sheets_has_token()）を使い、if () ブロックで条件を指定することを検討します
• 条件として 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() を使用する

管理上の要件

著作権者のロール

著者が自分 1 人だけの場合でも、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：Title、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 の年が現在の提出年と一致している

関数のドキュメント

• エクスポートされるすべての関数に @return のドキュメントがある
• 意味のある戻り値を持つエクスポート関数すべてに @examples がある
• コメントアウトされたコードを使っている例のセクションがない
• 本当に必要な場合を除き、例で \dontrun{} を使っていない
• 推奨パッケージが必要な例では、@examplesIf または if ガードを使用している
• 例を含む非エクスポート関数では、::: 記法または @noRd を使用している

URL とリンク

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

任意（推奨）

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