{attachment} v0.4.0: Breaking changes and configuration file for a better experience

You can read the original post in its original format on Rtask website by ThinkR here: {attachment} v0.4.0: Breaking changes and configuration file for a better experience

{attachment} v0.4.0 stores your parameters in a configuration file for an easier use during your package development: run att_amend_desc() from anywhere, it will re-use your last set of parameters.  This comes with some breaking changes for a better experience.

The goal of attachment is to help to deal with package dependencies during package development. It also gives useful tools to install or list missing packages used inside Rscripts, Rmds or qmd. This reads your NAMESPACE, your functions in R directory and your vignettes, then update the DESCRIPTION file accordingly. Are you ready to be lazy ? Let {attachment} help you !

Installation

{attachment} is available on CRAN and developed on GitHub. You can access the full documentation website on this page: https://thinkr-open.github.io/attachment. It also appears on the ThinkR r-universe page if you want to install the development version without GitHub API constraints.

Install CRAN version

install.packages("attachment")

Install development version

install.packages('attachment', repos = c('https://thinkr-open.r-universe.dev', 'https://cloud.r-project.org'))

Declare all dependencies in DESCRIPTION during package development

What you really want is to fill and update your description file along with the modifications of your documentation. Indeed, only the following function will really be called. Use and abuse during the development of your package !

attachment::att_amend_desc()

{attachment} detects all calls to library(pkg), @importFrom pkg fun, pkg::fun() in the different classical directories of your R package, then list them in the correct “Imports” or “Suggests” category in the DESCRIPTION file, according to their position in the package.

Declare extra dependencies for extra uses

If you want to add extra packages like {pkgdown} or {covr} that are not listed in any script in your package, a call for your development packages would be:

attachment::att_amend_desc(extra.suggests = c("pkgdown", "covr"), update.config = TRUE)

Note the update.config = TRUE parameter that will save the parameters used in the call of att_amend_desc() to the package configuration file: “dev/config_attachment.yaml”.

If you run att_amend_desc() a second time afterwards, directly from the console, it will use the last set of parameters extracted from the configuration file.

Indeed, we recommend to store the complete command line in a “dev/dev_history.R” file to update and run it when needed. If the parameters do not change, you can run attachment::att_amend_desc() directly in the console, wherever you are, it will use the configuration file.

Automatically fill the “Remotes” field

If you would like to detect the sources of your installations so that you can add dependencies in the “Remotes” field of your DESCRIPTION file, to mimic your local installation, you will use:

attachment::set_remotes_to_desc()

Combination of {attachment} with {fusen}

The configuration file of {attachment} was originally developed for a better integration with {fusen}. Indeed, when you inflate() your notebook file into a fully documented R package, {fusen} automatically runs attachment::att_amend_desc() to update your documentation and the list of dependencies of your package. However, until now, it was not possible to use extra parameters in the inflate() function to be used by {attachment}, and you had to stop the automatic detection with document = FALSE, then run your specific {attachment} code from somewhere else.

As we are all lazy, we do not want to change file each time we have to introduce a new changes in our package. With the configuration file of {attachment}, you can let your fusen::inflate() as is, and it will use the last version of attachment::att_amend_desc() according to what’s in the configuration file.  If you want to change the default parameters, by adding extra dependencies for instance, you will have to change the configuration file only once. To do so, you’ll surely want to update your “dev/0-dev_history.Rmd” file with this code to run once:

attachment::att_amend_desc(extra.suggests = c("pkgdown", "covr"), update.config = TRUE)

NEWS content

Breaking changes

• When using att_amend_desc() without the default parameters, like pkg_ignore = "x" will now require att_amend_desc(pkg_ignore = "x", update.config = TRUE), otherwise, it will fail. This allows for the use of parameters stored in the config file when running att_amend_desc() directly in the console.
  Recommendation: Run att_amend_desc(pkg_ignore = "x", update.config = TRUE) if you have to update your config, run att_amend_desc() daily as you’ll want to use what is stored in the config file.
• create_dependencies_file() gets parameter install_only_if_missing = FALSE by default to complete the installation instructions packages only if missing. (@MurielleDelmotte)

New features

• att_amend_desc() can run with the last set of parameters stored in a configuration file, without having to call them all each time. See vignettes and documentation of parameters update.config = FALSE, use.config = FALSE and path.c = "dev/config_attachment.yaml". (@dagousket)
• create_dependencies_file() now takes other sources into account (git, gitlab, github, bioc, local). (@MurielleDelmotte)
• Use create_dependencies_file(to = NULL) to only get the output as character and do not create a file

Bug fixes

• att_amend_desc() does not modify user options("warn") level anymore (#94)
• att_amend_desc() allows “Remotes” field to contain @ref (#67)

This post is better presented on its original ThinkR website here: {attachment} v0.4.0: Breaking changes and configuration file for a better experience