prepare for cran
1.0.0
Une liste ouverte et collaborative de choses que vous devez vérifier avant de soumettre votre colis au CRAN.
Ce repo est né après des échanges sur Twitter concernant le processus de soumission du CRAN, notamment ce fil.
L'idée ici est de rassembler des règles de base qui aideraient le CRAN à travailler plus facilement, en répertoriant les éléments courants (ou peu courants) qu'ils demandent aux responsables de modifier afin d'être à l'épreuve du CRAN.
La soumission CRAN est stricte, l'équipe CRAN fait son travail volontairement et il y a plus de 15 000 packages à maintenir.
Nous pensons pouvoir les aider en leur donnant quelques bonnes pratiques sur le développement de packages et la soumission CRAN, afin que les auteurs de packages puissent travailler sur ces problèmes avant que l'équipe CRAN ne le leur demande. Ainsi, nous pourrions faire gagner du temps à tout le monde en empêchant l'équipe CRAN de vous envoyer un email car il y a "avec R" dans le titre de votre DESCRIPTION. Parce que, comme le dit Peter Dalgaard :
Trop de gens ne réalisent pas que le groupe des responsables du CRAN peut se compter sur une seule main, parfois même sur un doigt.
Il reste encore des étapes à ajouter à la liste des tests automatisés comme détaillé dans les sections suivantes, mais vous pouvez l'ajouter à un fichier "dev/dev_history.R" pour les exécuter à chaque fois que vous envoyez quelque chose au 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() renvoie 0 0 0 La première chose à faire est d'exécuter devtools::check() , et de s'assurer qu'il n'y a pas d'erreur, pas d'avertissement, pas de note.
Si vous êtes dans RStudio, vous pouvez également cliquer sur Construire > Vérifier.
Si jamais vous pensez que ces avertissements ou notes ne sont pas justifiés, laissez un commentaire lors de la soumission en précisant pourquoi vous pensez que cela n'est pas justifié.
Vous pouvez appeler usethis::use_spell_check() dans votre package pour ajouter un test d'orthographe. Appelez spelling::spell_check_package() à tout moment si vous devez exécuter la vérification orthographique.
{rhub} Le package {rhub} permet de vérifier votre package sur plusieurs plateformes avec la configuration par défaut CRAN, à l'aide des actions GitHub.
Exécutez rhub::rhub_setup() et suivez les instructions.
En savoir plus sur {rhub} : https://github.com/r-hub/rhub
Testez que votre package est construit à l'aide de l'outil win-builder ou avec devtools::check_win_devel() .
Créez et soumettez manuellement votre archive ici : https://mac.r-project.org/macbuilder/submit.html
Voir https://github.com/DavisVaughan/extrachecks
Ces contrôles pourraient ne pas détecter tout ce que l'équipe CRAN détectera, voici donc une liste de bonnes pratiques :
Notez que s'il s'agit de votre première soumission, vous aurez automatiquement une NOTE, pour New submission .
La soumission au CRAN d'une nouvelle version ne doit pas être effectuée trop fréquemment. Une fois tous les 30 jours semble être la règle générale (sauf si vous soumettez à nouveau après les commentaires d'un membre de l'équipe CRAN).
Lorsque vous soumettez à nouveau après un retour d'information CRAN, assurez-vous d'inclure qu'il s'agit d'une nouvelle soumission après un retour d'information et décrivez ce que vous avez fait.
Si vous soumettez à nouveau après un retour CRAN, ajoutez 1 au composant patch de votre numéro de version (par exemple, si votre première soumission est 0.3.1, votre nouvelle soumission devrait être 0.3.2).
CRAN peut rejeter les packages contenant des erreurs de grammaire dans la DESCRIPTION . Quelques fautes d'orthographe courantes :
' (exemple : Lorem-Ipsum Helper Function for 'shiny' Prototyping )API , et non Api ) Le fichier DESCRIPTION doit avoir un cph (titulaire des droits d'auteur). Il peut s'agir soit du premier auteur, soit de l'entreprise où travaillent le ou les auteurs.
Cela n'a peut-être pas été détecté par le CRAN, mais assurez-vous d'avoir tout rempli dans ce fichier.
Il est tentant d'écrire quelque chose comme « Un gestionnaire de conditions plus convivial pour R » ou « Création facile de Dockerfile pour R » dans le titre de votre référentiel sur GitHub (et cela semble approprié). L'équipe CRAN vous demandera de supprimer ceci, car il est redondant (vous n'utilisez que des packages R sur le CRAN).
Écrivez un champ de description élaboré.
Le titre doit être dans la casse du titre
Lettres majuscules et minuscules dans les titres (cas du titre)
Remarque : cela devrait être détecté par r-hub.
Un package à l'épreuve du CRAN doit avoir une longue description expliquant ce que fait le package, quels sont les avantages, ce qui est nouveau et en quoi diffère-t-il de ce qui existe déjà sur le CRAN.
Ni le titre ni la description ne doivent commencer par « Un package… » ou par le nom du package.
Si vous citez un autre package, un article/livre ou un site Web/API, mettez son nom entre guillemets simples ' . De plus, les noms de packages sont sensibles à la casse. par exemple « brillant » -> « brillant ».
Si un nom de fonction est utilisé dans votre DESCRIPTION, assurez-vous de le suivre de parenthèses. par exemple, "fournit un remplacement immédiat pour cat() du package 'de base'."
Si vous écrivez une interface R vers une API ou implémentez un algorithme à partir d'un article/livre publié, ajoutez une référence à la publication sous forme de DOI, ISBN ou lien canonique similaire, ou URL de l'API ou de l'article dans le champ « Description ». de votre fichier DESCRIPTION.
Lorsque vous créez un lien vers un article ou un site Web dans la DESCRIPTION, utilisez des crochets angulaires pour créer un lien automatique.
API name or
authors (year) (see )
authors (year)
authors (year, ISBN:...)
sans espace après https: , doi: , arXiv: et crochets angulaires pour la liaison automatique.
Toutes les fonctions exportées dans votre package doivent avoir une valeur @return . Si une fonction ne renvoie pas de valeur, documentez-la également.
S'il existe une fonction interne (non exportée) avec une documentation partielle (titre, et.ou @param ), utilisez la balise #' @noRd pour éviter de générer de la documentation.
Vous pouvez utiliser checkhelper::find_missing_tags() pour vous aider à trouver les balises manquantes dans votre documentation. Installez {checkhelper} depuis GitHub : https://github.com/ThinkR-open/checkhelper
dontrun{} Les éléments dontrun{} dans les exemples pourraient en fait être exécutés par CRAN. Si vous ne souhaitez pas qu'un exemple soit exécuté, placez-le entre if (interactive()) {} . N'encapsulez pas l'exemple entre if (FALSE) {} .
dontrun{} ne doit être utilisé que si l'exemple ne peut vraiment pas être exécuté (par exemple en raison d'un logiciel supplémentaire manquant, de clés API manquantes, ...) par l'utilisateur. C'est pourquoi l'emballage des exemples dans dontrun{} ajoute le commentaire ("# Not run:") comme avertissement pour l'utilisateur.
Déballez les exemples s'ils sont exécutables en <5 secondes, ou remplacez dontrun{} par donttest{} .
Notez que donttest{} sera exécuté par check() et peut être exécuté par CRAN...
S'il y a des URL dans votre documentation, assurez-vous de :
Vous pouvez utiliser {urlchecker} pour vous aider : https://github.com/r-lib/urlchecker
README.md , NEWS.md , LICENSE.md ) Si vous avez des URI relatifs pointant vers des fichiers comme NEWS.md ou CODE_OF_CONDUCT.md à partir du README.md par exemple :
Code is distributed under the [GPL-3.0-License](LICENSE.md).
Ils généreront l'erreur CRAN suivante :
Found the following (possibly) invalid file URIs:
URI: LICENSE.md
From: README.md
Changer les liens relatifs en liens absolus pointant vers le site Web {pkgdown} fait l'affaire (voir le Code de conduite dans {dplyr} README)
Code is distributed under the [GPL-3.0-License](https://USERNAME.github.io/MY_PACKAGE/LICENSE.html).
Pointer vers une ressource externe, pour une licence, fonctionne également (voir le README {golem} ) :
Code is distributed under the [GPL-3.0-License](https://www.gnu.org/licenses/gpl-3.0.en.html).
Si vous avez des exemples dont l'exécution prend plus de quelques secondes chacun, enveloppez-les dans donttest{} , n'utilisez pas dontrun{} .
#' @example
#' donttest{x <- foo(y)}
Il ne doit pas y avoir de balises vides dans la documentation (pour celle nécessitant une valeur). devtools::check() détecte les sorties @param et @return vides.
Encore une fois, vous pouvez utiliser checkhelper::find_missing_tags() pour vous aider à trouver les balises manquantes dans votre documentation. Installez {checkhelper} depuis GitHub : https://github.com/ThinkR-open/checkhelper
Si vous avez ce problème sur CRAN
Warning: ![]()
attribute "align" not allowed for HTML5
Vous pouvez suivre ces étapes :
https://github.com/DavisVaughan/extrachecks-html5
État de la politique du référentiel CRAN :
Les packages ne doivent pas écrire dans l'espace fichier personnel de l'utilisateur (y compris les presse-papiers), ni ailleurs sur le système de fichiers en dehors du répertoire temporaire de la session R (ou lors de l'installation à l'emplacement pointé par TMPDIR : et une telle utilisation doit être nettoyée). L'installation dans l'installation R du système (par exemple, des scripts dans son répertoire bin) n'est pas autorisée.
Vous ne savez peut-être pas ce que sont les répertoires/fichiers temporaires ni comment les utiliser. Ces fichiers temporaires sont créés pour la session R en cours et ils sont supprimés à la fermeture de la session.
Vous pouvez les créer avec :
file <- tempfile()
Ajouter une extension avec
tmp <- tempfile(fileext = ".csv")
tmp
[1] "/var/folders/lz/thnnmbpd1rz0h1tmyzgg0mh00000gn/T//Rtmpnh8kAc/fileae1e28878432.csv"
Vous pouvez donc :
write.csv(iris, file = tmp)
Voir : Créer des noms pour les fichiers temporaires
Si les packages dépendent de votre package, vous devez exécuter un test de dépendances inverses sur les packages répertoriés avec devtools::revdep() .
Utilisez {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()Crée cran-comments.md, un modèle pour vos communications avec CRAN lors de la soumission d'un package. L’objectif est de communiquer clairement les étapes que vous avez suivies pour vérifier votre package sur une large gamme de systèmes d’exploitation. Si vous soumettez une mise à jour d'un package utilisé par d'autres packages, vous devez également résumer les résultats de vos vérifications de dépendance inverse.
usethis::use_cran_comments(open = rlang::is_interactive())
Vous pouvez exécuter devtools::release() pour envoyer automatiquement au CRAN depuis R.
Vous recevrez un lien dans votre boîte mail. Cliquez sur ce lien pour confirmer le téléchargement.
Selon le colis, cela peut prendre entre une heure et plusieurs semaines. S'il nécessite une inspection manuelle, cela peut prendre un certain temps.
Vous pouvez surveiller l'état de votre colis avec {cransays} : https://lockedata.github.io/cransays/articles/dashboard.html
Liste de contrôle pour les soumissions CRAN
Politique du référentiel CRAN
Forfaits R - par Hadley Wickham et Jennifer Bryan
Écriture d'extensions R - Documentation officielle
Maîtriser le développement logiciel en R - par Roger D. Peng, Sean Kross et Brooke Anderson.
Comment développer de bons packages R (pour la science ouverte) - par Maëlle Salmon (avec liste de tutoriels)
Sinew : Documentation du package R simple - par Jonathan Sidi
Packages rOpenSci : développement, maintenance et évaluation par les pairs - par les éditeurs intégrés de rOpenSci
