From d097d61db389d6ccb0d037750e6648f1d1f65f21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= Date: Fri, 15 Dec 2023 14:13:41 +0100 Subject: [PATCH] update roxygen2 contents (#750) * Translate bookreleaseissue to Portuguese (#675) * Translate bookreleaseissue to Portuguese * Review 1 of Portuguese translation for `bookreleaseissue.Rmd` (#682) * Fix some typos in the automatic translated output * Add translated version of template * Update paths to templates inside translated version * Small fix over paragraph Co-authored-by: Marcelo S. Perlin * Add neutral gender suffix --------- Co-authored-by: Marcelo S. Perlin * Update bookreleaseissue.pt.Rmd --------- Co-authored-by: Pedro Faria <69123925+pedropark99@users.noreply.github.com> Co-authored-by: Marcelo S. Perlin Co-authored-by: Yanina Bellini Saibene * update roxygen2 contents * add news item * Update pkg_building.es.Rmd Co-authored-by: Yanina Bellini Saibene * Update pkg_building.es.Rmd Co-authored-by: Yanina Bellini Saibene * Update pkg_building.es.Rmd Co-authored-by: Yanina Bellini Saibene --------- Co-authored-by: Pedro Faria <69123925+pedropark99@users.noreply.github.com> Co-authored-by: Marcelo S. Perlin Co-authored-by: Yanina Bellini Saibene --- booknews.Rmd | 2 ++ bookreleaseissue.pt.Rmd | 12 +++++------ pkg_building.Rmd | 28 +++++++++--------------- pkg_building.es.Rmd | 36 ++++++++++++------------------- templates/book-release.pt.md | 41 ++++++++++++++++++++++++++++++++++++ 5 files changed, 72 insertions(+), 47 deletions(-) create mode 100644 templates/book-release.pt.md diff --git a/booknews.Rmd b/booknews.Rmd index c7691cf47..463353f81 100644 --- a/booknews.Rmd +++ b/booknews.Rmd @@ -2,6 +2,8 @@ ## dev (0.9.0) +- 2023-12-15, update roxygen2 advice, mainly linking to roxygen2 website (#750). + - 2023-09-15, add suggestions for API packages (#496). - Translation to Spanish! diff --git a/bookreleaseissue.pt.Rmd b/bookreleaseissue.pt.Rmd index cd6326e18..39b3e4b04 100644 --- a/bookreleaseissue.pt.Rmd +++ b/bookreleaseissue.pt.Rmd @@ -2,11 +2,11 @@ repo-actions: true --- -# Book release guidance {#bookreleaseissue} +# Orientação para lançamento de livros {#bookreleaseissue} -Editors preparing for a release can run the `prelease.R` script in the `inst` directory of this repository to automatically open a GitHub issue with checkpoints for all current issues assigned to the upcoming release milestone, along with the following checklist. -Before running the script, please manually check the assignment of issues to the milestone. -This should be run one month prior to planned release. +Os(as) editores(as) que estão se preparando para um lançamento podem executar o script `prelease.R` na pasta `inst` deste repositório para abrir automaticamente um problema no GitHub com os pontos de verificação para todos os problemas atuais atribuídos ao marco da próxima versão, juntamente com a seguinte lista de verificação. +Antes de executar o script, verifique manualmente a atribuição de problemas ao marco. +Isso deve ser executado um mês antes do lançamento planejado. ::: {.content-hidden when-format="pdf"} @@ -14,7 +14,7 @@ This should be run one month prior to planned release. ```{r} #| results: 'asis' #| echo: false -#| child: "templates/book-release.md" +#| child: "templates/book-release.pt.md" ``` ```` @@ -23,7 +23,7 @@ This should be run one month prior to planned release. ::: {.content-visible when-format="pdf"} ```{r} -#| child: "templates/book-release.md" +#| child: "templates/book-release.pt.md" ``` diff --git a/pkg_building.Rmd b/pkg_building.Rmd index 86b736d7c..c2b31c8a1 100644 --- a/pkg_building.Rmd +++ b/pkg_building.Rmd @@ -193,7 +193,7 @@ where issue\_id is the number of the issue in the software-review repository. Fo - If there is potential overlap or confusion with other packages providing similar functionality or having a similar name, add a note in the README, main vignette and potentially the Description field of DESCRIPTION. Examples in [rtweet README](https://docs.ropensci.org/rtweet/), [rebird README](https://docs.ropensci.org/rebird/#auk-vs-rebird), and the non-rOpensci package [slurmR](https://uscbiostats.github.io/slurmR/index.html#vs). -- The package should contain top-level documentation for `?foobar`, (or ``?`foobar-package` `` if there is a naming conflict). Optionally, you can use both `?foobar` and ``?`foobar-package` `` for the package level manual file, using `@aliases` roxygen tag. `usethis::use_package_doc()` adds the template for the top-level documentation. +- The package should contain top-level documentation for `?foobar`, (or ``?`foobar-package` `` if there is a naming conflict). Optionally, you can use both `?foobar` and ``?`foobar-package` `` for the package level manual file, using `@aliases` roxygen tag. [`usethis::use_package_doc()`](https://usethis.r-lib.org/reference/use_package_doc.html) adds the template for the top-level documentation. - The package should contain at least one **HTML** vignette providing a substantial coverage of package functions, illustrating realistic use cases and how functions are intended to interact. If the package is small, the vignette and the README may have very similar content. @@ -215,14 +215,12 @@ The general vignette should present a series of examples progressing in complexi ### roxygen2 use {#roxygen-2-use} -- We request all submissions to use `roxygen2` for documentation. `roxygen2` is [an R package](https://cran.r-project.org/web/packages/roxygen2/index.html) that automatically compiles `.Rd` files to your `man` folder in your package from simple tags written above each function. +- We request all submissions to use [roxygen2](https://roxygen2.r-lib.org/) for documentation. roxygen2 is an R package that automatically compiles `.Rd` files to your `man` folder in your package from simple tags written above each function. -- More information on using roxygen2 [documentation](https://r-pkgs.org/man.html) is available in the R packages book. +- More information on using roxygen2 documentation is available in the [R packages book](https://r-pkgs.org/man.html) and in [roxygen2 website itself](https://roxygen2.r-lib.org/). One key advantage of using roxygen2 is that your `NAMESPACE` will always be automatically generated and up to date. - If you were writing Rd by hand, the [Rd2roxygen](https://cran.r-project.org/web/packages/Rd2roxygen/index.html) package contains functions to convert Rd to roxygen documentation. -- One key advantage of using `roxygen2` is that your `NAMESPACE` will always be automatically generated and up to date. - - All functions should document the type of object returned under the `@return` heading. - The default value for each parameter should be clearly documented. For example, instead of writing `A logical value determining if ...`, you should write ``A logical value (default `TRUE`) determining if ...``. It is also good practice to indicate the default values directly in your function definition: @@ -233,21 +231,15 @@ f <- function(a = TRUE) { } ``` -- Documentation should support user navigation by including useful cross-links between related functions and documenting related functions together in groups or in common help pages. The `@seealso` and `@family` tags (the latter of which automatically creates "See also" links and [can help group](https://pkgdown.r-lib.org/reference/build_reference.html) functions together on pkgdown sites), are recommended for this purpose. See [the "manual" section of The R Packages book](https://r-pkgs.org/man.html) and [the "function grouping" section of the present chapter](#function-grouping) for more details. +- Documentation should support user navigation by including useful [cross-links](https://roxygen2.r-lib.org/reference/tags-index-crossref.html) between related functions and documenting related functions together in groups or in common help pages. In particular, the `@family` tags, that automatically creates "See also" links and [can help group](https://pkgdown.r-lib.org/reference/build_reference.html) functions together on pkgdown sites, is recommended for this purpose. See [the "manual" section of The R Packages book](https://r-pkgs.org/man.html) and [the "function grouping" section of the present chapter](#function-grouping) for more details. -- You could re-use documentation pieces (e.g. details about authentication, related packages) across the vignettes/README/man pages. A possible approach for that is the use of [R Markdown fragments, relying on knitr use of child documents so you can store the re-used parts in a folder in man/, and call them from both the README and the vignette](https://www.garrickadenbuie.com/blog/dry-vignette-and-readme/) as well [as in man pages by using the `@includeRmd` tag available from `roxygen 0.7.0`](https://roxygen2.r-lib.org/articles/rd.html#including-external--rmd-md-files). +- You can re-use documentation pieces (e.g. details about authentication, related packages) across the vignettes/README/man pages. Refer to [roxygen2 vignette on documentation reuse](https://roxygen2.r-lib.org/articles/reuse.html). -- Add `#' @noRd` to internal functions. +- For including examples, you can use the classic `@examples` tag (plural "examples") but also the `@example ` tag (singular "example") for storing the example code in a separate R script (ideally under `man/`), and the `@exampleIf` tag for running examples conditionally and avoiding R CMD check failures. Refer to [roxygen2 documentation about examples](https://roxygen2.r-lib.org/articles/rd.html#examples). -- If you prefer not to clutter up code with extensive documentation, you can place further examples outside of the R script and use the `@example` tag; and you place further documentation in files in a `man-roxygen` folder in the root of your package, and those will be combined into the manual file by the use of `@template `, for example. - - - Put any documentation for an object in a `.R` file in the `man-roxygen` folder (at the root of your package). For example, [this file](https://github.com/ropensci/rgbif/blob/master/man-roxygen/occ_search_egs.R). Link to that template file from your function ([e.g.](https://github.com/ropensci/rgbif/blob/master/R/occ_search.r)) with the `@template` keyword ([e.g.](https://github.com/ropensci/rgbif/blob/master/R/occ_search.r#L7)). The contents of the template will be inserted when documentation is built into the resulting `.Rd` file that users will see when they ask for documentation for the function. - - Note that if you are using markdown documentation, markdown currently doesn't work in template files, so make sure to use latex formatting. - - In most cases you can ignore templates and `man-roxygen`, but there are two cases in which leveraging them will greatly help: - 1. When you have a lot of documentation for a function/class/object separating out certain chunks of that documentation can keep your `.R` source file tidy. This is especially useful when you have a lot of code in that `.R` file. On the other hand, it means the docs are not readable "in-source" since they're in another file. - 2. When you have the same documentation parts used across many `.R` functions it's helpful to use a template. This reduces duplicated text, and helps prevent mistakenly updating documentation for one function but not the other. Using a template file for a parameter documentation is an alternative to defining the parameter for one function and using `@inheritParams` for other functions using the same parameter. +- Add `#' @noRd` to internal functions. You might be interested in the [devtag experimental package](https://github.com/moodymudskipper/devtag) for getting local manual pages when using `#' @noRd`. -- Starting from `roxygen2` version 7.0.0, `R6` classes are officially supported. See the [roxygen2 docs](https://roxygen2.r-lib.org/articles/rd.html#r6) for details on how to document `R6` classes. +- Starting from roxygen2 version 7.0.0, `R6` classes are officially supported. See the [roxygen2 docs](https://roxygen2.r-lib.org/articles/rd-other.html#r6) for details on how to document `R6` classes. ### URLs in documentation {#ur-ls-in-documentation} @@ -274,7 +266,7 @@ Before submission and before transfer, you could use the [approach documented by When your package has many functions, use grouping in the reference, which you can do more or less automatically. -If you use `roxygen2` above version 6.1.1, you should use the `@family` tag in your functions documentation to indicate grouping. This will give you links between functions in the local documentation of the installed package ("See also" section) *and* allow you to use the `pkgdown` `has_concept` function in the config file of your website. Non-rOpenSci example courtesy of [`optiRum`](https://github.com/lockedata/optiRum): [family tag](https://github.com/lockedata/optiRum/blob/master/R/APR.R#L17), [`pkgdown` config file](https://github.com/lockedata/optiRum/blob/master/_pkgdown.yml) and [resulting reference section](https://itsalocke.com/optirum/reference/). +If you use roxygen2 above version 6.1.1, you should use the `@family` tag in your functions documentation to indicate grouping. This will give you links between functions in the local documentation of the installed package ("See also" section) *and* allow you to use the `pkgdown` `has_concept` function in the config file of your website. Non-rOpenSci example courtesy of [`optiRum`](https://github.com/lockedata/optiRum): [family tag](https://github.com/lockedata/optiRum/blob/master/R/APR.R#L17), [`pkgdown` config file](https://github.com/lockedata/optiRum/blob/master/_pkgdown.yml) and [resulting reference section](https://itsalocke.com/optirum/reference/). To customize the text of the cross-reference title created by roxygen2 (`Other {family}:`), refer to [roxygen2 docs regarding how to provide a `rd_family_title` list in `man/roxygen/meta.R`](https://roxygen2.r-lib.org/articles/rd.html#cross-references). Less automatically, see the example of [`drake` website](https://docs.ropensci.org/drake/) and [associated config file @@ -374,7 +366,7 @@ For more explanations around licensing, refer to the [R packages book](https://r ## Package dependencies {#pkgdependencies} -- Use `Imports` instead of `Depends` for packages providing functions from other packages. Make sure to list packages used for testing (`testthat`), and documentation (`knitr`, `roxygen2`) in your `Suggests` section of package dependencies (if you use `usethis` for adding testing infrastructure via [`usethis::use_testthat()`](https://usethis.r-lib.org/reference/use_testthat.html) or a vignette via [usethis::use\_vignette()](https://usethis.r-lib.org/reference/use_vignette.html), the necessary packages will be added to `DESCRIPTION`). If you use any package in the examples or tests of your package, make sure to list it in `Suggests`, if not already listed in `Imports`. +- Use `Imports` instead of `Depends` for packages providing functions from other packages. Make sure to list packages used for testing (`testthat`), and documentation (`knitr`, roxygen2) in your `Suggests` section of package dependencies (if you use `usethis` for adding testing infrastructure via [`usethis::use_testthat()`](https://usethis.r-lib.org/reference/use_testthat.html) or a vignette via [usethis::use\_vignette()](https://usethis.r-lib.org/reference/use_vignette.html), the necessary packages will be added to `DESCRIPTION`). If you use any package in the examples or tests of your package, make sure to list it in `Suggests`, if not already listed in `Imports`. - If your (not Bioconductor) package depends on Bioconductor packages, make sure the installation instructions in the README and vignette are clear enough even for an user who is not familiar with the Bioconductor release cycle. diff --git a/pkg_building.es.Rmd b/pkg_building.es.Rmd index f3979f264..a8503379d 100644 --- a/pkg_building.es.Rmd +++ b/pkg_building.es.Rmd @@ -206,7 +206,7 @@ La etiqueta indicará primero "en revisión" y luego "revisado" una vez que tu p - El paquete debe contener la documentación general del paquete para `?paquete` (o ``?`paquete-package``` si hay un conflicto de nombres). Opcionalmente, puedes utilizar tanto `?paquete` como ``?`paquete-package``` para el archivo del manual del paquete utilizando la etiqueta `@aliases` de roxygen. - `usethis::use_package_doc()` añade la plantilla para generar la documentación general. + [`usethis::use_package_doc()`](https://usethis.r-lib.org/reference/use_package_doc.html) añade la plantilla para generar la documentación general. - El paquete debe contener al menos una viñeta en formato **HTML** que cubra una parte importante de las funciones del paquete, ilustrando casos de uso realistas y cómo se supone que las funciones interactúen entre ellas. Si el paquete es pequeño, la viñeta y el *README* pueden tener un contenido muy similar. @@ -236,15 +236,13 @@ La viñeta general debe presentar una serie de ejemplos que progresen en complej ### Uso de roxygen2 {#roxygen-2-use} -- Pedimos que todos los paquetes que se presenten para revisión utilicen `roxygen2` para generar la documentación. - `roxygen2` es [un paquete de R](https://cran.r-project.org/web/packages/roxygen2/index.html) que compila automáticamente archivos `.Rd` en la carpeta `man` del paquete utilizando etiquetas incluidas antes de cada función. +- Pedimos que todos los paquetes que se presenten para revisión utilicen [roxygen2](https://roxygen2.r-lib.org/) para generar la documentación. + roxygen2 es un paquete de R que compila automáticamente archivos `.Rd` en la carpeta `man` del paquete utilizando etiquetas incluidas antes de cada función. Una ventaja clave de utilizar roxygen2 es que tu archivo `NAMESPACE` siempre se generará automáticamente y estará actualizado. -- Más información sobre el uso de roxygen2 para generar documentación está disponible [en el libro *R Packages*](https://r-pkgs.org/man.html). +- Más información sobre el uso de roxygen2 para generar documentación está disponible [en el libro *R Packages*](https://r-pkgs.org/man.html) y en [el sitio web de roxygen2](https://roxygen2.r-lib.org/). - Si escribiste los archivos .Rd a mano, el paquete [Rd2roxygen](https://cran.r-project.org/web/packages/Rd2roxygen/index.html) contiene funciones para convertir la documentación de Rd a documentación de roxygen2. -- Una ventaja clave de utilizar `roxygen2` es que tu archivo `NAMESPACE` siempre se generará automáticamente y estará actualizado. - - Todas las funciones deben documentar el tipo de objeto devuelto bajo el encabezado `@return`. - El valor por defecto de cada parámetro debe estar claramente documentado. @@ -258,26 +256,18 @@ f <- function(a = TRUE) { ``` - La documentación debe ayudar a la navegación incluyendo links entre funciones relacionadas y agrupando la documentación de funciones relacionadas en página de ayuda comunes. - Para esto recomendamos las etiquetas `@seealso` y `@family` (esta última crea automáticamente enlaces "See also" y [puede agrupan las funciones](https://pkgdown.r-lib.org/reference/build_reference.html) en sitios web generados con pkgdown). + Para esto recomendamos la etiqueta `@seealso`, que crea automáticamente enlaces _"See also"_ (ver también, en inglés) y [puede agrupan las funciones](https://pkgdown.r-lib.org/reference/build_reference.html) en sitios web generados con pkgdown. Consulta [la sección "manual" del libro *R Packages*](https://r-pkgs.org/man.html) y [la sección "Agrupación de funciones" de este capítulo](#function-grouping) para más detalles. - Puedes reutilizar partes de la documentación (por ejemplo, detalles sobre la autenticación, paquetes relacionados) en las viñetas, *README* y páginas de manual. - Una forma de hacerlo es [usando fragmentos de R Markdown](https://www.garrickadenbuie.com/blog/dry-vignette-and-readme/). - Usando "documentos hijos" con kintr puedes guardar fragmentos de código en la carpeta `man` y reutilizarlos en el *README*, las viñetas y la documentación (usando la etiqueta `@includeRmd`, [disponible desde la versión 0.7.0 de roxygen2](https://roxygen2.r-lib.org/articles/rd.html#including-external--rmd-md-files)). - -- Añade `#' @noRd` a las funciones internas. - -- Si prefieres no abarrotar el código con una documentación muy larga, puedes colocar más ejemplos fuera del *script* de R. - Coloca la documentación extra en archivos en la carpeta `man-roxygen` en la raiz de tu paquete e insértala en el archivo de ayuda con `@template ` debajo de la etiqueta `@example`. + Consulta la [viñeta de roxygen2 sobre la reutilización de documentación](https://roxygen2.r-lib.org/articles/reuse.html). - - Coloca la documentación de cualquier objeto en un archivo `.R` en la carpeta `man-roxygen` (en la raíz de tu paquete). Por ejemplo [este archivo](https://github.com/ropensci/rgbif/blob/master/man-roxygen/occ_search_egs.R). Vincula ese archivo de plantilla desde el código de tu función ([por ejemplo](https://github.com/ropensci/rgbif/blob/master/R/occ_search.r)) con la etiqueta `@template` ([por ejemplo](https://github.com/ropensci/rgbif/blob/master/R/occ_search.r#L7)). El contenido de la plantilla se insertará cuando se construya la documentación en el archivo resultante `.Rd` que se mostrará al acceder a la documentación de la función. - - Ten en cuenta que actualmente el formato de markdown no funciona en las plantillas, así que asegúrate de utilizar formato LaTeX. - - En la mayoría de los casos puedes ignorar las plantillas y `man-roxygen` pero hay dos casos en los que aprovecharlos será de gran ayuda: - 1. Si tienes mucha documentación en una función, clase u objeto, separar ciertos trozos de esa documentación puede mantener tu archivo `.R` ordenado. Esto es especialmente útil cuando tienes mucho código en ese archivo `.R`. Por otro lado, significa que la documentación no será legible "en el código fuente", ya que estará en otro archivo. - 2. Cuando utilizas la misma documentación en muchas funciones y archivos `.R` es útil utilizar una plantilla. Esto reduce el texto duplicado y ayuda a evitar que por error se actualice la documentación de una función pero no la de otra. Utilizar un archivo de plantilla para la documentación de un parámetro es una alternativa a definir el parámetro para una función y utilizar `@inheritParams` para otras funciones que utilicen el mismo parámetro. +- Para incluir ejemplos, puedes utilizar el clásico `@examples` (en plural _"examples"_), pero también la etiqueta `@example ` (en singular _"example"_) para almacenar el código de ejemplo en un script R independiente (idealmente en `man/`), y la etiqueta `@exampleIf` para ejecutar ejemplos condicionalmente y evitar fallos de `R CMD check`. Consulta [la documentación de roxygen2 sobre ejemplos](https://roxygen2.r-lib.org/articles/rd.html#examples). + +- Añade `#' @noRd` a las funciones internas. Quizá te interese el [paquete experimental devtag](https://github.com/moodymudskipper/devtag) para obtener páginas de manual locales al utilizar `#' @noRd`. -- A partir de la versión 7.0.0 de `roxygen2`, las clases `R6` son oficialmente compatibles. - Consulta la [documentación de roxygen2](https://roxygen2.r-lib.org/articles/rd.html#r6) para saber cómo documentar las clases `R6`. +- A partir de la versión 7.0.0 de roxygen2, las clases `R6` son oficialmente compatibles. + Consulta la [documentación de roxygen2](https://roxygen2.r-lib.org/articles/rd-other.html#r6) para saber cómo documentar las clases `R6`. ### URLs en la documentación {#ur-ls-in-documentation} @@ -313,7 +303,7 @@ En cualquier caso, no olvides actualizar la URL del sitio web en todos los lados Cuando tu paquete tenga muchas funciones, es conveniente que aparezcan agrupadas en el índice de la documentación, lo cual se puede hacer de forma más o menos automática. -Si utilizas `roxygen2` versión 6.1.1 o mayor, puedes utilizar la etiqueta `@family` en la documentación de tus funciones para indicar un grupo al que pertenecen. +Si utilizas roxygen2 versión 6.1.1 o mayor, puedes utilizar la etiqueta `@family` en la documentación de tus funciones para indicar un grupo al que pertenecen. Esto generará enlaces las funciones en la documentación local del paquete instalado (en la sección "See also") *y* te permitirá utilizar la función `has_concept` de `pkgdown` en el archivo de configuración de tu sitio web. Puedes ver un ejemplo (de un paquete no perteneciente a rOpenSci) cortesía de [`optiRum`](https://github.com/lockedata/optiRum): [etiqueta family](https://github.com/lockedata/optiRum/blob/master/R/APR.R#L17), [archivo de configuración de `pkgdown`](https://github.com/lockedata/optiRum/blob/master/_pkgdown.yml) y [la sección en el índice resultante](https://itsalocke.com/optirum/reference/). Para personalizar el texto del título de la referencia cruzada creada por roxygen2 (`Other {family}:`), puedes consultar la documentación de [roxygen2 sobre cómo proporcionar una lista `rd_family_title` en `man/roxygen/meta.R`](https://roxygen2.r-lib.org/articles/rd.html#cross-references). @@ -447,7 +437,7 @@ Para más detalles sobre las licencias, consulta el libro [R packages](https://r ## Dependencias del paquete {#pkgdependencies} - Utiliza la sección `Imports` en lugar de `Depends` para listar los paquetes cuyas funciones usas en tu paquete. - Utiliza sección `Suggests` para listar los paquetes que usas en los *tests* (`testthat`), y para generar la documentación (`knitr`, `roxygen2`) (si utilizas `usethis` para añadir la infraestructura de *tests* con [`usethis::use_testthat()`](https://usethis.r-lib.org/reference/use_testthat.html) o una viñeta mediante [usethis::use\_vignette()](https://usethis.r-lib.org/reference/use_vignette.html) los paquetes necesarios se añadirán a `DESCRIPTION`). + Utiliza sección `Suggests` para listar los paquetes que usas en los *tests* (`testthat`), y para generar la documentación (`knitr`, roxygen2) (si utilizas `usethis` para añadir la infraestructura de *tests* con [`usethis::use_testthat()`](https://usethis.r-lib.org/reference/use_testthat.html) o una viñeta mediante [usethis::use\_vignette()](https://usethis.r-lib.org/reference/use_vignette.html) los paquetes necesarios se añadirán a `DESCRIPTION`). Si utilizas algún paquete en los ejemplos o *tests* de tu paquete, asegúrate de listarlo en `Suggests` si no aparece ya en `Imports`. - Si tu paquete no está en Bioconductor pero depende de paquetes de Bioconductor, asegúrate de que las instrucciones de instalación en el *README* y la viñeta sean lo suficientemente claras incluso para una persona que no esté familiarizada con el ciclo de publicación de Bioconductor. diff --git a/templates/book-release.pt.md b/templates/book-release.pt.md new file mode 100644 index 000000000..765796685 --- /dev/null +++ b/templates/book-release.pt.md @@ -0,0 +1,41 @@ +## Versão de lançamento do livro + +### Manutenção do repositório entre lançamentos + +- [ ] Consulte a página de problemas para [o guia dev](https://github.com/ropensci/dev_guide/issues) e também para o repositório [de revisões de software](https://github.com/ropensci/software-review-meta/issues), procure por mudanças que ainda devem ser feitas no guia dev. Atribua os problemas encontrados no guia dev ao marco correspondente às versões, seja esta a próxima versão, ou, às versões seguintes, e.g [versão 0.3.0](https://github.com/ropensci/dev_guide/milestone/2). Encoraje novos PRs e revise eles. + +### 1 mês antes do lançamento + +- [ ] Lembre os editores de abrirem problemas/PRs para itens que desejam ver na próxima versão. + +- [] Execute [a função `devguide_prerelease()`](https://github.com/ropensci-org/devguider) do pacote `devguider`. + +- [ ] Peça aos(às) editores(as) por qualquer feedback que você precise antes do lançamento. + +- [ ] Para cada contribuição/alteração verifique se as NOTÍCIAS no arquivo `Appendix.Rmd` foram atualizadas. + +- [ ] Planeje uma data para o lançamento e se comunique com o/a gerente da comunidade da rOpenSci, que lhe dará uma data para publicar uma postagem no blog (ou nota técnica). + + +### 2 semanas antes do lançamento + +- [ ] Escreva um rascunho para uma postagem de blog (ou nota técnica) sobre o lançamento com antecedência suficiente para que os(as) editores(as) e, em seguida, o(a) gerente da comunidade, possam revisá-lo (2 semanas). [Exemplo](https://github.com/ropensci/roweb3/pull/291), [instruções gerais para a postagem no blog](https://blogguide.rpensci.org/), [instruções específicas para as postagens de lançamento](#releaseblogpost). + +- [] Crie um PR a partir da branch `dev` para a branch `master` e, em seguida, comunique aos editores através do GitHub e do Slack. Mencione o rascunho da postagem do blog em um comentário dentro deste PR. + +### Lançamento + +- [] Verifique as URLs usando [a função `devguide_urls()` do pacote {devguider}](https://github.com/ropensci-org/devguider) + +- [] Verifique a ortografia usando [a função `devguide_spelling()` do pacote {devguider}](https://github.com/rpensci-org/devguider). Atualize também a [WORDLIST](https://github.com/ropensci/dev_guide/blob/master/inst/WORDLIST) conforme necessário. + +- [ ] Realize um squash sobre os seus commits para o PR de `dev` para `master`. + +- [ ] Atualize a página de *release* do GitHub, e confira a página de *release* do Zenodo. + +- [ ] Reconstrua (para atualizar os metadados do livro no Zenodo) ou aguarde o processo diário de construção do livro. + +- [ ] Crie novamente a branch `dev`. + +- [ ] Conclua o PR com a sua postagem de blog (ou nota técnica). Destaque os aspectos mais importantes a serem destacados em tweets (e publicações) como parte da discussão do PR. +