The Release Process

This document is adapted for The Hubverse from The Carpentries Developer’s Handbook (c) The Carpentries.

Background

Each of these packages are available on the Hubverse R-Universe and new versions are checked for hourly. This allows folks to get up-to-date versions of The Hubverse packages built for their system without running out of GitHub API query attempts.

In order to maintain quality, packages are only sent to the R-Universe if they have been formally released on GitHub (as specified in the packages.json configuration file). This allows us to incrementally add new experimental features without changing the stable deployments.

Versioning

The hubverse is built using very basic semantic versioning using the X.Y.Z[.9000] pattern.

X

Major version number: this version number will change if there are significant breaking changes to any of the user-facing workflows. That is, if a change requires users to modify their scripts, then it is a breaking change.
EXAMPLE: There are no examples of hubverse packages undergoing a major version change, but schemas v3.0.0 included the breaking change of switching sample/output_type_id (an array) to sample/output_type_id_params (an object). The breaking change meant that it was a non-trivial task to switch from a v2.0.1 schema to v3.0.0 and the users. This was reflected in the month-long timeline between the announcement of the change on 2024-05-13 to the actual release on 2024-06-18.

Y

Minor version number: this version number will change if there are new features or enhanced behaviors available to the users in a way that does not affect how users who do not need the new features use the package. This number grows the fastes in early stages of development.
EXAMPLE: The {hubValidations} package version 0.5.0 gives users the ability to reduce compute time by allowing them to sub-set the configuration by the new output_type argument to expand_model_out_grid(). Users who change nothing in their workflows or scripts will not see any change for the better or worse.

Z

Patch version number: this version number will change if something that was previously broken was fixed, but no new features have been added.
EXAMPLE: the {hubAdmin} package needed an enhancement for schema version 3.0.1, which removed the requirements for CDF outputs to have a specific pattern. The actual fix was not something a user would interact with, so version 1.0.1 was a patch release.

9000

Development version indicator: this version number indicates that the package is in a development state and has the potential to change. When its on the main branch, it indicates that the features or patches introduced have been reviewed and tested. This version is appended after every successful release. When this development version indicator exists, the documentation site will have an extra dev/ directory that contains the upcoming changes so that we can continue to develop the hubverse without disrupting the regular documentation flow. Advice on incrementing the version number from The R Packages Book (Wickham and Bryan, 2023):

Increment the development version, e.g. from 9000 to 9001, if you’ve added an important feature and you (or others) need to be able to detect or require the presence of this feature. For example, this can happen when two packages are developing in tandem. This is generally the only reason that we bother to increment the development version. This makes in-development versions special and, in some sense, degenerate. Since we don’t increment the development component with each Git commit, the same package version number is associated with many different states of the package source, in between releases.

Release Process

When a package is ready for release we use The Release Checklist (detailed in vignette("release-checklists", package = "hubDevs")). The rationale for this process is described in The proposal discussion for R package release guidelines.

Non-urgent releases only

This release process assumes that we have accumulated bugfixes and/or features in the main branch, which we are ready to release. If you have a bug that needs to be patched immediately and you have new features in the main branch that are not yet released, then you should create a hotfix instead.

Releases

Releases are a concept that is specific for GitHub. Under the hood, releases are created from commits or tags. When you use the GitHub web interface, you can choose to have a tag automatically created from a release (though the tag will not be annotated or signed, see below for creating stronger, signed tags). All releases should contain a summary of the changes that happened between this version and the previous version. A good example of this are the hubverse schema release notes, and GitHub offers to automatically fill the release notes with titles and links to the pull requests that populated the release, which is a good summary (assuming people create good PR titles).

Once the release is created on GitHub, then the package will be available on the R-Universe in about an hour or less.

Signed Tags

It is good practice to create a tag to release from so that we have a way to track the releases even if we eventually move away from GitHub. Better practice is to create annotated tags with the -a flag, which adds metadata to the tag, meaning that it cannot be moved. Even better practice is to create signed tags with the -s flag, which adds a cryptographic signature to the annotated tag metadata that allows anyone to verify that it came from your computer and not someone pretending to be you.

Zhian likes to create tags via the command line because he has set up his git configuration to use a gpg signature so the tags and the releases are both verified. Recently, Git and GitHub added support for creating signatures via an SSH key, which is a lot more approchable than GPG.

Unfortunately, you cannot create a signed tag on the GitHub web interface and it must be done locally.

git tag -s X.Y.Z -m 'summary of changes'
git push --tags

Once you have a signed tag created, you can then go to the Releases tab on GitHub and create the release (or you can use the gh CLI utility) and run gh release create X.Y.Z to interactively create the release.