prepare for cran
1.0.0
Eine offene und gemeinschaftliche Liste von Dingen, die Sie überprüfen müssen, bevor Sie Ihr Paket an das CRAN senden.
Dieses Repo entstand nach einem Austausch auf Twitter über den CRAN-Einreichungsprozess, insbesondere diesen Thread.
Die Idee hier besteht darin, Grundregeln zu sammeln, die dem CRAN dabei helfen würden, einfacher zu arbeiten, indem allgemeine (oder ungewöhnliche) Dinge aufgelistet werden, die Betreuer ändern sollen, um CRAN-sicher zu sein.
Die CRAN-Einreichung ist streng, das CRAN-Team erledigt seine Arbeit freiwillig und es müssen mehr als 15.000 Pakete verwaltet werden.
Wir glauben, dass wir ihnen helfen können, indem wir einige bewährte Methoden zur Paketentwicklung und CRAN-Einreichung bereitstellen, damit Paketautoren an diesen Problemen arbeiten können, bevor das CRAN-Team sie dazu auffordert. Daher könnten wir allen Zeit sparen, indem wir verhindern, dass das CRAN-Team Ihnen eine E-Mail sendet, weil der Titel Ihrer BESCHREIBUNG „mit R“ enthält. Denn wie Peter Dalgaard sagte:
Allzu vielen Menschen ist nicht bewusst, dass die Gruppe der CRAN-Betreuer an einer Hand, manchmal sogar an einem Finger, abgezählt werden kann.
Es müssen noch Schritte hinzugefügt werden, um automatisierte Tests aufzulisten, wie in den folgenden Abschnitten beschrieben, aber Sie können sie zu einer „dev/dev_history.R“-Datei hinzufügen, um sie jedes Mal auszuführen, wenn Sie etwas an CRAN senden.
# 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 zurückgibt Als erstes müssen Sie devtools::check() ausführen und sicherstellen, dass kein Fehler, keine Warnung oder kein Hinweis vorliegt.
Wenn Sie sich in RStudio befinden, können Sie auch auf Erstellen > Prüfen klicken.
Wenn Sie der Meinung sind, dass diese Warnungen oder Hinweise nicht gerechtfertigt sind, hinterlassen Sie beim Absenden einen Kommentar, in dem Sie angeben, warum dies Ihrer Meinung nach nicht gerechtfertigt ist.
Sie können usethis::use_spell_check() in Ihrem Paket aufrufen, um einen Rechtschreibtest hinzuzufügen. Rufen Sie jederzeit spelling::spell_check_package() auf, wenn Sie die Rechtschreibprüfung ausführen müssen.
{rhub} Das {rhub} -Paket ermöglicht die Überprüfung Ihres Pakets auf mehreren Plattformen mit der CRAN-Standardkonfiguration mithilfe von GitHub-Aktionen.
Führen Sie rhub::rhub_setup() aus und befolgen Sie die Anweisungen.
Mehr über {rhub} : https://github.com/r-hub/rhub
Testen Sie, ob Ihr Paket mit dem Win-Builder-Tool oder mit devtools::check_win_devel() erstellt wird.
Erstellen Sie Ihr Archiv und reichen Sie es manuell hier ein: https://mac.r-project.org/macbuilder/submit.html
Siehe https://github.com/DavisVaughan/extrachecks
Diese Überprüfungen erfassen möglicherweise nicht alles, was das CRAN-Team erkennt. Daher finden Sie hier eine Liste bewährter Vorgehensweisen:
Beachten Sie, dass Sie, wenn es sich um Ihre erste Einreichung handelt, automatisch einen HINWEIS für New submission erhalten.
Die CRAN-Einreichung einer neuen Version sollte nicht zu häufig erfolgen. Ein Mal alle 30 Tage scheint die allgemeine Regel zu sein (es sei denn, Sie reichen eine erneute Einreichung nach Rückmeldung eines CRAN-Teammitglieds ein).
Stellen Sie bei der erneuten Einreichung nach einem CRAN-Feedback sicher, dass Sie angeben, dass es sich um eine erneute Einreichung nach einem Feedback handelt, und beschreiben Sie, was Sie getan haben.
Wenn Sie nach einem CRAN-Feedback erneut einreichen, fügen Sie 1 zur Patch-Komponente Ihrer Versionsnummer hinzu (z. B. wenn Ihre erste Übermittlung 0.3.1 ist, sollte Ihre erneute Übermittlung 0.3.2 sein).
CRAN kann Pakete ablehnen, die Grammatikfehler in der DESCRIPTION enthalten. Einige häufige Rechtschreibfehler:
' liegen (Beispiel: Lorem-Ipsum Helper Function for 'shiny' Prototyping )API , nicht Api ) DESCRIPTION Datei sollte einen cph (Copyright-Inhaber) haben. Dabei kann es sich entweder um den Erstautor oder um das Unternehmen handeln, bei dem der/die Autor(en) tätig ist/sind.
Dies wird vom CRAN möglicherweise nicht erkannt, aber stellen Sie sicher, dass Sie in dieser Datei alles ausgefüllt haben.
Es ist verlockend, so etwas wie „Ein benutzerfreundlicherer Bedingungshandler für R“ oder „Einfache Dockerfile-Erstellung für R“ in den Titel Ihres Repositorys auf GitHub zu schreiben (und scheint angemessen). Das CRAN-Team wird Sie bitten, dies zu entfernen, da es redundant ist (Sie haben es nur mit R-Paketen auf dem CRAN zu tun).
Schreiben Sie ein ausführliches Beschreibungsfeld.
Der Titel sollte in Groß-/Kleinschreibung erfolgen
Groß- und Kleinbuchstaben in Titeln (Titelfall)
Hinweis: Dies sollte von r-hub erfasst werden.
Ein CRAN-sicheres Paket sollte eine lange Beschreibung enthalten, die erklärt, was das Paket tut, welche Vorteile es bietet, was neu ist und wie es sich von dem unterscheidet, was bereits auf dem CRAN enthalten ist.
Weder der Titel noch die Beschreibung sollten mit „Ein Paket…“ oder mit dem Namen des Pakets beginnen.
Wenn Sie ein anderes Paket, einen Artikel/ein Buch oder eine Website/API zitieren, setzen Sie dessen Namen in einfache Anführungszeichen ' . Außerdem muss bei Paketnamen die Groß-/Kleinschreibung beachtet werden. zB 'glänzend' -> 'Glänzend'.
Wenn in Ihrer BESCHREIBUNG ein Funktionsname verwendet wird, achten Sie darauf, ihm Klammern voranzustellen. Beispiel: „Stellt einen Ersatz für cat() aus dem ‚Basis‘-Paket bereit.“
Wenn Sie eine R-Schnittstelle zu einer API schreiben oder einen Algorithmus aus einem veröffentlichten Artikel/Buch implementieren, fügen Sie im Feld „Beschreibung“ einen Verweis auf die Veröffentlichung als DOI, ISBN oder einen ähnlichen kanonischen Link oder eine URL für die API oder den Artikel hinzu Ihrer BESCHREIBUNG-Datei.
Wenn Sie in der BESCHREIBUNG auf einen Artikel oder eine Website verlinken, verwenden Sie für die automatische Verlinkung spitze Klammern.
API name or
authors (year) (see )
authors (year)
authors (year, ISBN:...)
ohne Leerzeichen nach https: , doi: , arXiv: und spitze Klammern für die automatische Verlinkung.
Alle exportierten Funktionen in Ihrem Paket sollten einen @return Wert haben. Wenn eine Funktion keinen Wert zurückgibt, dokumentieren Sie dies ebenfalls.
Wenn es eine interne Funktion (nicht exportiert) mit teilweiser Dokumentation (Titel und.oder @param ) gibt, verwenden Sie das Tag #' @noRd , um die Generierung von Dokumentation zu vermeiden.
Sie können checkhelper::find_missing_tags() verwenden, um die fehlenden Tags in Ihrer Dokumentation zu finden. Installieren Sie {checkhelper} von GitHub: https://github.com/ThinkR-open/checkhelper
dontrun{} dontrun{} -Elemente in den Beispielen könnten tatsächlich von CRAN ausgeführt werden. Wenn Sie nicht möchten, dass ein Beispiel ausgeführt wird, schließen Sie es zwischen if (interactive()) {} ein. Beispiel nicht zwischen if (FALSE) {} umbrechen.
dontrun{} sollte nur verwendet werden, wenn das Beispiel vom Benutzer tatsächlich nicht ausgeführt werden kann (z. B. wegen fehlender Zusatzsoftware, fehlender API-Schlüssel, ...). Aus diesem Grund wird beim Einschließen von Beispielen in dontrun{} der Kommentar („# Not run:“) als Warnung für den Benutzer hinzugefügt.
Entpacken Sie die Beispiele, wenn sie in < 5 Sekunden ausführbar sind, oder ersetzen Sie dontrun{} durch donttest{} .
Beachten Sie, dass donttest{} von check() ausgeführt wird und möglicherweise von CRAN ausgeführt wird ...
Wenn Ihre Dokumentation einige URLs enthält, stellen Sie Folgendes sicher:
Sie können {urlchecker} verwenden, um zu helfen: https://github.com/r-lib/urlchecker
README.md , NEWS.md , LICENSE.md ). Wenn Sie relative URIs haben, die beispielsweise in README.md auf Dateien wie NEWS.md oder CODE_OF_CONDUCT.md verweisen:
Code is distributed under the [GPL-3.0-License](LICENSE.md).
Sie werden den folgenden CRAN-Fehler auslösen:
Found the following (possibly) invalid file URIs:
URI: LICENSE.md
From: README.md
Das Ändern der relativen Links in absolute Links, die auf die {pkgdown}-Website verweisen, reicht aus (siehe den Verhaltenskodex in der README-Datei {dplyr} ).
Code is distributed under the [GPL-3.0-License](https://USERNAME.github.io/MY_PACKAGE/LICENSE.html).
Das Verweisen auf eine externe Ressource für eine Lizenz funktioniert ebenfalls (siehe {golem} README):
Code is distributed under the [GPL-3.0-License](https://www.gnu.org/licenses/gpl-3.0.en.html).
Wenn Sie Beispiele haben, deren Ausführung jeweils mehr als ein paar Sekunden dauert, schließen Sie sie in donttest{} ein und verwenden Sie nicht dontrun{} .
#' @example
#' donttest{x <- foo(y)}
Die Dokumentation sollte keine leeren Tags enthalten (für diejenigen, die einen Wert erfordern). devtools::check() erkennt leere @param und @return -Ausgaben.
Auch hier können Sie checkhelper::find_missing_tags() verwenden, um die fehlenden Tags in Ihrer Dokumentation zu finden. Installieren Sie {checkhelper} von GitHub: https://github.com/ThinkR-open/checkhelper
Wenn Sie dieses Problem bei CRAN haben
Warning: ![]()
attribute "align" not allowed for HTML5
Sie können diesen Schritten folgen:
https://github.com/DavisVaughan/extrachecks-html5
Status der CRAN-Repository-Richtlinie:
Pakete sollten nicht in den Home-Dateibereich des Benutzers (einschließlich Zwischenablagen) oder an eine andere Stelle im Dateisystem außer dem temporären Verzeichnis der R-Sitzung schreiben (oder während der Installation an dem Speicherort, auf den TMPDIR verweist: und eine solche Verwendung sollte bereinigt werden). Die Installation in die R-Installation des Systems (z. B. Skripte in dessen bin-Verzeichnis) ist nicht zulässig.
Möglicherweise wissen Sie nicht, was temporäre Verzeichnisse/Dateien sind und wie Sie sie verwenden. Diese temporären Dateien werden für die aktuelle R-Sitzung erstellt und gelöscht, wenn die Sitzung geschlossen wird.
Sie können sie erstellen mit:
file <- tempfile()
Fügen Sie eine Erweiterung hinzu mit
tmp <- tempfile(fileext = ".csv")
tmp
[1] "/var/folders/lz/thnnmbpd1rz0h1tmyzgg0mh00000gn/T//Rtmpnh8kAc/fileae1e28878432.csv"
So können Sie:
write.csv(iris, file = tmp)
Siehe: Namen für temporäre Dateien erstellen
Wenn Pakete von Ihrem Paket abhängen, sollten Sie einen umgekehrten Abhängigkeitstest für Pakete durchführen, die mit devtools::revdep() aufgelistet sind.
Verwenden Sie {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()Erstellt cran-comments.md, eine Vorlage für Ihre Kommunikation mit CRAN beim Einreichen eines Pakets. Ziel ist es, die Schritte, die Sie zur Überprüfung Ihres Pakets auf einer Vielzahl von Betriebssystemen unternommen haben, klar zu kommunizieren. Wenn Sie ein Update für ein Paket senden, das von anderen Paketen verwendet wird, müssen Sie auch die Ergebnisse Ihrer umgekehrten Abhängigkeitsprüfungen zusammenfassen.
usethis::use_cran_comments(open = rlang::is_interactive())
Sie können devtools::release() ausführen, um automatisch von R an CRAN zu senden.
Sie erhalten einen Link in Ihrem Postfach. Klicken Sie auf diesen Link, um den Upload zu bestätigen.
Abhängig vom Paket kann es zwischen einer Stunde und mehreren Wochen dauern. Wenn eine manuelle Prüfung erforderlich ist, kann es einige Zeit dauern.
Sie können den Status Ihres Pakets mit {cransays} verfolgen: https://lockedata.github.io/cransays/articles/dashboard.html
Checkliste für CRAN-Einreichungen
CRAN-Repository-Richtlinie
R-Pakete – von Hadley Wickham und Jennifer Bryan
Schreiben von R-Erweiterungen – Offizielle Dokumentation
Softwareentwicklung in R meistern – von Roger D. Peng, Sean Kross und Brooke Anderson.
Wie man gute R-Pakete entwickelt (für Open Science) – von Maëlle Salmon (einschließlich Liste der Tutorials)
Sinew: Einfache R-Paketdokumentation – von Jonathan Sidi
rOpenSci-Pakete: Entwicklung, Wartung und Peer Review – von rOpenSci-Onboarding-Redakteuren
