8  Package maintenance

The following discussions on this page apply to both R and Python software unless otherwise noted.

8.1 Licenses

All software (R, Python, etc.) in the WILDS should by default use the MIT license.

If there are circumstances which prevent using MIT, please do discuss with Sean or Scott.

8.1.1 R

In R, you can add the MIT license to your repository with the following code:

if (!requireNamespace("usethis", quietly = TRUE)) {
  install.packages("usethis")
}
usethis::use_mit_license()

Note that usethis::use_mit_license adds two files to your repository (LICENSE and LICENSE.md, and adds entries to the .Rbuildignore file so that R CMD CHECK doesn’t complain).

8.1.2 Python

There’s no widely accepted single tool for dealing with licenses in Python similar to the above for R. For Python packages, simply include the license type (e.g., MIT) in your setup.py, setup.cfg, pyproject.toml, etc., and include the text of the license in a LICENSE file in the root of your repository.

8.2 Package versioning

There is a detailed discussion of versioning R packages in the lifecycle chapter of the R Packages book by Hadley Wickham and Jenny Bryan. Please follow that chapter in general for versioning of R and Python packages within the WILDS. To make it easier to grok, below are some of the highlights, and some exceptions to that chapter.

8.2.1 Package version numbers

There’s quite a bit of nuance - and surprises - to package version numbers - see the Package version number section for details. For example, using the utils::package_version() function, which parses package version strings into S3 classes, we get a suprising result:

"2.0" > "10.0"
#> [1] TRUE
package_version("2.0") > package_version("10.0")
#> [1] FALSE

With that example, please do think about your package versions before setting them.

8.2.1.1 WILDS Conventions

Following the Tidyverse package version conventions, WILDS packages will use the following conventions (see the link for more details):

  • Always use . as the separator, never use -.
  • A released version number consists of three components, <major>.<minor>.<patch>
  • While a package is in between releases, there is a fourth component: the development version, starting at 9000 (e.g., 0.2.2.9000), and incrementing from there until the package has another release at which point return to three components.

8.2.2 Ignore these

We are not following or enforcing any rules about changes at the function/class/etc level below the package level. For example, the R Packages book talks about using the lifecycle package to deal with function changes.

8.3 Package releases

In general follow the Releasing to CRAN chapter in the book R Packages for R, and the Releasing and versioning chapter in the book Python Packages for Python. Those chapters don’t have to be followed to the letter, but in general they provide really good guidance.

There are a few aspects of releases we are opinionated about and would like all WILDS R and Python packages to follow:

  • Use the MIT license unless there’s good reason not to
  • Follow our versioning guidelines above
  • Git tag released versions, and push the tag to GitHub
  • Add the associated NEWS/Changelog items to a release associated with the tag on GitHub