13 Release Process for Workbench Packages

13.1 Background

The workbench contains three main packages:

{sandpaper}: user interface and workflow engine
{pegboard}: parsing and validation engine
{varnish}: HTML templates, CSS, and JS elements

Each of these packages are available on the Carpentries R-Universe and new versions are checked for hourly. This allows folks to get up-to-date versions of The Workbench 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.

13.2 Versioning

The workbench 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. For example: at this time of writing, {pegboard} is at version 0.7.0, for which the Lesson object assumes a Jekyll lesson by default. If we were to change this to assume a sandpaper lesson by default, then this would be a breaking change because anyone who is using Lesson$new() will now need to use Lesson$new(jekyll = TRUE).
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. An example of this is {pegboard} version 0.7.0 introduced processing of child documents. If the lesson has no child documents, then it is processed as expected, but if the child documents exist, then they are additionally processed and validated.
Z: Patch version number this version number will change if something that was previously broken was fixed, but no new features have been added. An example of this is in {sandpaper} version 0.13.3 where there were two bugfixes that affected links to setup page sections and 404 page rendering that otherwise did not add any new features.
9000: Development version indicator this indicates that the version of {sandpaper} on GitHub is in development and not yet released. This indicator is always appended to the current release number and should be between 9000 and 9999. For example, you the development version indicator for the version of sandpaper after 0.13.2 is 0.13.2.9000. This particular version resulted in a bump to 0.13.3, but it could also have resulted in 0.14.0 or 1.0.0. It has not been extensively used in the past, but it is quite useful for tracking incremental changes with different bugfixes and features that may appear. 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 workbench without disrupting the regular documentation flow.

13.3 Release Process

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.

When a package is ready for release we use the following checklist:

Create a new branch from main called release-X.Y.Z
Update version number in DESCRIPTION and check that the Remotes: is up-to-date
Add NEWS for the changes in this version
commit, push changes, and create pull request
check the pull request against the workbench integration test
Merge the pull request when checks pass

add new signed tag with the name “ X.Y.Z” and push

# example: create a signed (-s) tag for sandpaper 3.3.3
git tag -s 3.3.3 -m '<short explanation of what changed>'
git push --tags

create a release on github from the new tag

Note

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.

The last two items can be achieved in a single step with the github cli with the command gh release create X.Y.Z for the version number

gh release create 3.3.3
# ? Title (optional) sandpaper 3.3.3
# ? Release notes  [Use arrows to move, type to filter]
#   Write my own
# > Write using generated notes as template
#   Leave blank

Selecting “Write using generated notes as a template” opens an editor and populates it with the pull requests that have been accepted since the last release.

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

13.4 Release Timeline

In the early days of The Workbench, the release process was ad-hoc because the number of users was low, but now that the entire community is using it, it is important to set expectations and properly communicate changes to the users. For patch relases, these releases should continue to happen ad-hoc because, by definition, these releases only fix bugs and do not add new features.

The release timelines are based on two assumptions:

a M–F workweek (i.e. NEVER release on a Friday unless you like working on the weekend)
All lesson builds and updates happen every Tuesday at 00:00 UTC (packages for R-based lessons are updated on the first Tuesday)

13.4.1 Minor Feature Updates

For releases that add new non-breaking features which bump the minor version, it is important to alert the community a couple of days in advance of the release so they have a chance to give feedback before the release. Thus, I propose the following timeline:

Friday (drafting): Members of Workbench Maintainer Group draft communications describing new features
Monday (communications): Communications describing new features sent to relevant communities (maintainers/trainers/instructors, depending on feature)
Wednesday (release): New version of Workbench package(s) released

We release on Wednesday in order to give enough time for the communications to sink in and give enough time for us to release patches to the release before all lessons get rebuilt.

13.4.2 Breaking Changes

If there are breaking changes, it is important to give the community enough time to adapt and to offer them a path forward to fix their workflows. Depending on how drastic the change is, it may be important to conduct beta testing to ensure that the change doesn’t contain any unforseen bugs and, importantly, that it improves the workflow for the audience over doing nothing at all.

The Beta Phase of The Workbench is an extreme version of this, but it is important, because major version changes have real-world consequences that you want to avoid as much as possible.

The release should still happen on a Wednesday, but the communications aspect should be timely, specific, targeted, and repeated. It may be that you have to communicate about the change one week, one month, or even one quarter ahead of the release. In a volunteer community, you will end up in situations where people are checked out for months at a time and will see everything changed, so please do take care with the communications and changes.