Maintain packages with {fusen}


Daily use of {fusen}

Add a new set of chunks in the current Rmd

Use the Addin “Add {fusen} chunks”

Create a new flat Rmd template

To add a new family of functions, create a new flat Rmd template

add_flat_template(template = "add")
# or directly

How to maintain a {fusen}? Can I use {fusen} with old-way packages ?

After you inflate() the “flat_template.Rmd”, your code appears twice in the package. In the “flat_template.Rmd” itself and in the correct place for it to be a package. Take it as a documentation for the other developers.
Maintaining such a package requires a choice:

Your first inflate() may not directly work as expected as with any R code that you write. In this case, you can continue to implement your functionality using Option 1.

Advice 1: Use Option 1 until you find it too complicated to be used ! I assure you, you will find the moment when you say : ok this is not possible anymore…

Advice 2: Use git as soon as possible, this will avoid losing your work if you made some modifications in the wrong place

Advice 3: Create a Readme.Rmd in the “dev/” directory with a chunk having fusen::draw_package_structure() and knit it. This will help to understand the structure of your package and see what is inflated or not. Have a look at the {fusen} package itself on GitHub to see how it looks like.

Option 1: Continue with the “flat_template.Rmd”

=> {fusen} itself is built as is. Each modification is added to the dedicated dev_history file and then inflated => The tree structure in the “dev/” file is very useful to understand what is inflated or not, and to see the structure of the package

Option 2: Maintain like a classical package

You can use deprecate_flat_file() to protect the original flat template file, so that you never use it again. Inflated files are also unprotected, so that you can modify them directly.

=> This is the way I add new functionalities in packages that started in the old way, and in specific cases where inflating is now too complicated, like for function inflate() and all its unit tests in this very {fusen} package.

What about packages already built the old way ?

The “flat_template.Rmd” template only modifies files related to functions presented inside the template. This does not remove or modify previous functions, tests or vignettes, provided that names are different.

Let’s try to convince package developers with an example

#' My median
#' @param x Vector of Numeric values
#' @inheritParams stats::median
#' @return
#' Median of vector x
#' @export
#' @examples
my_median <- function(x, na.rm = TRUE) {
  if (!is.numeric(x)) {
    stop("x should be numeric")
  stats::median(x, na.rm = na.rm)
test_that("my_median works properly and show error if needed", {
  expect_true(my_median(1:12) == 6.5)

That’s it!
You added a new function in your package, along with example, test and a new vignette:

Compare a classical way of building packages with the {fusen} way

Classical with {devtools} With {fusen}

- File > New Project > New directory > Package with devtools
  + Or devtools::create()

- File > New Project > New directory > Package with {fusen}
 + Or fusen::create_fusen()

- Open “DESCRIPTION” file
- Write your information
- Run function for the desired license in the console
  + usethis::use_*_license()

- Fill your information in the opened flat file
- Execute the chunk description

- Create and open a file for your functions in “R/”
   + usethis::use_r("my_fonction")
- Write the code of your function
- Write a reproducible example for your function

- Open DESCRIPTION file and fill the list of dependencies required

- Create and open a new file for your tests in “tests/testthat/”
   + usethis::use_testthat()
   + usethis::use_test("my_fonction")
- Write some unit tests for your function

- Create and open a new file for a vignette in “vignettes/”
   + usethis::use_vignette("Vignette title")

- Open DESCRIPTION file and fill the list of “Suggests” dependencies required

- Write code, examples and test in the unique opened flat file

- Generate documentation
 + Either attachment::att_amend_desc()
 + Or roxygen2::roxygenise()

- Check the package
 + devtools::check() => 0 errors, 0 warnings, 0 notes

- Inflate your flat file
 + Execute fusen::inflate() in the last “development” chunk
=> For one function, you need to switch regularly between 4 files => For one function, you need only one file