The Dovetail #10: Updates from The Carpentries Workbench

This is the tenth post in a series that we are calling “The Dovetail”, about the transition to The Carpentries Workbench. In this series, we aim to keep members of The Carpentries community abreast of the current news about the Workbench.

If you are interested in participating in discussions around The Carpentries Workbench, 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 Updates

Lessons Currently In the Beta Phase

R for Social Scientists and Introduction to Geospatial Raster and Vector Data with R have both entered into the Workbench Beta Phase. The table below shows the status of lessons that are currently in the Beta Phase:

When you visit these pages, if you want to go back to the original lesson, you can click on the workbench beta alert icon at the top of the page:

For Instructors, here is a video showing what you can expect to see when you go to teach a lesson that is entering the beta phase:

Upcoming Lessons

In the next two weeks, we will see the following lessons enter the beta phase:

• Data Cleaning with OpenRefine for Ecologists (2022-11-07)
• Library Carpentry: The UNIX Shell (2022-11-14)

Links to edit pages

During the beta phase, there will be two parallel sites available for 12 weeks, one that is live and will continue to recieve updates and the other that serves as a snapshot as demonstrated in this table:

A recent question from the Workbench GitHub Discussions asks:

If learners/trainees are presented with a “snapshot” version of a lesson, will clicking that button send them to the snapshot repo? If so, will there be any messaging (banners etc) to redirect them to the correct repo for making contributions?

We value all contributions and do not want the beta phase to introduce a barrier that could prevent a community member from improving a lesson. If someone clicks on a link, makes a suggested change, and opens a pull request, it would be demotivating to find out that the contribution was made to a temporary or frozen version of the lesson. Thus, the answer to this question is that clicking on the “improve this page” or “edit this page” buttons will lead contributors to a landing page that briefly explains the purpose of the phase they entered the lesson through and provides a link to follow to make their suggestion to the lesson.

For example, if the contributor clicks on a link from a snapshot in pre-beta stage where it is editable, but not permanent, they would find the following page:

If a lesson is in the beta stage, where the snapshot is not editable, they would find the following page:

Updates to The Carpentries Workbench

Since 2022-10-19,

• {sandpaper} version 0.10.4 -> 0.10.6
  • The move_episode() and set_ family of functions will now print the command to use if the user calls the function without write = TRUE
• {pegboard} 0.3.2
  • no updates :)
• {varnish} 0.2.6 -> 0.2.8
  • Bugs in the Workbench beta phase links have been fixed
  • Links to edit pages on GitHub are now directed to a page that first explains the purpose of the beta phase.

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'))

Upcoming and Current Lessons in Workbench Beta

List of Lessons to enter Workbench Beta in 2022

Community Lessons

• carpentries-incubator/git-novice-branch-pr—Version Control with Git
• carpentries-incubator/data-management-pipelines-engineering—Data management and analytic pipelines for engineers
• carpentries-incubator/markdown-intro—Introduction to Markdown
• carpentries-incubator/SDC-BIDS-IntroMRI—Introduction to MRI and BIDS
• carpentries-incubator/SDC-BIDS-dMRI—Introduction to dMRI
• carpentries-incubator/SDC-BIDS-fMRI—fMRI Imaging Analysis
• carpentries-incubator/julia-novice—A lesson exploring the Julia language
• carpentries-incubator/R-archaeology-lesson
• carpentries-incubator/python-packaging-publishing—Packaging and Publishing with Python

Participants

• Sara Morsy, Lesson Developer (in The Carpentries Incubator)
• @iramosp, Maintainer
• Jesse Sadler, Maintainer
• Eirini Zormpa, Maintainer
• Robin, Instructor
• Jon Haitz Legarreta Gorroño, Lesson Developer (in The Carpentries Incubator)
• Karen Word, Maintainer
• Luis J. Villanueva, Maintainer
• Jon Wheeler, Lesson Developer (in The Carpentries Incubator)
• Simon Christ, Lesson Developer (in The Carpentries Incubator)
• Maneesha Sane, Instructor
• Sarah Brown, Maintainer
• Joel Nitta, Translator
• Juan Fung, Maintainer
• Jannetta Steyn, Lesson Developer (in The Carpentries Incubator)
• Michael Joseph, Lesson Developer (in The Carpentries Incubator)
• Sarah Stevens, Lesson Developer (in The Carpentries Incubator)
• Kozo Nishida, Lesson Translation (to Japanese)
• François Michonneau, Maintainer
• Jamie Jamison, Maintainer
• Jennifer Stubbs (she/her), Instructor
• Drake Asberry, Maintainer

Tips and Tricks for Using The Workbench

This tip is for folks who are working on lessons that use R Markdown.

This tip will show you how to use the package cache to debug a problem in your lesson without changing your default R package library.

Lessons that use the Workbench automatically use the {renv} package to manage lesson dependencies without modifying the state of your default R package library. This is different than the styles version of the lessons where you would be forced to update the packages in your global package library. In a lesson, the lockfile for this package cache lives in renv/profiles/lesson-requirements/renv.lock.

Now imagine that there is a mysterious error in your lesson. Take for example PR#378 for one of the lessons that was released into pre-beta today. This error happened because there was a change in a package that was used. This led to a problem with some of the plotting commands where there would be an error that looked something like this:

Error in FUN(X[[i]], ...): object 'HARV_RGB_Ortho.3' not found

There are two ways to diagnose the error:

Solution 1: copy files and use renv

You can create a new folder outside of your lesson and copy the renv.lock file into that folder along with the data and files from the episodes/ folder. When you open R inside that folder type:

renv::restore()

Once you have that, you can run through the commands until you get to the error.

Solution 2: use work_with_cache()

I wrote the work_with_cache() function in the {sandpaper} package to temporarily allow me to use the versions in the package cache while I was working on the transition workflow. It allowed me to quickly access packages to build the lesson without having to reinstall them to my default library.

To debug, I open the R Markdown file that was giving me trouble and set my working directory to site/built where all of the intermediate Markdown output is rendered. After that I call work_with_cache() placing the output in a variable called “done”.

library(sandpaper)
setwd("site/built")
done <- work_with_cache() # loads the lesson-requirements profile

Once I do this, My prompt looks like this:

* (lesson-requirements) Project '/path/to/r-raster-vector-geospatial' loaded. [renv 0.16.0]
ℹ call `done()` when you are finished with the session.

[lesson]> 

And then I can walk through the R Markdown document until I hit the error and begin exploring. When I find the solution, I can fix it in the document and then restore my session by calling done(), which is a function that work_with_cache() created to finalise the session and return you to your previous state.

done() # detaches the lesson-requirements profile, allowe me to access my default library