general_issues.qmd

---
title: "General Issues"
subtitle: "General issues and helpful notes around CRAN submission best practices."
format: 
  html:
    css: style.css
---

# Structure of CRAN-Submissions

<!-- I would add a section about the path of packages when they are submitted to CRAN.
Where do they end up and who will look at them etc... -->

<!-- # Fields of the DESCRIPTION File --> 

<!-- I suggest writing a short overview of the most common and important fields of the DESCRIPTION -->

# Description Length

The description field in the DESCRIPTION file should be a short paragraph (2+ sentences) on the package's purpose, motivation and may include further references to the package documentation website. You can also consider the Description length to be similar to a blurb or synopsis written on the inside jacket of a book - brief but informative. A good example of this description length is included in the ['tidyverse'](https://github.com/tidyverse/tidyverse/blob/main/DESCRIPTION#L8-L12) package.

::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true}

The Description field is intended to be a (one paragraph) description of what the package does and why it may be useful. Please add more details about the package functionality and implemented methods in your Description text.

:::

# Structuring of Examples 

As part their documentation most functions have example code in their .Rd-files marked by the `\examples{}` tag. 
Examples serve two major purposes for packages on CRAN.

1. Show users how to implement the function correctly and what to expect as outcome.
2. Allow the CRAN team to perform test on the code.

For several reasons, some examples cannot be run as tests. Therefore, CRAN has several wrappers to structure them. The following list gives a short overview of the most common ones and when to use them.

* **Unwrapped:**
  + Short examples to show the functionality of the code
  + CRAN recommends the use of toy examples on small data sets
  + Ideally, also cover some edge cases


* **\\donttest{}:** 
  + Lengthy examples, with execution times longer than 5 seconds
  + Examples that download data
  + They are tested infrequently on CRAN as well and are also executed when calling example()
  
* **\\dontrun{}:**
  + Unexecutable examples due to missing information (e.g. API calls where a password is needed)
  + Examples which require additional software
  + Never executed, are automatically marked with a comment ("# Not run:") in the Help file. 
  
* **if(interactive()){}:**
  + Functions which only run interactively and cannot be used in scripts
  + Most commonly, examples for Shiny Apps and interactive plots
  
* **try():**
  + Examples which are supposed to fail and throw an error
  + try() shows the error message but won't halt the execution
  
* **if(requireNamespace("packagename")){}**
  + Used for examples which need particular packages to run
  + Those packages should be listed in the Suggests filed of the DESCRIPTION file
  
* **\\dontshow{}:**
  + Treated similarly to unwrapped examples but are not shown to the user
  + Great for setting and resetting options or code purely for tests 
  


:::{.callout-important}

All wrappers must still be placed inside the `\examples{}` tag. 

:::

::: {.callout-note title="Examples of CRAN Review Communication" appearance="simple" icon=false collapse=true}

\\dontrun\{\} should only be used if the example really cannot be executed (e.g. because of missing additional software, missing API keys, ...) by the user. That's why wrapping examples in \\dontrun\{\} adds the comment ("# Not run:") as a warning for the user. Does not seem necessary. Please replace \\dontrun with \\donttest.

Please unwrap the examples if they are executable in < 5 sec, or replace \\dontrun\{\} with \\donttest\{\}.

Functions which are supposed to only run interactively (e.g. shiny) should be wrapped in if(interactive()). Please replace \\dontrun\{\} with if(interactive())\{\} if possible, then users can see that the functions are not intended for use in scripts.

All your examples are wrapped in \\donttest\{\} and therefore do not get tested.  
Please unwrap the examples if that is feasible and if they can be executed in < 5 sec for each Rd file or create additionally small toy examples to allow automatic testing.

:::

# Package Size

Ideally, CRAN packages should be under 5 Mb. There are *very few exceptions* mostly for a larger `inst/` folder (and these will trigger flags for every future submission). They must be approved by a CRAN team member and since every accepted version is saved on CRAN, they are very hesitant.

It's best to minimize the package size. Large datasets can be hosted externally, such as on GitHub, and downloaded when necessary. Consider placing them in a separate data package that requires less frequent updates.

At a upper limit of the package tarball the CRAN policy states 10 Mb. It is recommended to include third-party source software within the package. If that requires larger tarballs, a modestly increased limit can be requested at submission.

:::callout-tip

If your package exceeds the recommended 5 Mb limit, it will generate a NOTE in the R CMD Check. You can explain why the size is okay by providing details in the [cran-comments.md](https://usethis.r-lib.org/reference/use_cran_comments.html) file.

:::


::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true}

A CRAN package should not be larger than 5 MB. Please reduce the size.

:::

# Communicating with CRAN

For a smooth review process and to provide CRAN volunteers with helpful context on any issues, it’s recommended to CC `cran-submission@r-project.org` in your email communications. See the rules and recommendations on the [CRAN Repository Policy](https://cran.r-project.org/web/packages/policies.html). This way, any available team member can respond. Additionally, include any updates or explanations related to your package in the submission comments file ([cran-comments.md](https://usethis.r-lib.org/reference/use_cran_comments.html)).