Releasing packages

layout: true

<div class="my-footer">
<a id="link" href="https://packages2archives.llrs.dev" style="position:absolute; left:2.5%">
packages2archives.llrs.dev</a>
<a href="https://twitter.com/Lluis_Revilla" style="position:absolute; left:45%"> Lluis_Revilla <svg viewBox="0 0 512 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg">
 <path d="M459.37 151.716c.325 4.548.325 9.097.325 13.645 0 138.72-105.583 298.558-298.558 298.558-59.452 0-114.68-17.219-161.137-47.106 8.447.974 16.568 1.299 25.34 1.299 49.055 0 94.213-16.568 130.274-44.832-46.132-.975-84.792-31.188-98.112-72.772 6.498.974 12.995 1.624 19.818 1.624 9.421 0 18.843-1.3 27.614-3.573-48.081-9.747-84.143-51.98-84.143-102.985v-1.299c13.969 7.797 30.214 12.67 47.431 13.319-28.264-18.843-46.781-51.005-46.781-87.391 0-19.492 5.197-37.36 14.294-52.954 51.655 63.675 129.3 105.258 216.365 109.807-1.624-7.797-2.599-15.918-2.599-24.04 0-57.828 46.782-104.934 104.934-104.934 30.213 0 57.502 12.67 76.67 33.137 23.715-4.548 46.456-13.32 66.599-25.34-7.798 24.366-24.366 44.833-46.132 57.827 21.117-2.273 41.584-8.122 60.426-16.243-14.292 20.791-32.161 39.308-52.628 54.253z"></path>
</svg></a></div>

---
name: title-slide
class: center, middle
background-image: url("index_files/figure-html/title_slide_background.png")
background-size: contain
background-position: bottom

.top[
# Releasing packages
]

**For R User Group Ghana on their 3rd anniversary**

[Lluís Revilla Sancho](https://llrs.dev)  
[IDIBAPS](https://www.clinicbarcelona.org/en/idibaps), [CIBEREHD](https://www.ciberehd.org/en)

2022/01/16

.minor[.minor[(updated: 2022-01-15 )]]

---
name:index

# Index

.pull-left[

- [Creating good packages](#good-packages).

- [Releasing packages](#release-packages).

- [Maintaining packages.](#maintaining-packages)

]

???

Creating packages based on the [previous workshop](https://llrs.dev/talk/workshop-creating-packages/) for this user group.

Release process based on the [useR!2021 talk](https://llrs.dev/talk/user-2021/)

Maintaining packages based on the [archived packages files.](https://llrs.dev/post/2021/12/07/reasons-cran-archivals/)

.pull-right[
![](https://c.tenor.com/abY7c2fitNIAAAAC/thumb-okay.gif)
]

---
name:good-packages
class: bold-last-item
# Creating good packages

> Packages provide a mechanism for loading optional code, data and documentation as needed.

.center[Code]

???

Most common usage

.center[Data]

???

Less used due to restrictions on size on CRAN

.center[Documentation]

???

In my opinion the most important aspect.

---
name:resources

## Resources

- **[R extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html "Offical complete instructions")**: Official documentation, everything is answered here
- **[R packages](https://r-pkgs.org/ "R packages")**: A book more digestible and using other packages and tools to create packages.
- [Package primer](https://kbroman.org/pkg_primer/ "R package primer a minimal tutorial"): Website explaining different aspects of creating a package.
- [Creating R packages from scratch](https://hilaryparker.com/2014/04/29/writing-an-r-package-from-scratch/ "Creating a cats package"): Very easy to follow blog post.
- [Updated version by Tomas Westlake](https://r-mageddon.netlify.app/post/writing-an-r-package-from-scratch/ "Creating a cats package with usethis"): Similar to the post above but with more modern tools.
- **[rOpenSci](https://devguide.ropensci.org/)**: A book  about writing packages and maintaining them on good shape.
- [Video](https://www.youtube.com/watch?v=IlWMkz769B4) with a similar workshop showing live the code used.

**Many resources!**

.center[

You can also find help online (always check the etiquette)

Asking your local community: R User Group Ghana  
[Asking on Twitter #rstats](https://www.t4rstats.com/)  
[Asking on Stack Overflow](https://stackoverflow.com/questions/5963269)  
[Asking on RStudio forum](https://community.rstudio.com/)

]
???

Resources used to create this workshop

[Maëlle post](https://masalmon.eu/2017/12/11/goodrpackages/): how to write good packages is also recommended.

---

## Structure

.left-column[

]

.right-column[

- A `.github` folder: Files specific to GitHub (this isn't necessary/[Advanced content](https://ghana.llrs.dev/#advanced))  
- A **R folder with [*.R files](https://ghana.llrs.dev/#r-files)**: your code.  
- A `man` folder with [*.rd files](https://ghana.llrs.dev/#rd-files): your documentation.  
- A `tests` folder: [Check the code](https://ghana.llrs.dev/#tests) of the package.  
- A [`vignette` folder](https://ghana.llrs.dev/#vignettes): Long documentation; not just examples.  
- A `.Rbuildignore`: A file describing what to omit when building the package.  
- A __[`DESCRIPTION` file](https://ghana.llrs.dev/#description)__: Summary and description of the package.  
- A [`LICENSE` file](https://ghana.llrs.dev/#licenses): The conditions under the package is released.  
- A __[`NAMESPACE` file](https://ghana.llrs.dev/#namespace)__: What this package shares and needs.  
- A [`NEWS` file](https://ghana.llrs.dev/#news): What has changed since last release.  
- A [`README`](https://ghana.llrs.dev/#readme): How to install and why this packages is needed and some basic examples.

]

---
name: description

## DESCRIPTION

.pull-left[

```
Package: my_package
Title: Short Descriptiono in Title Case
Version: 0.0.9000
Authors@R: c(person(given = "Name",
             role = c("aut", "cre", "cph"),
             email = "my@email.com"),
             ...)
Description: A long description of the package
License: MIT + file LICENSE
Depends: 
    R (>= 4.1.2)
Imports: 
    methods
Suggests: 
    covr,
    knitr
VignetteBuilder: 
    knitr
Encoding: UTF-8
Language: en-US
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.1.1
```
]

???
Name of the package, description of the package, maintainer, relationships with other packages...
Language does not need to be on English, it can be in other languages

.pull-right[

**Package**: Name (ASCII characters and . and -).  
**Title**: Short description.
**Version**: At least two numbers.  
**`Authors@R`**: Information with an author (auth) and maintainer (cre).  
**Description**: Longer description.  
**License**: Information about the copyright.  
**Depends**: Packages needed without which the package doesn't work.  
**Imports**: Packages used.  
**Suggests**: Packages used on examples or vignettes.  
**VignetteBuilder**: How to build the vignette.  
Other optional fields:
- **URL**: Link to the source code, and webpages.
- **BugReports**: Link to where to report issues.
- **Encoding**: ASCII or UTF-8.
- ...

]

---

## R files

1. Only valid R code: functions, objects, environments that don't depend on previous code executed.

2. If a function uses a function of an other package use `package::function`

3. Add that package to the appropriate site on [Description](#description)
    
    4. add a `#' @importFrom package function` (See next slide)

```r
meow <- function() {
 message("meow")
}
```

---
name: namespace
## NAMESPACE

Import code of other packages and export code of your package:

```r
import(dplyr)
importFrom(methods, is)
export(meow)
```

???

This can be done manually no need to do it via other tools  (but recommended)

If using [roxygen2](https://cran.r-project.org/package=roxygen2) you can use:

```r
#' @import dplyr
#' @importFrom methods is
is_meow <- function(x){
 methods(x, "meow")
}
#' @export # To make it available to others
meow <- function() {
 message("meow")
} 
```

Which will be written to the NAMESPACE file when [updating the documentation](#rd-files)

???
Important file!

---
name: rd-files

## Function documentation

.pull-left[
Using roxygen2:

```r
#' Check if it is a meow
#'
#' Check if object is of class meow.
#' @param x A character string.
#'
#' @return A logical value with either TRUE or FALSE 
#' if the object is a meow.
#' @export
#' @examples
#' is_meow("hi")
#' @importFrom methods is
is_meow <- function(x){
 methods(x, "meow")
}
```
]

.pull-right[
Convert this specials comments into *.Rd files with:

```r
document()
```
]

???

In Rstudio you can insert the skeleton with <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>R</kbd> .
In Rstudio you can convert the special comments into documentation with <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd> .

---
class: bold-last-item

## Not covered here:

- Vignettes and articles

???

Articles are like vignettes but not checked by `R CMD check`

- Tests

???

With testthat, tinytest or other ways

- Website for the documentation of the package

???

Sites with pkgdown or other tools.

- Compiled code

???

C++, C, Fortran or linking to other languages, Java, perl; or other programs (cURl, xmldev)

- Other

???

How to choose a name of the package.  
How to write a good README and NEWS file.
Set up continuous integration tests.
How to pick up a license.

---
name: release-packages
# Releasing the package

.center[**Sharing** with others]

.center[A `my_package.tar.gz` file ]

.center[Built with `R CMD build my_package`]

???

What does it mean? Building `R CMD build` and making it accessible to other people, example: `install.packages("http://biodev.cea.fr/sgcca/gliomaData_0.4.tar.gz", repos = NULL)`

What are the expectations?

---
class: bold-last-item

## Choosing the right archive/repository

- Repository

.center[Git repository, svn, or none]

???

Repositories keep versions of code

- Archive

.center[CRAN, Bioconductor, Zenodo]

???

Archive do not delete content (normally)
Keep versions "released". 
Only CRAN, Bioconductor and additional repositories like [r-universe](https://r-universe.org), [drat](https://cran.r-project.org/package=drat), ... work via `install.packages`.

- All

.center[GitHub + R-universe + (rOpenSci) + CRAN/Bioconductor + Zenodo]

???

Able to combine them, not mutually-exclusive

---

## Submitting the package

Goals of a *submission*

- Sharing something of quality that can be useful to others.
- Make it easier for others to build upon your package.
- Other: work, grant, prestige ...

???

Submissions are though specially if coming from places with poor training
Lack of confidence/experience with reviews.

| Archives reviewing packages | Objectives of the reviews? |
|:--------------------------------------------------:|:----------------------------------------------------------------------------------------:|
| <a href=https://cran.r-project.org/>CRAN</a> | Non-trivial publication quality packages. |
| <a href=https://bioconductor.org/>Bioconductor</a> | Promote high-quality, well documented and interoperable. |
| <a href=https://ropensci.org/>rOpenSci</a> | Drive the adoption of best practices with useful, transparent and constructive feedback. |

???

Differences in objectives but all looking for quality
CRAN: Point errors, comments
Bioconductor: In detail comment of style, classes, dependencies, structure…
rOpenSci: guideline for reviewers (about style, tests, functions, description, documentation, …)

CRAN ~18000 packages, Bioconductor ~2000,  rOpenSci ~300
To work with this slides use xaringan::infinite_moon_reader()

.bottom[.center[Pick the right for you and your users]]

---
name:projects

### Project differences

.center[

| | CRAN | Bioconductor | rOpenSci |
|:---------|:-------------------------------------------------------------------------------:|:------------------------------------------------------------------------------:|:----------------------------------------------------------------------:|
|Guides | <a href=https://cran.r-project.org/doc/manuals/r-release/R-exts.html>R-exts</a> | <a href=https://www.bioconductor.org/developers/package-guidelines>Website</a> | <a href=https://devguide.ropensci.org/index.html>Book</a> |
|Submit | <a href=https://cran.r-project.org/submit.html>tar.gz file</a> | <a href=https://github.com/Bioconductor/Contributions/>fill an issue</a> | <a href=https://github.com/ropensci/software-review/>fill an issue</a> |
|Review | email & ftp | Github | Github |
|Setup | None | ssh key, subscribe mailing | CI tests |
|Checks | check --as-cran | check; BiocCheck | check --as-cran |
|OS | Windows, Unix, iOS | Windows, Unix, iOS | Windows, Unix, iOS |
|Versions | oldrel, release, patched, devel | release, devel | oldrel, release, devel |
|Cycle | Always open | 2 annual releases | Always open |
|Editors | 0 | 0 | ~10 |
|Reviewers | ~5 Volunteers | ~10+Volunteers | Volunteers |

]

.center[.middle[Different setup, different review.]]

???

The different projects/archives have different setups.
*Read the table*
All of them first you need to pass the automatic checks in place before a human looks into it.
Will use data from the three projects but mostly refer to CRAN.

---

name:submissions

### Submissions

.center[
CRAN data thanks to the [incoming dashboard](https://lockedata.github.io/cransays/articles/dashboard.html).

]

???

One order of magnitude of difference between each other CRAN > Bioconductor > rOpenSci
Many variability on month
Also very few data collected from CRAN so far (Also there are some hiccups on CRAN collection, near the end of May the CRON job stopped working for a week. )

---

name:organization

### Organization

.center[
Packages are moved by reviewers [between folders](https://llrs.dev/2021/01/cran-review/#cran-load).
]

???

Many folders but these two are the most important.
There isn't an explanation from CRAN about how do they work.
Pretest is resubmission (newer versions of packages) and also for newbies

---

name:submission-patterns

### Submissions patterns

.center[
Check [the dashboard](https://lockedata.github.io/cransays/articles/dashboard.html) before submitting?
]

???

Submit when you are ready, better on the queue than outside.

---
name:review-time

#### Review time

.center[Reviews are short, brief and to the point.]

???

Median time on submissions ~9 hours, mean time ~31.4254531 hours.
1, 2, 9, 31.4254531, 33, 2365

---

#### Review speed

.center[Expect 3-7 days till your new package is on CRAN.]

???

Different time, can be shorter or longer.
Most longer need resubmission.
Resubmit with different version (makes it easier to track how many are).

```
## # A tibble: 2 × 2
## new time
## <chr> <dbl>
## 1 New 58
## 2 Update 5
```

CRAN: 60h
Bioconductor: most of them in 1 month
rOpenSci: in 2 months (seeking 2 reviewers and posting them).

---

name: users

#### Users role

.center[Some users are very involved.]

???

Bioconductor reviewers do a lot
rOpenSci editors too
Both organizations have a group of users involved on the package review system.
Even if Bioconductor doesn't explicitly ask for reviewers from the community.
Bioconductor are considering now how to improve the review system.
Omitted bots bioc-issue-bot and ropensci-review-bot (new March 2021).

---

### Comments

.center[
A dialog between authors and reviewers & editors. 
]

???

Non reviewers users on bioconductor still chime in to help.

---
name:bot

### Bot role

.center[Bot helps on the process and changes with the process]

???

Bot provides feedback of many issues and actions performed. 
It can be changed/adapted to change in requirements or errors.
rOpenSci is going to have a bot too [ropensci-review-bot](https://github.com/ropensci-review-bot/).

---
name: labels

### Labels

.bottom[ .center[ Labels are used to indicate progress on the submission. ] ]

???

On bioconductor most problems with the submissions are not the package itself but not replying or chosing another venue.
rOpenSci provides more detailed questioning for scope of a package.

---

name:success-submissions
## Success submissions

.bottom[.center[High approval rates!!]]

???

Bioconductor & rOpenSci 50%, some submissions are abandoned or do not fit the project.
Different problems faced by new packages and older ones. 
More in depth review requires 1 month for each reviewer.

```
## # A tibble: 50 × 7
## submission_n new Accepted n perc suspended perc_suspended
## <fct> <chr> <lgl> <int> <dbl> <dbl> <dbl>
## 1 1 New FALSE 652 17.8 652 31.0 
## 2 1 New TRUE 3015 82.2 0 0 
## 3 1 Update FALSE 691 13.4 691 32.8 
## 4 1 Update TRUE 4456 86.6 0 0 
## 5 2 New FALSE 148 23.4 148 7.03
## 6 2 New TRUE 485 76.6 0 0 
## 7 2 Update FALSE 270 8.27 270 12.8 
## 8 2 Update TRUE 2993 91.7 0 0 
## 9 3 New FALSE 41 20.4 41 1.95
## 10 3 New TRUE 160 79.6 0 0 
## # … with 40 more rows
```

```
## # A tibble: 2 × 3
## Approved n perc
## <chr> <int> <dbl>
## 1 No 1233 0.505
## 2 Yes 1208 0.495
```

```
## # A tibble: 1 × 4
## `1. awaiting moderation` `2. review in progress` `3a. accepted` `3b. declined`
## <dbl> <dbl> <dbl> <dbl>
## 1 0.0000231 0.299 35.7 19.1
```

|name                            | Median days| Total days|
|:-------------------------------|-----------:|----------:|
|1/editor-checks                 |         2.8|        2.8|
|2/seeking-reviewer(s)           |         2.4|        5.2|
|3/reviewer(s)-assigned          |         7.1|       12.3|
|4/review(s)-in-awaiting-changes |        27.0|       39.3|
|5/awaiting-reviewer(s)-response |        17.1|       56.3|
|6/approved                      |        13.3|       69.6|

---

## Success submissions II

.center[High acceptance rates]

---

name:submit
## Prepare sumbission

.center[
.tip-submission[
.left[
__Prepare__]
.center[
 
  Manual to [create R packages](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Creating-R-packages), [R Packages](https://r-pkgs.org/)  
  Follow policies ([CRAN](https://cran.r-project.org/web/packages/policies.html)) and **guidelines** ([Bioconductor](https://www.bioconductor.org/developers/package-submission/), [rOpenSci](https://devguide.ropensci.org/)).
]
]

.tip-submission[
.center[
**Check**

CRAN pre-submission checks: [macOS](https://mac.r-project.org/macbuilder/submit.html), [Windows](https://win-builder.r-project.org/)
  
  [Use Rhub](https://builder.r-hub.io/), [Github Actions](https://github.com/r-lib/actions)]
]

]

???

Follow the detailed guidelines from Bioconductor and rOpenSci.
Fix any problem that you haven't detected previously (double check the [CRAN repository policy](https://cran.r-project.org/web/packages/policies.html)). 
Resubmit

---
name:celebrate
## Submit

.tip-submission[
.left[[Via web](https://cran.r-project.org/submit.html "Submission page") or  `devtools::release()`.]

]

.center[ Nervous]

.right[Wait..]

.tip-submission[ 
.left[***Resubmit***]
.center[
[Fix and explain](https://cran.r-project.org/web/packages/policies.html#Re_002dsubmission) on re-submission.]
]

.center[  🎉 Celebrate 🎉 
 
Announce to the community:  
📥 [R-packages mailing   list](https://stat.ethz.ch/mailman/listinfo/r-packages)  
🐦 Social media  
👪 Family?  
Parties interested: users, R-user-groups, ...
]

---
class: bold-last-item
name:maintaining-packages
# Maintaining packages

- Keep up to date

Changes on R code, changes on dependencies, changes on CRAN checks.
    
???

Not in your hands to control, reactive work

- Change code of the package

Evaluate how to adapt your package
    
???

Better quality => Less work

- New releases

Provide new releases

???

Check also your dependencies and be mindful to users

---
class: bold-last-item
## Changing the package

.pull-left[
**New features**

Whenever you want

.minor[.minor[ On Bioconductor only after each release ] ]
]

???

Be mindful that you now "need" to support this.

.pull-right[
**Deprecating features/breaking changes**

- Notify users: NEWS, warnings , deprecate via [`.Deprecated`](https://search.r-project.org/R/refmans/base/html/Deprecated.html "Help page of .Deprecated")
]

--
.pull-right[
- And later on defunct via [`.defunct`](https://search.r-project.org/R/refmans/base/html/Defunct.html, "Help page of .Defunct")
]

.pull-right[

- If you have dependencies: notify with at least 1 month before submitting

]

???

Deprecate and defunct are important steps to notify users.  
Be mindful also to other developers that depend on your package: give them time, hear their concerns...

.bottom[.center[Make life easy to users and developers]]

---

## Keep checks clean

.center[Most packages are in good shape.]

---

## CRAN mainteinance

.center[Packages might be archived from repositories]

---

## Common reasons of archiving:

.center[Check email!]

---

## Archived?

.pull-left[

![:scale 60% "Meme image of keep calm and carry on"](images/keep-calm-and-carry-on-original.jpg)
]

.pull-right[

.center[Understand why happened.]

.center[Fix and resubmit]  
(Your package will need to pass the new package checks again.)

.middle[

|CRAN | Packages|Proportion |
|:----|--------:|:----------|
|no   |     3091|60%        |
|yes  |     2063|40%        |

]
]

.center[  
Many archived packages return to CRAN.]

---

# Summary

- 🚧 [Creating a package](#good-packages) is easy.

- 📦 [Releasing a package](#release-packages) is doable.

- ⚙️ [Maintaining](#maintaining-packages) the high standards is not.

.middle[.center[
 
Thanks to the R core team past and current members.

Thanks to the CRAN, Bioconductor, rOpenSci teams.

All the contributors to packages used to make this presentation.

]]

.middle[.center[

**To you!**

]]

???

Thank also to the package authors (mainly tidyverse, ggplot2 and rhub, and gh).
Maëlle Salmon and Stephanie Locke for the CRAN dashboard.
And the organization.
rOpenSci review: [Video](https://www.youtube.com/watch?v=iJnn_9xKkqk)

```
## NULL
```