The Dovetail #14: Updates from The Carpentries Workbench

This is the fourteenth post in a series that we are calling “The Dovetail”, about the transition to The Carpentries Workbench (our new lesson infrastructure). In this series, we aim to keep members of The Carpentries community abreast of the current news about the Workbench. If you are unfamiliar with The Workbench, you can watch a video that describes the workbench and the beta phase in twom minutes.

If you are interested in participating in discussions around The Carpentries Workbench, or if you have questions, head over to our GitHub Discussions forum: https://github.com/carpentries/workbench/discussions

If you have used the workbench and would like to provide feedback, please tell us about your experience.

Entering the Second Stage of the Beta Phase

Beta Phase So Far

Since December, the lessons currently in the beta phase have been in the first (pre-beta) stage of the beta phase: two repositories, two sites. In this stage, each lesson had two repositories serving parallel versions of their lessons websites: one using the styles infrastructure, and the other, a snapshot, using the Workbench infrastructure.

For example, here is the state of the R for Social Scientists DataCarpentry lesson:

In this stage of the beta phase, the community is encouraged to explore, fork, and contribute to The Workbench version of these lessons in our sandbox GitHub organisation. All of the lessons in this repository are snapshots from the official lessons and any changes made to them are strictly temporary, which means that this is a perfect sandbox for practising your GitHub skills working with these sandboxed lessons.

It is important to note that during this time, the Maintainers of these lessons will be focused on resolving and closing pull requests on the styles version, so please be mindful before opening a pull request for these lessons, and open an issue instead.

Transition on 2023-02-06

In 20 days (Monday 2023-02-06), the the lessons currently in the beta phase will enter the second (beta) stage of the beta phase: one repository, two sites.

Following the example above, the state of the R for Social Scientists DataCarpentry lesson will look like this:

The transition will use the following process:

1. A lesson release will be created for the styles version of the lesson
2. The default branch will be moved to have the prefix legacy/ and locked from editing (only to be updated for crucial updates).
3. A transformation of the default branch will be set as main and that will become the default branch.

During this time, any changes to the lesson repository will only affect the Workbench version of the lesson. Because the git history of the default branch will be changing, if you have a fork of one of these lessons, you must delete it and re-fork if you want to make a new contribution, otherwise, you risk a failed pull request.

After 8 weeks, the default lesson website will use The Workbench and the styles branch will be removed from the GitHub repository.

Lessons Currently In the Beta Phase

The table below shows the status of lessons that are currently in the beta phase. All of these lessons are currently in the pre-beta stage (two repositories, two lesson websites) and will transition to the beta stage (one repository, two lesson websites) on 2022-02-06.

Updates to The Carpentries Workbench

Since 2022-12-21,

• {sandpaper} version 0.11.3
  • no updates :)
• {pegboard} version 0.3.2 -> 0.4.2
  • A bug in parsing Jekyll templating syntax was fixed.
  • The minimum version of {tinkr} required is the current development version: 0.1.0.9000
• {varnish} 0.2.11 -> 0.2.13
  • Table styling has been fixed so that tables are more accessible. They no longer have indentation in the first column, the headers are bold, rows are zebra striped, and the table is now accurately represented as a table for screen readers.
  • The sidebar no longer takes up extra room at the foot of the document when collapsed.

  

To update your local Workbench installation, open R and use the following code:

# Enable repository from carpentries
options(repos = c(
  ropensci = 'https://carpentries.r-universe.dev',
  CRAN = 'https://cloud.r-project.org'))
# Download and install sandpaper in R
install.packages(c('tinkr', 'pegboard', 'sandpaper', 'varnish'))

Tips and Tricks for Using The Workbench

One common practice for instructors is to fork a lesson to their own GitHub account so that they can modify, rearrange, add, or omit episodes to serve their audience.

GitHub does not enable GitHub Actions or Pages by default, so there are a few steps you need to do to make sure your fork can display a website.

1. (recommended) When creating your fork, you should uncheck “Copy the main branch only” checkbox. 

2. To enable actions, on your fork, navigate to the actions tab, and click the button that says “I understand my workflows, go ahead and enable them”.

3. To enable the pages, navigate to the “Settings” tab, click on “pages” on the side bar, and then set your site to deploy from the gh-pages branch.