diff --git a/08_git-2.qmd b/08_git-2.qmd index 53665a9..49d04b6 100644 --- a/08_git-2.qmd +++ b/08_git-2.qmd @@ -139,7 +139,7 @@ A largo plazo, es posible que tengas que trabajar en el código de otra persona Es posible que más de una persona esté trabajando en el mismo archivo, ya sea un script o documentación. Por lo general, ese será un trabajo para muchas personas. Una solución es turnarse: vos trabajás en el archivo por la mañana y tu compañero/a lo hace por la tarde. -### 4. Las personas trabajan en branchs +### 4. Las personas trabajan en branches Aquí es donde aprovechamos al máximo lo que git tiene para ofrecer. diff --git a/D_checklist.qmd b/D_checklist.qmd index 66f961d..65437d7 100644 --- a/D_checklist.qmd +++ b/D_checklist.qmd @@ -4,9 +4,9 @@ A lo largo de las secciones los ejercicios transversales que llamamos "Construye A continuación encontrarás una lista de elementos que debe tener o con los que debe cumplir el paquete para estar completo. -- [ ] Estructura del paquete -- [ ] Repositorio local -- [ ] Repositorio remoto +- [ ] Estructura del paquete correcta +- [ ] El paquete instala correctamente +- [ ] Contiene instrucciones para comenzar a usarlo rapidamente ## DESCRIPTION @@ -26,11 +26,12 @@ A continuación encontrarás una lista de elementos que debe tener o con los que - [ ] Incluye un README con: - [ ] como instalar el paquete. - [ ] los autores. - - [ ] como se puede contribuir al paquete. + - [ ] etiquetas (covertura de tests, lifecycle, etc). + - [ ] un logo para el paquete. - [ ] Incluye una viñeta que explica como usar las funciones - [ ] El paquete tiene una página web -## Tests +## Checks y tests - [ ] El paquete tiene tests que cubren al menos el 75% del código de las funciones - [ ] El paquete tiene una GitHub action que revisa la covertura de los tests @@ -41,7 +42,12 @@ A continuación encontrarás una lista de elementos que debe tener o con los que - [ ] Incluye una licencia - [ ] Incluye un código de conducta -- [ ] El README incluye: - - [ ] etiquetas (covertura de tests, lifecycle, etc). - - [ ] un logo para el paquete. +- [ ] Guía de contribución + +## Uso de Git y GitHub + +- [ ] las dos personas en el equipo aportaron al paquete (hicieron commmits) +- [ ] hay suficientes commmits y cubren cambios pequeños en uno o pocos archivos +- [ ] los mensajes de commits son significativos + diff --git a/docs/D_checklist.html b/docs/D_checklist.html index 801099c..8788070 100644 --- a/docs/D_checklist.html +++ b/docs/D_checklist.html @@ -254,8 +254,9 @@

Table of contents

  • D.1 DESCRIPTION
  • D.2 Funciones y datos
  • D.3 Documentación
    • -
  • D.4 Tests
    • +
  • D.4 Checks y tests
  • D.5 Otros
    • +
  • D.6 Uso de Git y GitHub
    • @@ -284,9 +285,9 @@

    Appendix D — Checklist para revisar el paquete

    A lo largo de las secciones los ejercicios transversales que llamamos “Construyendo un paquete de R paso a paso” son una guía para, justamente, construir un paquete que lee y ayuda a analizar datos meteorológicos.

    A continuación encontrarás una lista de elementos que debe tener o con los que debe cumplir el paquete para estar completo.

    D.1 DESCRIPTION

    @@ -312,15 +313,15 @@

    • -
    • +
    • +

    • -
    -

    D.4 Tests

    +
    +

    D.4 Checks y tests

    +
    +
    +

    D.6 Uso de Git y GitHub

    +
    • +
    • +
    • diff --git a/docs/search.json b/docs/search.json index c802b9d..de5c64e 100644 --- a/docs/search.json +++ b/docs/search.json @@ -584,7 +584,7 @@ "href": "08_git-2.html#identificando-conflictos-de-versiones", "title": "10  Git para trabajar en equipo", "section": "10.3 Identificando conflictos de versiones", - "text": "10.3 Identificando conflictos de versiones\nImaginá que alguien en tu equipo cambia el contenido de archivo R/pulgadas_a_centimetros.R para cambiar el mensaje de \"medida_pulgadas debe ser numérico.\" a \"medida_pulgadas debe ser **de tipo** numérico.\":\npulgadas_a_centimetros <- function(medida_pulgadas) {\n \n if (!is.numeric(medida_pulgadas)) {\n cli::cli_abort(c(\n \"medida_pulgadas debe ser de tipo numérico.\",\n \"i\" = \"La variable ingresada es un {class(medida_pulgadas)[1]}.\"\n ))\n }\n \n medida_pulgadas * 2.54\n}\nAl mismo tiempo, vos también cambiaste esta línea en el código pero decidiste que el mensaje de error debe ser \"medida_pulgadas debe ser **una variable numérica**.\". Cuando intentás hacer push de la nueva versión del archivo al repositorio remoto te encontrás con este mensaje:\n>>> /usr/bin/git push origin HEAD:refs/heads/master\nTo github.com:paocorrales/paqueteprueba.git\n ! [rejected] HEAD -> master (fetch first)\nerror: failed to push some refs to 'github.com:paocorrales/paqueteprueba.git'\nhint: Updates were rejected because the remote contains work that you do not\nhint: have locally. This is usually caused by another repository pushing to\nhint: the same ref. If you want to integrate the remote changes, use\nhint: 'git pull' before pushing again.\nhint: See the 'Note about fast-forwards' in 'git push --help' for details.\nEl mensaje nos aconseja hacer pull antes de intentar hacer push para actualizar el repositorio remoto. Al hacer pull nos encontramos con el siguiente problema:\n>>> /usr/bin/git pull\nFrom github.com:paocorrales/paqueteprueba\n 6e63458..d7d2a6c master -> origin/master\nAuto-merging R/pulgadas_a_centimetros.R\nCONFLICT (content): Merge conflict in R/pulgadas_a_centimetros.R\nAutomatic merge failed; fix conflicts and then commit the result.\nEl mensaje dice que hay conflictos con el contenido de R/pulgadas_a_centimetros.R y que el merge automático falló. La buena noticia es que ya sabemos cuál es el archivo que da problemas. Aquí, hacer commits con pequeños cambios ayuda mucho.\nAhora, si revisamos el archivo R/pulgadas_a_centimetros.R, el contenido cambió:\npulgadas_a_centimetros <- function(medida_pulgadas) {\n\n if (!is.numeric(medida_pulgadas)) {\n cli::cli_abort(c(\n<<<<<<< HEAD\n \"medida_pulgadas debe ser una variable numérica.\",\n=======\n \"medida_pulgadas debe ser de tipo numérico.\",\n>>>>>>> d7d2a6cf0e03652e1ff52e7cf5eb2da96fe69312\n \"i\" = \"La variable ingresada es un {class(medida_pulgadas)[1]}.\"\n ))\n }\n\n medida_pulgadas * 2.54\n}\nEstos simbolos <<<<<<<, ======= y >>>>>>> fueron agregados por git para resaltar el contenido que está generando conflictos. Todo lo que hay entre <<<<<<< HEAD y ======= corresponde a la versión local, y el contenido entre ======= y >>>>>>> es la versión actualmente en GitHub. La cadena larga es el identificador del commit en Github y HEAD refiere al último commit local.\nPara arreglar el conflicto será necesario:\n\nEliminar las lineas que agrego git.\nElegir una de las 2 versiones en conflicto o generar una nueva versión que incluya todos los cambios.\nGuardar el archivo y hacer un nuevo commit, que normalmente tiene como mensaje “arregla conflicto de merge”.\n\nAlgunas herramientas como GitHub Desktop y GitKraken tienen una interfaz gráfica que permite resolver estos conflictos de manera rápida, sin embargo el mecanismo en el fondo es el mismo.\nLos conflictos de merge pueden suceder si cambiaste algo en GitHub, olvidaste hacer pull localmente y cambiaste el mismo archivo localmente. Aunque los conflictos son parte de trabajar con control de versiones, vamos a tratar de evitarlos en la medida de lo posible.\n\n10.3.1 1. Primero, hace pull\nEs recomendable hacer pull antes de empezar a trabajar con los archivos de un repositorio, ya que así empezarás a trabajar con la versión más actualizada del repositorio.\n\n\n10.3.2 2. Cada persona trabaja en archivos diferentes\nLa forma más fácil de evitar conflictos de merge es pedir a cada persona que trabaje en archivos diferentes y que no editen los archivos de otras personas. Esto funciona pero tiene limitaciones.\nA largo plazo, es posible que tengas que trabajar en el código de otra persona y, en esos casos, la comunicación entre los miembros del equipo es fundamental.\n\n\n10.3.3 3. Las personas se turnan\nEs posible que más de una persona esté trabajando en el mismo archivo, ya sea un script o documentación. Por lo general, ese será un trabajo para muchas personas. Una solución es turnarse: vos trabajás en el archivo por la mañana y tu compañero/a lo hace por la tarde.\n\n\n10.3.4 4. Las personas trabajan en branchs\nAquí es donde aprovechamos al máximo lo que git tiene para ofrecer.\nLas branchs (ramas en inglés) parecen un concepto nuevo, pero en realidad, siempre estás trabajando en una rama sin darte cuenta. La branch “predeterminada” en general se llama main porque es la principal, y todo este tiempo estuviste “agregando commits a la branch main”.\nUna branch en git es una etiqueta que apunta a un commit específico en el repositorio a partir de la cual se crean otras versiones paralelas. Trabajar en una branch te permite modificar archivos sin modificar los mismos archivos en otras branchs, porque esencialmente estás trabajando en un conjunto de archivos independientes. Cuando quieras pasar los cambios de tu branch a la branch main, tendrás que hacer un merge para combinar las ramas.\n\n\n\n“Diagrama de un árbol git que muestra la branch principal con 4 commits y una branch secundaria llamada función que comienza desde el commit 2 en la branch main y tiene 2 nuevos commits, independientes de la principal.”\n\n\nHay diferentes formas de utilizar branchs Quizás cada persona del equipo tiene una branch y trabaja en ella hasta que llega el momento de hacer un merge a la branch main. O quizás, y esto es más común, cada branch represente un nuevo desarrollo que se agrega al paquete. Por ejemplo, si agregás una nueva función, creás una branch, desarrollas el código y luego hacer un merge para incorporar la función al paquete.\nTrabajar con branchs no eliminará los conflictos del todo. Es posible que estos aparezcan cuando intentes hacer merge entre tu branch con la branch principal. Pero esto pasará una sola vez y solo cuando lo decidas.\nAntes de revisar cómo es el flujo de trabajo con branchs, hay un nuevo concepto que debemos mencionar: un pull request o PR es una herramienta de GitHub que te permite realizar cambios en una branch y luego solicitar a quien mantiene el repositorio que fusione esos cambios en la branch principal. Los pull request pueden surgir de forks (que presentaremos más adelante) o de branchs independientes dentro del repositorio. Permiten a quienes mantienen y colaboran en un proyecto, revisar, discutir, solicitar y aprobar los cambios y sumarlos al repositorio cuando estan listos.\n\n10.3.4.1 Escenario 1\nEste diagrama muestra el flujo de trabajo cuando se desea contribuir al repositorio utilizando branchs y además, asumimos que tenés permisos de escritura en el repositorio remoto:\n\n\nCloná el repositorio en tu computadora\nCrear una nueva branch.\nEdita archivos, agregalos y hacé commits en esa branch.\nCuando los cambios estén hechos y listos, envía un pull request al repositorio remoto para comparar tus cambios en tu branch con main.\nEl pull request es aceptado y fusionado o hay que hacer nuevos cambios (vuelve al paso 3).\nUna vez que el PR es aceptado y fusionado, la branch principal tiene ahora los cambios actualizados y ya se puede eliminar la branch donde estabas trabajando.\nEl proceso puede repetirse varias veces, en paralelo o en secuencia dependiendo del tamaño del equipo.\n\n\n\n10.3.4.2 Escenario 2\nSi no tenés permisos de escritura en el repositorio remoto, tendrás que utilizar forks. Esto es muy habitual cuando querés colaborar en un proyecto del que no formas parte.\nUn fork es una copia del repositorio de otra persona o equipo que se almacenará en tu cuenta de GitHub. Tanto el repositorio original como el fork se encuentran en GitHub, la diferencia es que puedes modificar y actualizar la versión que se encuentra en tu cuenta.\n\n\nCrear un fork del repositorio principal (si aún no lo tenés).\nCloná el repositorio en tu computadora.\nCrear una nueva branch en tu copia del repositorio.\nRealiza ediciones y cambios en los archivos y envíalos a la branch.\nCuando esté todo listo, abrí el pull request. Si te piden nuevos cambios tendrás que volver al paso 4.\nSi el PR aceptado y fusionado, la branch principal en el repositorio principal se actualizará y la nueva branch se puede borrar.\nFinalmente podés sincronizar tu fork del repositorio con el repositorio principal.", + "text": "10.3 Identificando conflictos de versiones\nImaginá que alguien en tu equipo cambia el contenido de archivo R/pulgadas_a_centimetros.R para cambiar el mensaje de \"medida_pulgadas debe ser numérico.\" a \"medida_pulgadas debe ser **de tipo** numérico.\":\npulgadas_a_centimetros <- function(medida_pulgadas) {\n \n if (!is.numeric(medida_pulgadas)) {\n cli::cli_abort(c(\n \"medida_pulgadas debe ser de tipo numérico.\",\n \"i\" = \"La variable ingresada es un {class(medida_pulgadas)[1]}.\"\n ))\n }\n \n medida_pulgadas * 2.54\n}\nAl mismo tiempo, vos también cambiaste esta línea en el código pero decidiste que el mensaje de error debe ser \"medida_pulgadas debe ser **una variable numérica**.\". Cuando intentás hacer push de la nueva versión del archivo al repositorio remoto te encontrás con este mensaje:\n>>> /usr/bin/git push origin HEAD:refs/heads/master\nTo github.com:paocorrales/paqueteprueba.git\n ! [rejected] HEAD -> master (fetch first)\nerror: failed to push some refs to 'github.com:paocorrales/paqueteprueba.git'\nhint: Updates were rejected because the remote contains work that you do not\nhint: have locally. This is usually caused by another repository pushing to\nhint: the same ref. If you want to integrate the remote changes, use\nhint: 'git pull' before pushing again.\nhint: See the 'Note about fast-forwards' in 'git push --help' for details.\nEl mensaje nos aconseja hacer pull antes de intentar hacer push para actualizar el repositorio remoto. Al hacer pull nos encontramos con el siguiente problema:\n>>> /usr/bin/git pull\nFrom github.com:paocorrales/paqueteprueba\n 6e63458..d7d2a6c master -> origin/master\nAuto-merging R/pulgadas_a_centimetros.R\nCONFLICT (content): Merge conflict in R/pulgadas_a_centimetros.R\nAutomatic merge failed; fix conflicts and then commit the result.\nEl mensaje dice que hay conflictos con el contenido de R/pulgadas_a_centimetros.R y que el merge automático falló. La buena noticia es que ya sabemos cuál es el archivo que da problemas. Aquí, hacer commits con pequeños cambios ayuda mucho.\nAhora, si revisamos el archivo R/pulgadas_a_centimetros.R, el contenido cambió:\npulgadas_a_centimetros <- function(medida_pulgadas) {\n\n if (!is.numeric(medida_pulgadas)) {\n cli::cli_abort(c(\n<<<<<<< HEAD\n \"medida_pulgadas debe ser una variable numérica.\",\n=======\n \"medida_pulgadas debe ser de tipo numérico.\",\n>>>>>>> d7d2a6cf0e03652e1ff52e7cf5eb2da96fe69312\n \"i\" = \"La variable ingresada es un {class(medida_pulgadas)[1]}.\"\n ))\n }\n\n medida_pulgadas * 2.54\n}\nEstos simbolos <<<<<<<, ======= y >>>>>>> fueron agregados por git para resaltar el contenido que está generando conflictos. Todo lo que hay entre <<<<<<< HEAD y ======= corresponde a la versión local, y el contenido entre ======= y >>>>>>> es la versión actualmente en GitHub. La cadena larga es el identificador del commit en Github y HEAD refiere al último commit local.\nPara arreglar el conflicto será necesario:\n\nEliminar las lineas que agrego git.\nElegir una de las 2 versiones en conflicto o generar una nueva versión que incluya todos los cambios.\nGuardar el archivo y hacer un nuevo commit, que normalmente tiene como mensaje “arregla conflicto de merge”.\n\nAlgunas herramientas como GitHub Desktop y GitKraken tienen una interfaz gráfica que permite resolver estos conflictos de manera rápida, sin embargo el mecanismo en el fondo es el mismo.\nLos conflictos de merge pueden suceder si cambiaste algo en GitHub, olvidaste hacer pull localmente y cambiaste el mismo archivo localmente. Aunque los conflictos son parte de trabajar con control de versiones, vamos a tratar de evitarlos en la medida de lo posible.\n\n10.3.1 1. Primero, hace pull\nEs recomendable hacer pull antes de empezar a trabajar con los archivos de un repositorio, ya que así empezarás a trabajar con la versión más actualizada del repositorio.\n\n\n10.3.2 2. Cada persona trabaja en archivos diferentes\nLa forma más fácil de evitar conflictos de merge es pedir a cada persona que trabaje en archivos diferentes y que no editen los archivos de otras personas. Esto funciona pero tiene limitaciones.\nA largo plazo, es posible que tengas que trabajar en el código de otra persona y, en esos casos, la comunicación entre los miembros del equipo es fundamental.\n\n\n10.3.3 3. Las personas se turnan\nEs posible que más de una persona esté trabajando en el mismo archivo, ya sea un script o documentación. Por lo general, ese será un trabajo para muchas personas. Una solución es turnarse: vos trabajás en el archivo por la mañana y tu compañero/a lo hace por la tarde.\n\n\n10.3.4 4. Las personas trabajan en branches\nAquí es donde aprovechamos al máximo lo que git tiene para ofrecer.\nLas branchs (ramas en inglés) parecen un concepto nuevo, pero en realidad, siempre estás trabajando en una rama sin darte cuenta. La branch “predeterminada” en general se llama main porque es la principal, y todo este tiempo estuviste “agregando commits a la branch main”.\nUna branch en git es una etiqueta que apunta a un commit específico en el repositorio a partir de la cual se crean otras versiones paralelas. Trabajar en una branch te permite modificar archivos sin modificar los mismos archivos en otras branchs, porque esencialmente estás trabajando en un conjunto de archivos independientes. Cuando quieras pasar los cambios de tu branch a la branch main, tendrás que hacer un merge para combinar las ramas.\n\n\n\n“Diagrama de un árbol git que muestra la branch principal con 4 commits y una branch secundaria llamada función que comienza desde el commit 2 en la branch main y tiene 2 nuevos commits, independientes de la principal.”\n\n\nHay diferentes formas de utilizar branchs Quizás cada persona del equipo tiene una branch y trabaja en ella hasta que llega el momento de hacer un merge a la branch main. O quizás, y esto es más común, cada branch represente un nuevo desarrollo que se agrega al paquete. Por ejemplo, si agregás una nueva función, creás una branch, desarrollas el código y luego hacer un merge para incorporar la función al paquete.\nTrabajar con branchs no eliminará los conflictos del todo. Es posible que estos aparezcan cuando intentes hacer merge entre tu branch con la branch principal. Pero esto pasará una sola vez y solo cuando lo decidas.\nAntes de revisar cómo es el flujo de trabajo con branchs, hay un nuevo concepto que debemos mencionar: un pull request o PR es una herramienta de GitHub que te permite realizar cambios en una branch y luego solicitar a quien mantiene el repositorio que fusione esos cambios en la branch principal. Los pull request pueden surgir de forks (que presentaremos más adelante) o de branchs independientes dentro del repositorio. Permiten a quienes mantienen y colaboran en un proyecto, revisar, discutir, solicitar y aprobar los cambios y sumarlos al repositorio cuando estan listos.\n\n10.3.4.1 Escenario 1\nEste diagrama muestra el flujo de trabajo cuando se desea contribuir al repositorio utilizando branchs y además, asumimos que tenés permisos de escritura en el repositorio remoto:\n\n\nCloná el repositorio en tu computadora\nCrear una nueva branch.\nEdita archivos, agregalos y hacé commits en esa branch.\nCuando los cambios estén hechos y listos, envía un pull request al repositorio remoto para comparar tus cambios en tu branch con main.\nEl pull request es aceptado y fusionado o hay que hacer nuevos cambios (vuelve al paso 3).\nUna vez que el PR es aceptado y fusionado, la branch principal tiene ahora los cambios actualizados y ya se puede eliminar la branch donde estabas trabajando.\nEl proceso puede repetirse varias veces, en paralelo o en secuencia dependiendo del tamaño del equipo.\n\n\n\n10.3.4.2 Escenario 2\nSi no tenés permisos de escritura en el repositorio remoto, tendrás que utilizar forks. Esto es muy habitual cuando querés colaborar en un proyecto del que no formas parte.\nUn fork es una copia del repositorio de otra persona o equipo que se almacenará en tu cuenta de GitHub. Tanto el repositorio original como el fork se encuentran en GitHub, la diferencia es que puedes modificar y actualizar la versión que se encuentra en tu cuenta.\n\n\nCrear un fork del repositorio principal (si aún no lo tenés).\nCloná el repositorio en tu computadora.\nCrear una nueva branch en tu copia del repositorio.\nRealiza ediciones y cambios en los archivos y envíalos a la branch.\nCuando esté todo listo, abrí el pull request. Si te piden nuevos cambios tendrás que volver al paso 4.\nSi el PR aceptado y fusionado, la branch principal en el repositorio principal se actualizará y la nueva branch se puede borrar.\nFinalmente podés sincronizar tu fork del repositorio con el repositorio principal.", "crumbs": [ "10  Git para trabajar en equipo" ] @@ -634,7 +634,7 @@ "href": "09_paquetes-1.html#qué-es-un-paquete-r", "title": "\n11  Empaquetando funciones\n", "section": "\n11.3 ¿Qué es un paquete R?", - "text": "11.3 ¿Qué es un paquete R?\nPara entender qué es un paquete R, daremos un paso atrás y consideraremos lo que ocurre cuando interactuamos con R. El primer acercamiento a R es a través de la consola, donde escribís funciones en R para realizar tareas que que se imprimen en pantalla. Si no cambiaste la configuración inicial esa sesión de R correrar en tu carpeta raiz, normalmente algo parecido a /home/username/ en Linux, /Users/username/ para macOS, o C:\\Users\\username para Windows. Así que cualquier dato o gráfico que guardes o importes debe incluir la ruta del archivo a la ubicación correcta. Desde un punto de vista reproducible y modular esto va en contra de las buenas prácticas. Asimismo, el código de R qeu escribas en la consola no se guarda en ningún lado. Por tanto, no podés reutilizarlo o compartirlo fácilmente.\nEl siguiente nivel es guardar el código en un scriptde R (un archivo almacenado en cualquier lugar en el ordenador que termina en .R) y hacer que R ejecute este código en secuencia. En el pasado, la gente podía escribir scripts de R en editores de texto como vim, emacs o Notepad, y ejecutar manualmente el script en la consola de R. En la actualidad, la mayoría de la gente utiliza un Entorno de Desarrollo Integrado (IDE) como RStudio o VS Code. Este es el método más utilizado para realizar cualquier tipo de trabajo en R. Teóricamente, el código escrito de esta forma es reproducible y se puede compartir. Sin embargo, en la práctica, las personas escriben código de manera secuencial, resolviendo un problema luego del otro y trabajan con R de forma más interactiva que programáticamente. El directorio de trabajo de un script R en este caso no está definido, por lo que seguimos encontrando problemas similares a los que tenemos al usar la consola. Si bien se puede almacenar código o funciones de R en un script y cargarlas con source() desde otros scripts, esto implica hacer un seguimiento de los archivos con estas funciones y actualizarlos cuando corresponda.\nUn paquete de R no es muy diferente de utilizar varios scripts. Existen ciertas expectativas y convenciones que deben seguirse para para que que el paquete se “instale” en tu computadora y quede disponible como paquete. Algunas de estas convenciones son:\n\nDebe haber un archivo llamado DESCRIPTION que contiene los metadatos necesarios para que R sepa cómo instalar el paquete. Veremos qué debe incluir más adelante.\nDebe haber una carpeta llamada R/. Normalmente sólo contendrá archivos .R y sólo incluirán las funciones que hayas creado. Veremos como incorporar las funciones que ya tenemos dentro de un paquete.\nDebe haber un archivo NAMESPACE que contenga la lista de funciones de tu paquete que esten disponibles para ser usadas. Este archivo se gestiona automáticamente con funciones de devtools y roxygen2.\nLa carpeta que contiene todo, aunque no es obligatorio debería llamarse como el paquete. Por ejemplo, el paquete usethis tiene el nombre de carpeta usethis/. Esto no es un requisito explícito, pero es muy recomendable. R determina el nombre del paquete a partir del campo Package: en el archivo DESCRIPTION.\n\nNada de esto es algo de lo que tengas que preocuparte realmente porque los paquetes usethis y devtools están diseñados para hacer muchas de estas tareas de configuración de paquetes por ti, o al menos simplificarlas.\nHasta ahora interactuaste con paquetes de R instalados en tu computadora con install.packages() y que luego cargas en memoria con library() para poder usar sus funciones. Instalado y en memoria son dos estados posibles de un paquete. Pero ahora, en el contexto del desarrollo de paquetes, empezarás a trabajar con el código fuente. En este estado, el paquete tiene una pinta distinta y el flujo de trabajo también va a cambiar.\nLos 5 estados en los que puede estar un paquete de R son:\n\n\ncódigo fuente o source en inglés: incluye la carpeta y todos los archivos que mencionamos antes.\n\nbundled: es una versión comprimida del paquete, independiente del sistema operativo de las computadoras, a partir del cual puede ser instalado.\n\nbinary o binario: es una versión del paquete lista para instalar, sin embargo depende del sistema operativo. Un binario creado para Windows no funcionará en Linux.\n\ninstalado: es la version del paquete ya instalado en una computadora.\n\nen memoria: el paquete está cargado en el ambiente de R y podemos usar las funciones porque corrimos library(nombre_paquete).\n\n¿Cómo funciona la instalación de paquetes? Depende. Si instalas el paquete desde CRAN, Bioconductor o R-Universe install.packages() va a descargar el bundle o el binario en tu computadora, y lo va a descomprimir la “librería de paquetes de R” (una carpeta medio escondida en tu computadora) y generar los archivos necesario para que puedas usarlo.\nSi instalas tu paquete mientras lo estás desarrollando, R va a tomar el código fuente para generar los archivos necesarios y guardar los en la libreria de paquetes de R, de la misma manera que lo hace con cualquier otro paquete.\nEsta “instalación del paquete” en la libreria no es más que una carpeta con archivos y otras carpetas que contienen el código de las funciones en un formato específico que entiende R. Para ver dónde están instalados los paquetes, utiliza:\n\n.libPaths()\n\n[1] \"/home/paola/R/x86_64-pc-linux-gnu-library/4.5\"\n[2] \"/opt/R/4.5.0/lib/R/library\" \n\n\nSi corres esa función en la consola, es posible que el resultado sea un poco diferente a esto, depende de cada computadora. Si .libPaths() muestra más de una ruta, normalmente la primera contendrá todos los paquetes.\n\nlibrary(fs)\n\nprimary_library_path <- .libPaths()[1] #Elegimos la primera ruta\npackages <- dir_ls(path(primary_library_path))\n\n# Número de paquetes instalados\nlength(packages)\n\n[1] 246\n\n# Muestra los primeros 6\nhead(packages)\n\n/home/paola/R/x86_64-pc-linux-gnu-library/4.5/DBI\n/home/paola/R/x86_64-pc-linux-gnu-library/4.5/DT\n/home/paola/R/x86_64-pc-linux-gnu-library/4.5/FNN\n/home/paola/R/x86_64-pc-linux-gnu-library/4.5/Formula\n/home/paola/R/x86_64-pc-linux-gnu-library/4.5/GitStats\n/home/paola/R/x86_64-pc-linux-gnu-library/4.5/Lahman", + "text": "11.3 ¿Qué es un paquete R?\nPara entender qué es un paquete R, daremos un paso atrás y consideraremos lo que ocurre cuando interactuamos con R. El primer acercamiento a R es a través de la consola, donde escribís funciones en R para realizar tareas que que se imprimen en pantalla. Si no cambiaste la configuración inicial esa sesión de R correrar en tu carpeta raiz, normalmente algo parecido a /home/username/ en Linux, /Users/username/ para macOS, o C:\\Users\\username para Windows. Así que cualquier dato o gráfico que guardes o importes debe incluir la ruta del archivo a la ubicación correcta. Desde un punto de vista reproducible y modular esto va en contra de las buenas prácticas. Asimismo, el código de R qeu escribas en la consola no se guarda en ningún lado. Por tanto, no podés reutilizarlo o compartirlo fácilmente.\nEl siguiente nivel es guardar el código en un scriptde R (un archivo almacenado en cualquier lugar en el ordenador que termina en .R) y hacer que R ejecute este código en secuencia. En el pasado, la gente podía escribir scripts de R en editores de texto como vim, emacs o Notepad, y ejecutar manualmente el script en la consola de R. En la actualidad, la mayoría de la gente utiliza un Entorno de Desarrollo Integrado (IDE) como RStudio o VS Code. Este es el método más utilizado para realizar cualquier tipo de trabajo en R. Teóricamente, el código escrito de esta forma es reproducible y se puede compartir. Sin embargo, en la práctica, las personas escriben código de manera secuencial, resolviendo un problema luego del otro y trabajan con R de forma más interactiva que programáticamente. El directorio de trabajo de un script R en este caso no está definido, por lo que seguimos encontrando problemas similares a los que tenemos al usar la consola. Si bien se puede almacenar código o funciones de R en un script y cargarlas con source() desde otros scripts, esto implica hacer un seguimiento de los archivos con estas funciones y actualizarlos cuando corresponda.\nUn paquete de R no es muy diferente de utilizar varios scripts. Existen ciertas expectativas y convenciones que deben seguirse para para que que el paquete se “instale” en tu computadora y quede disponible como paquete. Algunas de estas convenciones son:\n\nDebe haber un archivo llamado DESCRIPTION que contiene los metadatos necesarios para que R sepa cómo instalar el paquete. Veremos qué debe incluir más adelante.\nDebe haber una carpeta llamada R/. Normalmente sólo contendrá archivos .R y sólo incluirán las funciones que hayas creado. Veremos como incorporar las funciones que ya tenemos dentro de un paquete.\nDebe haber un archivo NAMESPACE que contenga la lista de funciones de tu paquete que esten disponibles para ser usadas. Este archivo se gestiona automáticamente con funciones de devtools y roxygen2.\nLa carpeta que contiene todo, aunque no es obligatorio debería llamarse como el paquete. Por ejemplo, el paquete usethis tiene el nombre de carpeta usethis/. Esto no es un requisito explícito, pero es muy recomendable. R determina el nombre del paquete a partir del campo Package: en el archivo DESCRIPTION.\n\nNada de esto es algo de lo que tengas que preocuparte realmente porque los paquetes usethis y devtools están diseñados para hacer muchas de estas tareas de configuración de paquetes por ti, o al menos simplificarlas.\nHasta ahora interactuaste con paquetes de R instalados en tu computadora con install.packages() y que luego cargas en memoria con library() para poder usar sus funciones. Instalado y en memoria son dos estados posibles de un paquete. Pero ahora, en el contexto del desarrollo de paquetes, empezarás a trabajar con el código fuente. En este estado, el paquete tiene una pinta distinta y el flujo de trabajo también va a cambiar.\nLos 5 estados en los que puede estar un paquete de R son:\n\n\ncódigo fuente o source en inglés: incluye la carpeta y todos los archivos que mencionamos antes.\n\nbundled: es una versión comprimida del paquete, independiente del sistema operativo de las computadoras, a partir del cual puede ser instalado.\n\nbinary o binario: es una versión del paquete lista para instalar, sin embargo depende del sistema operativo. Un binario creado para Windows no funcionará en Linux.\n\ninstalado: es la version del paquete ya instalado en una computadora.\n\nen memoria: el paquete está cargado en el ambiente de R y podemos usar las funciones porque corrimos library(nombre_paquete).\n\n¿Cómo funciona la instalación de paquetes? Depende. Si instalas el paquete desde CRAN, Bioconductor o R-Universe install.packages() va a descargar el bundle o el binario en tu computadora, y lo va a descomprimir la “librería de paquetes de R” (una carpeta medio escondida en tu computadora) y generar los archivos necesario para que puedas usarlo.\nSi instalas tu paquete mientras lo estás desarrollando, R va a tomar el código fuente para generar los archivos necesarios y guardar los en la libreria de paquetes de R, de la misma manera que lo hace con cualquier otro paquete.\nEsta “instalación del paquete” en la libreria no es más que una carpeta con archivos y otras carpetas que contienen el código de las funciones en un formato específico que entiende R. Para ver dónde están instalados los paquetes, utiliza:\n\n.libPaths()\n\n[1] \"/home/paola/R/x86_64-pc-linux-gnu-library/4.5\"\n[2] \"/opt/R/4.5.0/lib/R/library\" \n\n\nSi corres esa función en la consola, es posible que el resultado sea un poco diferente a esto, depende de cada computadora. Si .libPaths() muestra más de una ruta, normalmente la primera contendrá todos los paquetes.\n\nlibrary(fs)\n\nprimary_library_path <- .libPaths()[1] #Elegimos la primera ruta\npackages <- dir_ls(path(primary_library_path))\n\n# Número de paquetes instalados\nlength(packages)\n\n[1] 365\n\n# Muestra los primeros 6\nhead(packages)\n\n/home/paola/R/x86_64-pc-linux-gnu-library/4.5/BiocGenerics\n/home/paola/R/x86_64-pc-linux-gnu-library/4.5/BiocManager\n/home/paola/R/x86_64-pc-linux-gnu-library/4.5/BiocStyle\n/home/paola/R/x86_64-pc-linux-gnu-library/4.5/BiocVersion\n/home/paola/R/x86_64-pc-linux-gnu-library/4.5/CFtime\n/home/paola/R/x86_64-pc-linux-gnu-library/4.5/DBI", "crumbs": [ "11  Empaquetando funciones" ] @@ -1080,18 +1080,18 @@ "href": "D_checklist.html#documentación", "title": "Appendix D — Checklist para revisar el paquete", "section": "D.3 Documentación", - "text": "D.3 Documentación\n\nTodas las funciones y datos están documentados y tienen ejemplos de uso\nIncluye un README con:\n\ncomo instalar el paquete.\nlos autores.\ncomo se puede contribuir al paquete.\n\n\nIncluye una viñeta que explica como usar las funciones\nEl paquete tiene una página web", + "text": "D.3 Documentación\n\nTodas las funciones y datos están documentados y tienen ejemplos de uso\nIncluye un README con:\n\ncomo instalar el paquete.\nlos autores.\netiquetas (covertura de tests, lifecycle, etc).\nun logo para el paquete.\n\nIncluye una viñeta que explica como usar las funciones\nEl paquete tiene una página web", "crumbs": [ "Appendices", "D  Checklist para revisar el paquete" ] }, { - "objectID": "D_checklist.html#tests", - "href": "D_checklist.html#tests", + "objectID": "D_checklist.html#checks-y-tests", + "href": "D_checklist.html#checks-y-tests", "title": "Appendix D — Checklist para revisar el paquete", - "section": "D.4 Tests", - "text": "D.4 Tests\n\nEl paquete tiene tests que cubren al menos el 75% del código de las funciones\nEl paquete tiene una GitHub action que revisa la covertura de los tests\nEl paquete pasa R CMD checks\nEl paquete tiene una GitHub action que chequea el paquete en distintos sistemas operativos", + "section": "D.4 Checks y tests", + "text": "D.4 Checks y tests\n\nEl paquete tiene tests que cubren al menos el 75% del código de las funciones\nEl paquete tiene una GitHub action que revisa la covertura de los tests\nEl paquete pasa R CMD checks\nEl paquete tiene una GitHub action que chequea el paquete en distintos sistemas operativos", "crumbs": [ "Appendices", "D  Checklist para revisar el paquete" @@ -1102,7 +1102,18 @@ "href": "D_checklist.html#otros", "title": "Appendix D — Checklist para revisar el paquete", "section": "D.5 Otros", - "text": "D.5 Otros\n\nIncluye una licencia\nIncluye un código de conducta\nEl README incluye:\n\netiquetas (covertura de tests, lifecycle, etc).\nun logo para el paquete.", + "text": "D.5 Otros\n\nIncluye una licencia\nIncluye un código de conducta\nGuía de contribución", + "crumbs": [ + "Appendices", + "D  Checklist para revisar el paquete" + ] + }, + { + "objectID": "D_checklist.html#uso-de-git-y-github", + "href": "D_checklist.html#uso-de-git-y-github", + "title": "Appendix D — Checklist para revisar el paquete", + "section": "D.6 Uso de Git y GitHub", + "text": "D.6 Uso de Git y GitHub\n\nlas dos personas en el equipo aportaron al paquete (hicieron commmits)\nhay suficientes commmits y cubren cambios pequeños en uno o pocos archivos\nlos mensajes de commits son significativos", "crumbs": [ "Appendices", "D  Checklist para revisar el paquete"