Workbench Beta Test

[drakeasberry]

Hello all other maintainers. @zkamvar is currently looking for early adopters to participate in the Workbench Beta test and I would like to help out by volunteering our lesson for use during the testing phase. It comes with some conditions (listed below) that I would like to make sure everyone is okay with before proceeding. Let us know if you all have any questions, concerns or reservations.

The Workbench Beta Phase has three stages:

Pre-Beta: snapshot of the lesson is created and hosted at the beta URL for 4 weeks. This version is a sandbox for you to explore on GitHub with no risk of destroying anything. During this time, it is important to resolve (merge, defer, or close) any pull requests that currently exist on the lesson.

Beta: your repository is transformed to default to the "main" branch, which will contain the workbench version of the lesson. The styles version is frozen and will live in the "legacy" branch. The success criteria for this is for at least two pull requests to be received and merged from bots and community members.

Release Candidate: The styles version is removed and work continues to address minor formatting errors that may have arisen due to the conversion.

[zkamvar]

Bumping for the @datacarpentry/r-raster-vector-geospatial-maintainers: I have this lesson currently scheduled to enter workbench pre-beta on Tuesday, July 26th https://github.com/carpentries/workbench/discussions/11

I can not enter a lesson into the beta phase unless all maintainers opt-in.

[jsta]

Is the purpose of the workbench beta to streamline the styles upgrading process? Or is styles going away?

[zkamvar]

Hi @jsta,

Is the purpose of the workbench beta to streamline the styles upgrading process? Or is styles going away?

Styles is going away. All lessons will switch over to The Workbench in January 2023. The Workbench is stable, but because this is a large change, we still need unguided feedback from maintainers, instructors, and learners, before we convert all lessons to The Workbench. For your reference, here is a guide to how The Workbench compares to Styles: https://carpentries.github.io/workbench/transition-guide.html

[jsta]

Looks great! Love getting rid of the double > > in challenge/solution blocks.

[zkamvar]

It will also make your lives as maintainers of an R lesson a lot easier because you get three new features:

1. Only files that change are rebuilt
2. pinned package versions that update monthly via PR
3. automated PR comments that show you exactly what changed in the rendered markdown contents

[zkamvar]

@arreyves, as a maintainer, are you okay with going forward with the beta test?

[zkamvar]

Hello @datacarpentry/r-raster-vector-geospatial-maintainers,

Thank you for your patience during the last quarter. I am pleased to announce that the transition to beta phase for this lesson will take place in 4 weeks on 2022-10-31.

Timing

the beta phase is divided into the following schedule of stages

• 2022-10-31: pre-beta stage (two repos, two sites)
• 2022-11-28: beta stage (one repo, two sites)
• 2023-02-06: pre-release stage (one repo, one site)

Please let me know if this does not work for you and I will do my best to accommodate. Importantly: please resolve (close or merge) any open pull requests before 2022-11-28 because the beta stage will involve changing the folder structure of this repository which will render any existing pull requests invalid.

Pre Beta Tasks

During this first pre-beta stage of the Beta Phase, I will give you access to https://github.com/fishtree-attempt/r-raster-vector-geospatial and encourage you to test out the following things on the lesson to get familiar with The Workbench. Here are some suggestions:

• clone the lesson and build it locally
• (optionally trigger and) merge and automated workflow update PRs that @carpentries-bot opens
• review a PR that includes some failing accessibility checks
• (R lessons only) review a PR using the preview of rendered changes
• fix a simple typo in a lesson - perhaps in a relatively non-obvious location e.g. in the setup instructions
• write a link from one episode to another in the same lesson

I will be recording a short video describing the changes you will see in the next week, so be sure to keep your eyes out for that.

[arreyves]

@arreyves, as a maintainer, are you okay with going forward with the beta test?

Hi @zkamvar ,

Looks like it comes with a bunch of enhancements so why not? I'm going to be trying it out...

[zkamvar]

Hello @datacarpentry/r-raster-vector-geospatial-maintainers,

https://github.com/datacarpentry/r-raster-vector-geospatial/pull/380 has been merged and I have created the pre-beta snapshot of the lesson at https://github.com/fishtree-attempt/r-raster-vector-geospatial. I have invited all the maintainers on this lesson to a team that has maintain access for the lesson. This version of the lesson is a snapshot and is available for you to play around with and test out without risk of affecting the lesson as a whole. In 28 days, I will perform the full conversion on this lesson. Please ensure that all PRs are closed before this happens.

As a reminder, you can check out the setup instructions to get yourself ready to build it locally.

Here are some tasks that you can try out during this 28 day period and please take a minute to give some feedback: https://carpentries.typeform.com/to/KRBl4IZM

• clone the lesson and build it locally
• merge one of those 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
• 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

If you have any questions, feel free to ask!

[zkamvar]

Hi @datacarpentry/r-socialsci-maintainers,

Just a reminder that before the transition, all of the current pull requests must be resolved.

I also highly recommend for you to play around with the snapshot repository! You all have full maintain access and are free to do whatever you like. Here are some options:

• ~~Check out the automated pull request to update packages on the snapshot repository~~ (thank you @jsta!) Check out the changes that come from updating packages. I've written some documentation of what to expect.
• Trigger an automated pull request to update workflows (these were recently updated in sandpaper 0.10.7)
• Use sandpaper::validate_lesson() locally to find and improve inaccessible elements of the lesson
• Add an instructor note or two inline for the lesson from the narrative instructor notes

As always, please provide feedback about your experience with the workbench.

[zkamvar]

Workbench Beta Phase Timeframe Adjustment

Note: this is identical to the message I sent directly via email

The beta phase has been in progress since the end of October, but because of various changing circumstances, I will be pushing back the beta phase timeline according to the revised schedule below, synchronising all of the beta phase repositories. With this new timeline, you will have more time to explore the repository snapshots, I will have time to provide more clear communications, and—because everyone will go through each stage synchronously—you will all be able to exchange tips and tricks together.

Note that Toby Hodges, Vini Salazar, and I will be hosting weekly helpdesk sessions, whose times we will send to you soon.

Here is the revised schedule, which you can also find on The Workbench beta phase website:

• 2022-12-12 (pre-beta): (re-)release all beta phase lessons to the pre-beta stage, which will have a parallel snapshot at https://github.com/fishtree-attempt/ hosting the Workbench preview on https://preview.carpentries.org/.
  • During this time, we encourage you to explore the repository. Here is a list of tasks to get started. Remember, This preview version is temporary, so you do not have to worry about making any mistakes here.
  • Take the time to merge or resolve any open PRs. 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.
• 2023-02-06 (beta): do in-place conversion of all beta phase lessons to use The Workbench by default. The default lesson site will still point to a snapshot of the jekyll version from 2023-02-06, and the preview lesson site will show the Workbench hosted on the main branch of the repository.
  • IMPORTANT: before this happens, all maintainers MUST be aware of this change and must merge or resolve any open PRs. Remember that it’s okay to say no and/or contact Zhian for wordsmithing.
  • Zhian will create a video describing what this process is doing
  • The broader maintainer community will be alerted that they have three months to merge or resolve their open PRs at this time.
• 2023-04-03 (pre-release): The Workbench will become the default version of the lesson and the Jekyll version will be removed. A blog post will go out alerting everyone of the change.

We will make the conversion of all of our lessons to use The Workbench on 2023-05-01

Thank you once again for agreeing to participate in the beta phase of The Carpentries Workbench. Your efforts in testing the infrastructure on your established lessons are invaluable to improving the workbench and I want to make sure that we take the time to get that right.

[zkamvar]

Hello and happy new year!

This is a reminder that on 06 February 2023 (just under four weeks away), your lesson repositories will be transformed to use The Carpentries Workbench. This is the irreversible second stage of the beta phase where the Workbench version of the lesson will be live and the styles version will be frozen.

Before 06 February 2023

1. (MUST DO) Merge or resolve any open PRs (If you are unsure of how to resolve some PRs that need more time, here's a guide on how to say 'no')
2. (recommended) Try out the pre-beta tasks to get familiar with The Workbench

After 06 February 2023

The lesson repository will change with a trimmed-down git history that reflects authorship. To prevent accidental overwriting of repository content, I will temporarily change your access to the repository as ‘read-only’. To regain ‘maintain’ access,

1. (MUST DO) make a fresh clone of or update your lesson on your computer.
2. (MUST DO) respond here with I am ready for write access :rocket:

Have Questions?

If you have any questions, would like help resolving PRs, or anything at all, you can email, slack, or schedule a meeting with me: https://calendly.com/zkamvar.

[drakeasberry]

@zkamvar All pull requests have been closed at this time.

[zkamvar]

Hello Maintainers,

Today is the day the lesson transitions into the second stage of the beta phase :tada:

I have created lesson release for this lesson and also have downloaded an archive of the repository and all associated comments. Before the end of the day, I will do the following:

1. temporarily restrict push access for the maintainers while I make the transition
2. set the config to display the beta stage banner (red), which will indicate that the styles version is locked
3. perform the transition (here is a rough 3 and a half minute video of what you can expect after the transition: https://youtu.be/kvmDlgjV8NA)

Once the transition happens, I will give access to those who follow the instructions:

• (MUST DO) make a fresh clone of or update your lesson on your computer.
• (MUST DO) respond here with I am ready for write access :rocket:

Thank you all for the commitment to testing this out and for all your feedback so far!

[zkamvar]

~~Also note: I will manually push up the results of the gh-pages branch as there is a GitHub Actions error that I am unable to easily fix~~

~~Edit: this appears to have fixed itself ᕕ( ᐛ )ᕗ~~

Edit of my Edit: there has been a problem with the natural earth download links and I fixed them by setting them to use HTTPS

[zkamvar]

The transition is done. When you have created a fresh clone of the lesson, please comment here with I am ready for write access :rocket: and I will grant you write access to the repository (note that we are going to leave the main branch protected).

[jsta]

I am ready for write access :rocket:

[zkamvar]

done!

[zkamvar]

Thank you all for your hard work getting the pull requests merged and giving feedback.

Now that you all have access, here are some resources that can help you understand how to handle the transition:

1. What you can expect from the transition 📹: https://carpentries.github.io/workbench/beta-phase.html#beta
2. How to update your local clone 💻: https://carpentries.github.io/workbench/beta-phase.html#updating-clone
3. How to update (delete) your fork (if you have one) 📹: https://carpentries.github.io/workbench/faq.html#update-fork-from-styles

[zkamvar]

I have created a video that describes situations where folks will accidentally create PRs from styles repositories, as documented in The Transition from Carpentries to Styles section in the Pull request documentation: https://youtu.be/FRZKbCz-9Eo (note that this only applies to R-based lessons)

The example in the video is shown in https://github.com/datacarpentry/r-socialsci/pull/433

[drakeasberry]

I am ready for write access :rocket:

[zkamvar]

done!

[drakeasberry]

Workbench switch has been merged with PR #410, which removed banner with links to workbench site; closing issue.