The Dovetail #15: Updates from The Carpentries Workbench

This is the fifteenth 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 two 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.

Beta Phase Second Stage Is Live

The second stage of the beta phase is now live. This is a big milestone because this is the portion of the beta phase where our community of contributors will get a chance to interact with and use the Workbench in our live lessons before we transition all of our lessons to use the new infrastructure in May 2023.

With this second stage of the beta phase, we have created a series of videos that demonstrate some of the guides for what to expect during this period: Workbench Beta Phase YouTube Playlist.

Here is the introduction to this stage of the beta phase:

On Monday, 2023-02-06, the beta phase lessons were transformed to enter the second (beta) stage of the beta phase: one repository, two sites where the Workbench version of the lesson is the default for the lesson repository.

For example, this is the state of the R for Social Scientists Data Carpentry lesson:

From now on, any changes to the lesson repository will only affect the Workbench version of the lesson. Because the git history of the default branch has changed, 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.

On Monday, 2023-04-03 the default lesson website will use the Workbench and the styles branch will be removed from the GitHub repository.

Thank You Beta Phase Participants

Being a Maintainer is not an easy job. As I mentioned in my ode to Maintainers in dovetail 13, they are the quality assurance and moderators for our lessons to ensure that they adhere to our teaching principles and provide guidance for Instructors and learners.

The Maintainers who are participating in the beta phase have gone above and beyond to test out the Workbench and provide valuable feedback that could only come from organic usage. It is because of the feedback from these Maintainers and other intrepid community members that the Workbench is stable. While not all Maintainers have been able to participate in the beta stage due to extenuating circumstances, I would like to thank them for stepping up despite the many false starts that this project has encountered as we have battled our own extenuating circumstances.

With that, I would like to extend my thanks to the Maintainers of the beta phase lessons:

R for Social Scientists Maintainers

• jessesadler
• Juan F Fung
• Eirini Zormpa

Introduction to Geospatial Raster and Vector Data with R Maintainers

• drakeasberry
• Ivo Agbor Arrey
• Jemma Stachelek

Maintainers de Análisis y visualización de datos usando Python

• Irene Ramos
• Agustina Pesce
• Vini Salazar

Instructor Training Curriculum Maintainers

• Sarah M Brown
• Karen Word
• Tim Dennis
• David Perez-Suarez
• Jon Wheeler
• Nathaniel Porter
• Toby Hodges
• Kelly Barnes

R Ecology Lesson Maintainers

• François Michonneau
• Tobias Busch
• Brian Seok

Library Carpentry Shell Lesson Maintainers

• Jamie Jamison
• Kaitlin Newson
• annaoates

I would also like to extend my sincere thanks to Saba Ferdous, Mark L Crowe, Sarah Kaspar, Jennifer Stubbs, Athanasia M Mowinckel, Jannetta Styen, Sarah Stevens, and Philipp M Schäfer for their invaluable feedback, testing, and general enthusiasm for the Workbench.

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 now in the second (beta) stage of the beta phase (one repository, two lesson websites).

Updates to The Carpentries Workbench

Since 2022-01-17,

• {sandpaper} version 0.11.3 -> 0.11.5
  • a bug where the setup page was not added if it wasn’t provisioned was fixed
  • The functions update_cache() and pin_version() will now work inside of subfolders. Thanks to Sarah Kaspar for spotting the bug
  • as of version 0.11.4, {sandpaper} now works with Pandoc version 3.
• {pegboard} version 0.4.2 -> 0.4.3
  • Improvements to link and image validation
    • alt-text validation better detects missing alt text (thanks to David P.S. for finding this)
    • an allowed list of URL protocols has been created to make sure that misspelled and malicious URL protocols are flagged.
• {varnish} 0.2.13 -> 0.2.14
  • The “edit this page” links for beta stage lessons no longer redirects to the splash page.

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 of the strengths of using the Workbench is that it gives you control over the package cache used to build R-based lessons. For official Carpentries lessons, a pull request to update the package cache will appear monthly and show you if there are any changes to the output of your lesson.

For lessons that are not within one of The Carpentries GitHub organisations, you can still update your package cache and create a pull request locally: open R in your lesson directory and then use sandpaper::update_cache() to update the package cache:

> sandpaper::update_cache()                                                            
* (lesson-requirements) Project '.' loaded. [renv 0.16.0]
* Querying repositories for available source packages ... Done!
* Checking for updated packages ... Done!
* 4 packages have updates available.
→ Do you want to update the following packages?
# CRAN ===============================
- knitr       [1.41 -> 1.42]
- rmarkdown   [2.18 -> 2.20]
- xfun        [0.35 -> 0.37]
- yaml        [2.3.6 -> 2.3.7]

1: Yes
2: No

Selection: 1

When you do this, the packages will be updated in your lesson cache and the file renv/profiles/lesson-requirements/renv.lock will be updated:

$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   renv/profiles/lesson-requirements/renv.lock

no changes added to commit (use "git add" and/or "git commit -a")

You can now create a new branch, commit, and make a pull request to see what changes happen in your lesson from the package updates.

This is also useful in cases where cache invalidation has failed.