faq.qmd

---
title: 'Frequently Asked Questions'
date: '2023-03-29'
---

::: {.callout-caution}

## 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](https://github.com/carpentries/workbench/discussions).**

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](reference.html#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](#teaching) or [Learning](#learning) sections.

### Why was R chosen for the infrastructure? {#why-r}

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](https://carpentries.org/blog/2021/07/infrastructure-testing/).

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](https://zkamvar.netlify.app/talk/carpentries-user-2021/) | [Use!R 2021 Video](https://youtu.be/vd8XZSuY_Rs?t=1240 "Zhian's talk from Use!R in 2021") | <https://zkamvar.github.io/user2021/#p1> |
| [Building Accessible Lessons with R and Friends](https://zkamvar.netlify.app/talk/carpentries-rstudio-2022/) | [`rstudio::conf(2022)` Video](https://www.rstudio.com/conference/2022/talks/building-accessible-lessons-r-friends/?wvideo=ssot3tfv28 "Zhian's talk from RStudio in 2021") | <https://zkamvar.github.io/rstudio-conf-2022/#p1> |

### Do I really need to use RStudio? {#do-i-need-rstudio}

No. We recommend using RStudio for [several reasons that pertain to ease of
use and standardisation across systems](#recommend), 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? {#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? {#workflow-plethora}

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](https://github.com/carpentries/sandpaper/tree/main/inst/workflows#readme).

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](https://carpentries.github.io/workbench-dev/remote/intro.html#workflows)
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](https://carpentries.github.io/workbench/workflow-guide.html#remote-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](https://carpentries.github.io/sandpaper-docs/pull-request.html) in the
Introduction to The Workbench.

### How do I add a custom logo?

For custom logos, you should do the following:

 1. [fork {varnish}](https://github.com/carpentries/varnish/fork) 
 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? {#custom-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`](https://carpentries.github.io/sandpaper/reference/set_config.html#custom-engines)

### Is there a Docker Container? {#docker}

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](https://github.com/carpentries/workbench/issues/39).

## Lesson Transition

This section is applicable for transitioning between the former
[carpentries/styles](https://github.com/carpentries/styles) lesson
infrastructure and The Workbench.

### How do I transition my lesson to using The Workbench? {#transition-new}

::: {.callout-warning}

#### Limited Support

Due to [significant staffing changes in late
2023](https://carpentries.org/blog/2023/12/saying-farewell-to-seven-carpentries-core-team-members/),
The Carpentries is unable to provide support for transitioning unofficial
lessons to use The Carpentries Workbench.

:::

You can use the [Lesson Transition Tool](https://github.com/carpentries/lesson-transition/#readme),
which will:

 1. create a submodule for your lesson
 2. filter out the infrastructure-related commits
 3. [transform the markdown syntax using {pegboard}](https://carpentries.github.io/pegboard/articles/intro-episode.html#jekyll-lesson-markdown-content)

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](https://github.com/carpentries/lesson-transition/blob/main/transition-workflow.md#register-a-lesson-submodule-to-this-repository)
 - [Transitioning and uploading a lesson](https://github.com/carpentries/lesson-transition/blob/main/release-workflow.md)


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

See [the above section](#transition-new) 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](https://github.com/carpentries/workbench/issues/51#issuecomment-1550028442).

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](https://github.com/MonashDataFluency/shell-novice/tree/2f4ee4bd9ed01513b8001192fc651ba3a5cca69e)
that had 16 commits _ahead_ of
[swcarpentry/shell-novice](https://github.com/swcarpentry/shell-novice).
Attempting to update the transitioned fork resulted in 188 conflicts[^conflict]\:

[^conflict]: 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. 

```
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
```

```sh
$ 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
```

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


### Local Clones {#local-clones}


#### How do I update my clone after the transition from styles? {#update-clone-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](beta-phase.html#updating-clone) on the
beta phase page.

### Post-transition GitHub Forks {#github-forks}

#### How do I update my fork after the transition from styles? {#update-fork-from-styles}

::: {.callout-important}

##### Before you read further

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

:::

::: {.callout-important}

##### 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](https://happygitwithr.com/burn.html)):

1. Save your edits on locally or in a scratch space.
2. **[Delete your fork](https://docs.github.com/en/repositories/creating-and-managing-repositories/deleting-a-repository)** 
3. **[Create a new fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo)** 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](https://carpentries.github.io/workbench/transition-guide.html)
   for your reference). 

Note that if you have a clone, you will need to also [delete and re-clone](#update-clone-from-styles).

<iframe width="100%" height="315" src="https://www.youtube-nocookie.com/embed/9DVwy818MIE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

::: {.callout-note}

##### 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. 

:::


::: {.callout-warning}

##### 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? {#teaching-fork}

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](https://carpentries.org/blog/2023/01/dovetail-14/#tips-and-tricks-for-using-the-workbench).

### 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](#teaching-fork) and link
that on your workshop website.

::: {.callout-note}

##### 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.

:::

::: {.callout-tip}

##### 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