Frequently Asked Questions

Work In Progress

As this is a FAQ, it will continue to grow as we update it. If you have any questions please submit them to the Workbench GitHub discussion forum.

I will attempt to divide these questions up by major categories, but these may shift around as questions come in.

If you have a question about definitions, consult our glossary

Authoring

These FAQs are intended for those who contribute to, maintain, or create lessons using The Workbench. If you only ever visit the website, then head over to the Teaching or Learning sections.

Why was R chosen for the infrastructure?

Most tools for webpage authoring outside of Wordpress and the like expect authors to have some knowledge or ability to manipulate HTML, CSS, JavaScript and one (or two) other languages to wrangle them all together. It’s great for people who are dabbling in webpage development, but as we’ve seen for several years now, it’s not great for people who do not have much experience with these technologies (think about the last time you assisted someone to install Jekyll correctly).

We chose R for four main reasons:

1. It has a really robust publishing ecosystem
2. It is available as a binary application on all major platforms with a packaging system that more often than not just works
3. Most of all: The R community as a whole is vibrant, diverse, welcoming, and is most aligned with The Carpentries core values.
4. It provides a throughline between the tools we teach and real-world applications.

We tested the infrastructure in 2021 to make sure that it works for people with varying levels of familiarity with R: See this Blog Post from 2021 on the Alpha Test of the infrastructure.

Zhian Kamvar has given two talks about The Workbench that go into a little bit more detail about why we chose R (which highlight the points above)

Talk	Video	Slides (with speaker notes)
Using R as a Community Workbench for The Carpentries Lesson Infrastructure	Use!R 2021 Video	https://zkamvar.github.io/user2021/#p1
Building Accessible Lessons with R and Friends	rstudio::conf(2022) Video	https://zkamvar.github.io/rstudio-conf-2022/#p1

Do I really need to use RStudio?

No. We recommend using RStudio for several reasons that pertain to ease of use and standardisation across systems, but we do not absolutely require it. If you are able to get Git, R, and pandoc installed on your system, then you do not need to use RStudio.

What is an R Library?

An R library is a folder on your computer that stores R packages. When you install R packages, the first message you will see will probably be something like (on Windows):

Installing packages into ‘c:/Users/USER/Documents/R/win-library/4.0’
(as ‘lib’ is unspecified)

This folder is where all of the R packages you install via install.packages() will live. If you ever need to look this up, you can use the .libPaths() function.

Sometimes, your R session will issue a warning that says a folder is not writeable and asks if you would like to use a personal library instead. In this case, select “yes”.

Why are there so many GitHub Workflows and what do they do?

Each lesson contains a set of GitHub workflows that are important for the following tasks:

• building the lesson and deploying it on GitHub (.github/workflows/sandpaper-main.yaml)
• validating and responding to pull requests
• automated updates of workflows and (for lessons that use R) package cache

These workflows originate from {sandpaper} and are copied directly into each lesson as described in a README.md inside the {sandpaper} repository.

You can read technical details of how the workflows work and how they are connected by reading the Workflows section of the Remote Deployment Chapter in the Workbench Developer’s Guide.

What are the md-outputs and gh-pages branches?

These branches are part of the remote two-step workflow.

• md-outputs: contains rendered markdown files, cached to 1) speed up computations by skipping content that has not changed and 2) allow for comparison of rendered output in Pull Requests
• gh-pages: contains the rendered website.

Why is The Workbench creating so many md-outputs-PR branches?

You might notice that every time a valid pull request is opened, a new branch is created. Each branch is unique to a pull request and is automatically removed when the pull request is closed.

These branches are orphan branches that contain two commits: the first commit is the current state of the md-outputs branch containing the rendered markdown of the active lesson. The second commit contains the rendered markdown of the pull request. The diff between these commits can be used to analyse changes in output of R Markdown documents. For more information, please read the Auditing Pull Requests Chapter in the Introduction to The Workbench.

How do I add a custom logo?

For custom logos, you should do the following:

1. fork {varnish}
2. modify the incubator-logo.svg and incubator-logo-sm.svg logos in the source/images/ folder.
3. ensure your lessons use the carpentries: 'incubator' and varnish: 'MYACCOUNT/varnish' keys in the config.yaml

How do I get my lesson to use a custom Workbench package?

If you have a custom version of a Workbench package (e.g. {varnish}, with different colours, logos, or badges), there are two steps to get your lesson to use it:

1. ensure your package is publicly available on GitHub
2. in your lesson, specify your package using the custom engine declaration in the config.yaml

Is there a Docker Container?

As of 2023-12-20, there is no official docker container, but the community has some around and created a few iterations as discussed in carpentries/workbench#39.

Lesson Transition

This section is applicable for transitioning between the former carpentries/styles lesson infrastructure and The Workbench.

How do I transition my lesson to using The Workbench?

Limited Support

Due to significant staffing changes in late 2023, The Carpentries is unable to provide support for transitioning unofficial lessons to use The Carpentries Workbench.

You can use the Lesson Transition Tool, which will:

1. create a submodule for your lesson
2. filter out the infrastructure-related commits
3. transform the markdown syntax using {pegboard}

It requires Python, R, git, Make, and BASH (it is unknown if these routines will work with zsh). I have written out detailed instructions for the transition process, but please note: these assume you have administrative access to your lesson.

• Initiating and testing a lesson transtion
• Transitioning and uploading a lesson

How do I transition a long-running fork to using The Workbench?

See the above section for instructions. You can copy the lesson-specific transition script to your fork folder to make things easier (though this depends on when you last updated your fork). If you do not have any intention of recieving or contributing your changes to the source, then the above section should be all that you need.

If you want to continue updating your fork, it will be a little more complicated because it depends on when you last updated your fork. There is some discussion in carpentries/workbench#51.

In short, the commit histories will be identical up until the point of the fork and then the commit history will diverge (but still be relatively compatible) until the point of transition. You may be able to merge the upstream into your fork, but it will not be easy and it will likely contain several merge conflicts. This is not to say that it cannot be done, but it highly depends on the level of customisation you did in the fork. Take for example a fork of the shell-novice lesson that had 16 commits ahead of swcarpentry/shell-novice. Attempting to update the transitioned fork resulted in 188 conflicts¹:

Unmerged paths:
  (use "git add/rm <file>..." as appropriate to mark resolution)
    both added:      .github/workflows/sandpaper-version.txt
    both added:      .gitignore
    both added:      CONTRIBUTING.md
    both modified:   README.md
    both added:      config.yaml
    both deleted:    data/data-shell.zip
    both modified:   episodes/01-intro.md
    both modified:   episodes/02-filedir.md
    both modified:   episodes/03-create.md
    both modified:   episodes/04-pipefilter.md
    deleted by us:   episodes/05-loop.md
    both modified:   episodes/05-script.md
    both modified:   episodes/07-find.md
    added by us:     episodes/data/data-shell.zip
    added by them:   episodes/data/shell-lesson-data.zip
    deleted by them: episodes/fig/redirects-and-pipes.png
    both modified:   index.md
    both added:      instructors/instructor-notes.md
    both modified:   learners/discuss.md
    both added:      learners/reference.md
    both added:      learners/setup.md

$ rg -c '<<<<' 
index.md:1
config.yaml:5
README.md:3
episodes/04-pipefilter.md:25
episodes/05-script.md:20
episodes/02-filedir.md:40
episodes/03-create.md:34
episodes/01-intro.md:3
episodes/07-find.md:25
instructors/instructor-notes.md:14
CONTRIBUTING.md:2
learners/discuss.md:3
learners/reference.md:12
learners/setup.md:1

$ rg -c '<<<<' | awk -F: '{sum+=$2} END{print sum}'
188

Local Clones

How do I update my clone after the transition from styles?

The easiest way is to rename your local clone to old-NAME (where NAME is the name of your repository folder) and then re-clone the lesson. You can find details on updating your local clone on the beta phase page.

Post-transition GitHub Forks

How do I update my fork after the transition from styles?

Before you read further

This is only applicable if you have created a fork of the lesson before 2023-02-06.

Do not “synchronise” your fork

If you attempt to synchronise your fork from the GitHub interface and create a pull request, that pull request will fail. Instead, follow the instructions below.

The easiest way to do this is to delete your fork and re-clone. The commit history of the lesson has changed and you will be unable to commit until your fork reflects those changes (this is known as the burn it all down strategy):

1. Save your edits on locally or in a scratch space.
2. Delete your fork
3. Create a new fork or use the “edit” button on the page you wish to edit.
4. Apply your changes (NOTE The Workbench uses a different syntax. Here is a Transition Guide from Styles to Workbench for your reference).

Note that if you have a clone, you will need to also delete and re-clone.

Production Forks

If you have a fork of a lesson that you have modified significantly and wish to continue maintaining under The Workbench, contact Zhian Kamvar and he will help you transition your repository.

contributing without deleting

If you contribute directly on the lesson itself using the “edit” button on GitHub, a new branch will be created for you and you can edit on that branch without deleting your fork.

This method is not recommended because it runs the risk that you will accidentally merge histories in your fork.

Teaching

GitHub Forks

How do I create a fork for teaching?

A common pattern for teaching is to create a fork of a lesson, modify it to add or remove specific section. Because the pages on The Workbench are deployed by GitHub actions, there are a couple of extra steps you need to do to enable the pages to load after the transition.

In short, when you fork, to make it easier, you should bring in all branches, enable GitHub pages, and enable GitHub Actions. After that, you will have your lesson website and can teach from it.

You can find the instructions in issue 14 of the Dovetail blog series.

Workshop Websites

How do I add episodes to my workshop website?

Before 2020, instructors were occasionally encouraged to copy the episodes from a lesson into their workshop website to avoid situations where the lesson would change significantly while the workshop was being taught. In short, you can not do this. Instead, you can make a fork of the lesson and link that on your workshop website.

Coming up: versioned lessons

In the future, we will implement lesson versioning where you will be able to select a specific version of a lesson to teach from, so that you can always be sure that the content is stable.

Low-rent versioning with HTMLpreview

The website https://htmlpreview.github.io allows you to display HTML pages hosted on GitHub without needing to set up GitHub pages. If you do not want to fork, but still want a working version you can teach from, you can head to a workbench repository, select the gh-pages branch, select the index.html file and click on copy permalink and paste that into html preview:

For example: this is the workbench documentation as of 2023-02-07: https://htmlpreview.github.io/?https://github.com/carpentries/sandpaper-docs/blob/59651a69e7716c04edaf8f9c1c79abc18ce3e476/index.html

This is a very workable version of the lesson (with some styling differences as the default font could not be loaded).

The only catch is that you have to manually switch to instructor view by the URL: https://htmlpreview.github.io/?https://github.com/carpentries/sandpaper-docs/blob/59651a69e7716c04edaf8f9c1c79abc18ce3e476/instructor/index.html

And there you have a quick version of the lesson.

Learning

---

1. It should be noted that these conflicts are not all created by the transition. Conflicts are an inevitable consequence of long-running forks that are not regularly updated. The transitioned lesson just added to the conflicts.