prepare for cran
1.0.0
Una lista abierta y colaborativa de cosas que debes verificar antes de enviar tu paquete al CRAN.
Este repositorio nació después de intercambios en Twitter sobre el proceso de envío de CRAN, especialmente este hilo.
La idea aquí es recopilar reglas básicas que ayudarían a que el CRAN funcione allí más fácilmente, enumerando cosas comunes (o poco comunes) que piden a los mantenedores que cambien para que sean a prueba de CRAN.
El envío de CRAN es estricto, el equipo de CRAN está haciendo su trabajo de forma voluntaria y hay más de 15.000 paquetes que mantener.
Creemos que podemos ayudarlos brindándoles algunas buenas prácticas sobre el desarrollo de paquetes y el envío de CRAN, para que los autores de paquetes puedan trabajar en estos temas antes de que el equipo de CRAN se los pida. Por lo tanto, podríamos ahorrarles tiempo a todos al evitar que el equipo de CRAN le envíe un correo electrónico porque hay "con R" en el título de su DESCRIPCIÓN. Porque, como dijo Peter Dalgaard:
Mucha gente no se da cuenta de que el grupo de mantenedores de CRAN se puede contar con una mano, incluso a veces con un dedo.
Todavía hay pasos para agregar a la lista de pruebas automatizadas como se detalla en las siguientes secciones, pero puede agregarlas a un archivo "dev/dev_history.R" para ejecutarlas cada vez que envíe algo a 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() devuelva 0 0 0 Lo primero que debe hacer es ejecutar devtools::check() y asegurarse de que no haya errores, advertencias ni notas.
Si estás en RStudio, también puedes hacer clic en Construir > Verificar.
Si alguna vez cree que estas advertencias o notas no están justificadas, deje un comentario al enviarlas donde especifique por qué cree que no está justificado.
Puede llamar usethis::use_spell_check() dentro de su paquete para agregar una prueba de ortografía. Llame spelling::spell_check_package() en cualquier momento si necesita ejecutar el corrector ortográfico.
{rhub} El paquete {rhub} permite verificar su paquete en varias plataformas con la configuración predeterminada de CRAN, usando GitHub Actions.
Ejecute rhub::rhub_setup() y siga las instrucciones.
Más información sobre {rhub} : https://github.com/r-hub/rhub
Pruebe que su paquete se compila utilizando la herramienta win-builder o con devtools::check_win_devel() .
Cree y envíe manualmente su archivo aquí: https://mac.r-project.org/macbuilder/submit.html
Ver https://github.com/DavisVaughan/extrachecks
Es posible que estas comprobaciones no detecten todo lo que el equipo de CRAN detectará, por lo que aquí hay una lista de buenas prácticas:
Tenga en cuenta que si este es su primer envío, automáticamente tendrá una NOTA para New submission .
El envío CRAN de una nueva versión no debe realizarse con demasiada frecuencia. Una vez cada 30 días parece ser la regla general (a menos que vuelva a enviarlo después de recibir comentarios de un miembro del equipo de CRAN).
Al volver a enviar después de un comentario de CRAN, asegúrese de incluir que se trata de un nuevo envío después de un comentario y describa lo que ha hecho.
Si vuelve a enviar después de recibir comentarios de CRAN, agregue 1 al componente de parche de su número de versión (por ejemplo, si su primer envío es 0.3.1, su nuevo envío debe ser 0.3.2).
CRAN puede rechazar paquetes que tengan errores gramaticales en DESCRIPTION . Algunos errores ortográficos comunes:
' (ejemplo: Lorem-Ipsum Helper Function for 'shiny' Prototyping )API , no Api ) El archivo DESCRIPTION debe tener un cph (titular de los derechos de autor). Puede ser el primer autor o la empresa donde trabaja el autor.
Es posible que CRAN no detecte esto, pero asegúrese de haber completado todo lo que hay en este archivo.
Es tentador escribir algo como 'Un manejador de condiciones más amigable para R' o 'Creación fácil de Dockerfile para R' en el título de su repositorio en GitHub (y parece apropiado). El equipo de CRAN le pedirá que lo elimine, ya que es redundante (solo está tratando con paquetes R en CRAN).
Escribe un campo de descripción elaborado.
El título debe estar en mayúsculas y minúsculas.
Letras mayúsculas y minúsculas en títulos (caso de título)
Nota: esto debería ser detectado por r-hub.
Un paquete a prueba de CRAN debe tener una descripción larga que explique qué hace el paquete, cuáles son los beneficios, qué hay de nuevo y en qué se diferencia de lo que ya está en CRAN.
Ni el título ni la descripción deben comenzar con "Un paquete..." o con el nombre del paquete.
Si cita otro paquete, un artículo/libro o un sitio web/API, coloque su nombre entre comillas simples ' . Además, los nombres de los paquetes distinguen entre mayúsculas y minúsculas. por ejemplo, 'brillante' --> 'Brillante'.
Si se utiliza un nombre de función en su DESCRIPCIÓN, asegúrese de seguirlo entre paréntesis. por ejemplo, "proporciona un reemplazo directo para cat() del paquete 'base'".
Si escribe una interfaz R para una API o implementa un algoritmo a partir de un artículo/libro publicado, agregue una referencia a la publicación como DOI, ISBN o un enlace canónico similar, o URL para la API o el artículo en el campo 'Descripción'. de su archivo DESCRIPCIÓN.
Al vincular a un artículo o sitio web en la DESCRIPCIÓN, utilice corchetes angulares para vincular automáticamente.
API name <http:...> or <https:...>
authors (year) <DOI:...> (see <https://en.wikipedia.org/wiki/Digital_object_identifier> )
authors (year) <arXiv:...>
authors (year, ISBN:...)
sin espacios después de https: doi: arXiv: y corchetes angulares para el enlace automático.
Todas las funciones exportadas en su paquete deben tener un valor @return . Si una función no devuelve un valor, documentelo también.
Si hay una función interna (no exportada) con documentación parcial (título y.o @param ), use la etiqueta #' @noRd para evitar generar documentación.
Puede utilizar checkhelper::find_missing_tags() para ayudarle a encontrar las etiquetas que faltan en su documentación. Instale {checkhelper} desde GitHub: https://github.com/ThinkR-open/checkhelper
dontrun{} Los elementos dontrun{} de los ejemplos podrían de hecho ser ejecutados por CRAN. Si no desea que se ejecute un ejemplo, envuélvalo entre if (interactive()) {} . No incluya el ejemplo entre if (FALSE) {} .
dontrun{} sólo debe usarse si el ejemplo realmente no puede ser ejecutado (por ejemplo, debido a que falta software adicional, faltan claves API, ...) por parte del usuario. Es por eso que al empaquetar ejemplos en dontrun{} se agrega el comentario ("# No ejecutar:") como advertencia para el usuario.
Desenvuelva los ejemplos si son ejecutables en < 5 segundos, o reemplace dontrun{} con donttest{} .
Tenga en cuenta que donttest{} se ejecutará mediante check() y puede ejecutarse mediante CRAN...
Si hay algunas URL en su documentación, asegúrese de:
Puedes usar {urlchecker} para ayudar: https://github.com/r-lib/urlchecker
README.md , NEWS.md , LICENSE.md ). Si tiene URI relativos que apuntan a archivos como NEWS.md o CODE_OF_CONDUCT.md desde README.md por ejemplo:
Code is distributed under the [GPL-3.0-License](LICENSE.md).
Lanzarán el siguiente error CRAN:
Found the following (possibly) invalid file URIs:
URI: LICENSE.md
From: README.md
Cambiar los enlaces relativos a enlaces absolutos que apuntan al sitio web {pkgdown} funciona (consulte el Código de conducta en {dplyr} README)
Code is distributed under the [GPL-3.0-License](https://USERNAME.github.io/MY_PACKAGE/LICENSE.html).
Apuntar a un recurso externo, para obtener una licencia, también funciona (consulte el README {golem} ):
Code is distributed under the [GPL-3.0-License](https://www.gnu.org/licenses/gpl-3.0.en.html).
Si tiene ejemplos que tardan más de unos segundos en ejecutarse, envuélvalos en donttest{} , no use dontrun{} .
#' @example
#' donttest{x <- foo(y)}
No debe haber etiquetas vacías en la documentación (para la que requiere un valor). devtools::check() detecta salidas @param y @return vacías.
Nuevamente, puedes usar checkhelper::find_missing_tags() para ayudarte a encontrar las etiquetas que faltan en tu documentación. Instale {checkhelper} desde GitHub: https://github.com/ThinkR-open/checkhelper
Si tienes este problema en CRAN
Warning: <img> attribute "align" not allowed for HTML5
Puedes seguir estos pasos:
https://github.com/DavisVaughan/extrachecks-html5
Estado de la política del repositorio CRAN:
Los paquetes no deben escribirse en el espacio de archivos de inicio del usuario (incluidos los portapapeles), ni en ningún otro lugar del sistema de archivos aparte del directorio temporal de la sesión R (o durante la instalación en la ubicación señalada por TMPDIR: y dicho uso debe limpiarse). No se permite la instalación en la instalación R del sistema (por ejemplo, scripts en su directorio bin).
Es posible que no sepa qué son los directorios/archivos temporales o cómo usarlos. Estos archivos temporales se crean para la sesión R actual y se eliminan cuando se cierra la sesión.
Puedes crearlos con:
file <- tempfile()
Agregar una extensión con
tmp <- tempfile(fileext = ".csv")
tmp
[1] "/var/folders/lz/thnnmbpd1rz0h1tmyzgg0mh00000gn/T//Rtmpnh8kAc/fileae1e28878432.csv"
Entonces puedes:
write.csv(iris, file = tmp)
Ver: Crear nombres para archivos temporales
Si los paquetes dependen de su paquete, debe ejecutar una prueba de dependencias inversas en los paquetes enumerados con devtools::revdep() .
Utilice {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()Crea cran-comments.md, una plantilla para sus comunicaciones con CRAN al enviar un paquete. El objetivo es comunicar claramente los pasos que ha seguido para verificar su paquete en una amplia gama de sistemas operativos. Si envía una actualización de un paquete que utilizan otros paquetes, también debe resumir los resultados de las comprobaciones de dependencia inversa.
usethis::use_cran_comments(open = rlang::is_interactive())
Puede ejecutar devtools::release() para enviar automáticamente a CRAN desde R.
Recibirás un enlace en tu buzón. Haga clic en este enlace para confirmar la carga.
Dependiendo del paquete, puede tardar entre una hora y varias semanas; si necesita inspección manual, puede llevar algún tiempo.
Puede ver el estado de su paquete con {cransays} : https://lockedata.github.io/cransays/articles/dashboard.html
Lista de verificación para envíos de CRAN
Política de repositorio CRAN
Paquetes R - por Hadley Wickham y Jennifer Bryan
Escritura de extensiones R: documentación oficial
Dominar el desarrollo de software en R - por Roger D. Peng, Sean Kross y Brooke Anderson.
Cómo desarrollar buenos paquetes R (para ciencia abierta) - por Maëlle Salmon (incluye lista de tutoriales)
Sinew: Documentación del paquete R simple - por Jonathan Sidi
Paquetes rOpenSci: desarrollo, mantenimiento y revisión por pares - por los editores de incorporación de rOpenSci
