beta phase of The Carpentries Workbench

2022-12-12 to 2022-04-03

What is the Workbench beta phase?

The Carpentries Workbench, first released in January 2022, has been running without issue for several months with several early adopters, who have all contributed to its improvement from their feedback. It is now at the stage where we are confident that it is in a stable condition to be used for Carpentries Lessons as a whole. Of course, with over 100 maintainers and even more instructors, making a sudden change has the potential to be massively disruptive.

Instead, we are slowly releasing The Workbench in three stages over a 16 week period during which there will be parallel websites showing two versions of the same lesson1. For example, when you visit https://datacarpentry.org/R-ecology-lesson, there will be a banner at the top of every page that will give a link to the beta version of the lesson (under https://preview.carpentries.org/) and the dates the styles version will be deprecated and finally superseded.

This slow progression is designed to allow community members to familiarlize themselves with the new format and to build expertise within the community for May 2023 when the infrastructure is formally released.

The three stages are called “pre-beta”, “beta”2, and “pre-release”.

If you would like to participate in the beta phase, you can

Diagram of three phases of the beta release. At the top is box labelled 'current' that contains a GitHub logo, a cartoon of a lesson page. Below is a box labelled 'Pre Beta' with the same contents as the box above plus an additional GitHub logo in blue with a camera above it (to indicate a snapshot) and a new cartoon of a lesson page with a padlock over it. There is a clock indicating a timeframe of four weeks. The next box below is labelled 'Beta'. The GitHub logo has become blue and there is a lightning bolt and a line connecting it to the previous logo, indicating that a transformation happened. A smaller, grey GitHub logo is adjacent with a lock over it, indicating that it is archived. The old lesson page now has a lock and information symbol above it. The new lesson page does not have any symbols above it. The timreframe is 6 to 8 weeks. The final box is titled 'Release Candidate' and has a single blue GitHub logo, a faded old lesson page, and a new lesson page with a timeframe of 6 months

An overview of the Workbench beta phase for the Git repository and the website, separated into three stages. The entire process will take about 12 months until the pre-beta stage.

pre-beta (two repos, two sites)

Lessons in this stage will have a workbench version of the lesson live in a separate repository in a sandbox GitHub organisation3. This version will be a snapshot from the date of the pre-beta version. Any changes made to the snapshot will appear on the beta website, but will disappear as soon as the lesson enters beta. Maintainers are encouraged to clone this snapshot repository and try it out by creating pull requests that change content.

Tasks to try

The purpose of the pre-beta stage is to make sure maintainers are comfortable with working on the lesson. Anything that happens on the sandbox repository is not permanent. Below is a list of tasks for different members of the community to try.

As always, please provide feedback in our < 1 minute survey

During this time, you should take the time to merge or resolve any open PRs in your lesson. And yes, this is a big task and it is helpful to remember how to say ‘no’ in a way that respects the contributor’s time and effort. If you feel like you need help with a particular PR, please contact Zhian and he will help craft a response.

  • clone the lesson and build it locally (see the setup instructions)
  • merge one of the automated workflow update PRs that is opened by @carpentries-bot
  • review a PR that includes some failing accessibility checks
  • (R lessons only) review a PR using the preview of rendered changes
  • create an inline instructor note from existing instructor notes
  • fix a simple typo in a lesson—perhaps in a relatively non-obvious location e.g. in the setup instructions
  • fix some broken syntax in a lesson
  • write a link from one episode to another in the same lesson
  • trigger a rebuild of the lesson from GitHub Actions

Browse the lesson and give feedback on your impressions. Is everything where you expect it to be?

Make a contribution to an episode! Click on the “Edit this page” button and make a change.

beta (one repo using the workbench, two sites)

Lessons in this stage will undergo a lesson release of the styles version and a snapshot of the repository, including issues and pull requests, will be archived. The default branches (gh-pages and main) will be renamed and a transformation4 of the default branch will be inserted as main:

branch transformation new name
gh-pages none legacy/gh-pages
main none legacy/main
[default] remove styles commits; transform syntax to Workbench main

The default lesson URL will still be served from the legacy/gh-pages branch during this period. All new changes to the lesson will be made to the workbench version.

Tasks to try

As always, please provide feedback in our < 1 minute survey

Before this stage can happen, you must merge or resolve any open PRs in your lesson. If you feel like you need help with a particular PR, please contact Zhian and he will help craft a response.

During this stage, you are working on the lesson as you would normally, which means to address any issues or pull requests that come in and improve the lesson. In addition, I would recommend to continue to do the things you were doing during the pre-beta stage, but first:

  1. Update your local version of the lesson (instructions to update)
  2. Re-fork the lesson if you have a fork (see the instructions in the FAQ)

Browse the lesson and give feedback on your impressions. Is everything where you expect it to be?

Now that the lesson source is in a permanent stage, add an inline instructor note. Click on the “Edit this page” button in any episode and make a change.

Make a contribution to an episode! Click on the “Edit this page” button and make a change.

Updating your local clone

During this phase, you will need to take care to bring in the changes to your local clone because they WILL be different. Details can be found in The Lesson Transition repository:

The easiest way is to get the updates and avoid dreaded merges is to use the burn it all down approach. For those who are more confident in their git skills, read on.

The general strategy is the same as when someone changes the name of their default branch: rename your local branch, fetch the changes, and set the right branch to track upstream:

In your lesson, use these commands. DO NOT PULL FIRST.

git checkout gh-pages              # make sure you are gh-pages
git branch -m gh-pages legacy/gh-pages               # rename the gh-pages branch to legacy
git fetch origin                                     # fetch changes from GitHub
git branch -u origin/legacy/gh-pages legacy/gh-pages # make sure your legacy branch tracks
git checkout main                  # switch to the brand-new main branch
git remote set-head origin -a      # set main branch to be your local default

The general strategy is the same as when someone changes the name of their default branch: rename your local branch, fetch the changes, and set the right branch to track upstream:

In your lesson, use these commands. DO NOT PULL FIRST.

git checkout main                  # make sure you are on main
git branch -m main legacy/main     # change 'main' to legacy
git checkout gh-pages              # switch to gh-pages
git branch -m gh-pages legacy/gh-pages       # rename the gh-pages branch to legacy
git fetch origin                             # fetch changes from GitHub
git branch -u origin/legacy/main legacy/main # make sure your legacy branches track
git branch -u origin/legacy/gh-pages legacy/gh-pages 
git checkout main                  # switch to the brand-new main branch
git remote set-head origin -a      # set main branch to be your local default

Maintainers will continue to work on this workbench version of the lesson.

pre-release (release-candidate) (one repo using workbench, one site)

The styles version of the lesson (in the legacy/ branches) will be removed, the default version of the lesson will switch to The Workbench, and the workbench-beta website will redirect to the live lesson.

Lessons currently in the beta phase

Maintainers of the following lessons have agreed to use their lessons to test out the beta phase of The Carpentries Workbench: If you want to preview these lessons, please visit the lesson, browse around and then provide feedback in our < 1 minute survey

Lesson Workbench URL
R for Social Scientists https://preview.carpentries.org/r-socialsci
Introduction to Geospatial Raster and Vector Data with R https://preview.carpentries.org/r-raster-vector-geospatial
Instructor Training https://preview.carpentries.org/instructor-training
Análisis y visualización de datos usando Python https://preview.carpentries.org/python-ecology-lesson-es

These lessons are all in the first (pre-beta) stage and will transition to the second (beta) stage on 2023-02-03.

Timeline

gantt
    dateFormat  YYYY-MM-DD
    axisFormat  %d %b
    title       Schedule For Lessons in Workbench Beta

    beta phase Start   :milestone, 2022-12-12,
    Pre Beta           :      dcre-pb, 2022-12-12, 56d
    Beta               :      dcre-b, after dcre-pb, 56d
    Pre-release        :milestone, crit, after dcre-b

These are the official Carpentries lessons that have entered the beta phase. Note that three out of the seven participated in the early stages of the beta phase, but were unable to continue due to extenuating circumstances. 2022 was a tough year for many people and participating in the beta phase was a voluntary act for our volunteer maintainers.

I am grateful for all of the maintainers who have participated in any stage of the beta phase. All of the contributions from the maintainers of these lessons have helped bring stability and refinement to The Carpentries Workbench.

Community Lessons

The following community lessons will be migrated to the Workbench during the beta phase. At the moment, there is no definite timeline, but we will update that soon. Note that these lessons will skip directly from pre-beta into pre-release.

  1. It will be mostly the same content, save for small changes as described in the different stages.↩︎

  2. Note, this is NOT the same thing as an in-development lesson being in Beta.↩︎

  3. The sandbox organisation is called “Fish Tree Attempt”, which is a pun on Carpentry: carp—fish, tree—ent (after Tolkien), attempt—try↩︎

  4. For details of what will happen to the files and syntax during the transition, see The Transition Guide. During the transformation, we will also excise the commits from styles, which necessarily rerwite the history of the lesson, while preserving the commits from lesson content. This move has two benefits: 1. The list of committers on the lesson will better reflect the actual lesson contributors rather than the contributors to the template. 2. Lessons will be reduced in size so that downloading them and contributing to them will be easier. There is precedence for this: When Software Carpentry moved its lessons from the original swcarpentr/bc monorepo, they excised the commits related to each lesson from the repository, but preserved the history.↩︎