Scheduling early transition to Workbench

[tobyhodges]

Short version: are you are willing to volunteer your lesson for early transition to The Carpentries Workbench
infrastructure?

---

Longer version below:

As I hope you are already aware, @zkamvar and the rest of the Curriculum Team are preparing to roll out the new lesson infrastructure, The Carpentries Workbench, across all of The Carpentries official lessons in early May 2023. This means that all Data Carpentry, Library Carpentry, and Software Carpentry lesson repositories will be modified to adopt the new infrastructure at the end of this month.

As you might imagine, coordinating a rollout like this involves a large amount of time and effort, and one thing that will really help us to keep to the schedule and avoid disruption for the community is to be able to prepare some lessons for
transition before the 1st May deadline.

With this in mind, I invite you to volunteer to schedule an early transition for theis lesson repository. If you expect to have time to adopt the Workbench version of the lesson repository in the next couple of weeks, please reply to let me know. As lesson Maintainers, these are the things you will need to be prepared to do for the transition:

1. Be prepared to quickly merge pull requests from Zhian. These pull requests will help update the lesson and aid the transition process.
2. Close any outstanding pull requests. Your repository currently has very few or zero open PRs, but we cannot rule out the possibility that someone will open more in the time between now and when the transition takes place. Open PRs will be invalidated when the transition takes place.
3. Preview the lesson (in the https://github.com/fishtree-attempt organisation) when it is available. Zhian will open an issue in your repository, tagging you when the preview is available. You should reply on that issue if you notice any problems with the Workbench version of the lesson site and repository in the preview.
4. Just before the transition happens, the repository will be temporarily set as read-only and an issue will be opened (see an example from the Maintainer Onboarding curriculum: Transition to Workbench carpentries/maintainer-onboarding#69)
5. After the transition, delete and recreate any forks and local clones you have of the repository and then confirm that you have done so (you will be given specific instructions in an issue).

If you are willing and able to help us ensure a smooth rollout of the Workbench, please reply to let me know that you are happy to volunteer your lesson for early transition. If there is a specific date you would like the transition to take place (or that we should avoid), please also mention that.

[jenmawe]

@tobyhodges Let me slack Abigail and Owen. I for one think this is a great idea.

[abigailsparling]

@tobyhodges We've discussed and are good to move ahead with the early transition.

[tobyhodges]

Excellent news, thank you all for your help. Watch out for pull requests from @zkamvar and me in the coming days, as we prepare for the transition.

[zkamvar]

Thank you for participating in the early transition to The Workbench. I have been able to render a preview of your lesson at https://fishtree-attempt.github.io/lc-marcedit.

I am tracking issues for your lesson in carpentries/lesson-transition#64. I will be updating the preview next week as I work on any remaining issues.

Please inspect the preview and make note in carpentries/lesson-transition#64 if you see anything that needs to be fixed (e.g extra templating, narrow tables, or malformed text).

[jenmawe]

Thanks @zkamvar . I will take some time today and next week. Is it ok with you if we have until at least next Friday to review everything? I'm out for 2 days and get back to the office on Wednesday.

[tobyhodges]

Hi @abigailsparling @jenmawe @ostephens we are getting ready for an early transition for this lesson, and we have prepared a schedule for early lesson transitions.

Please check that document to see the date we have planned for transitioning this lesson, and adjust the sheet if a different date would be more convenient for you (no more than three lessons per day, please!). The README sheet gives more information. If we don't hear from you, we will go ahead with the transition on the date shown in that document.

[jenmawe]

@zkamvar We looked at the lesson and found the following things that appear a little off to us:

1. Set Up
   Should this bit be removed? It appears right under the Design section (Set Up)
   {% comment %} This is a comment in Liquid {% endcomment %}

2. Headings either above or below the Overview section. Could these all be below the Overview section?
   For example, in https://fishtree-attempt.github.io/lc-marcedit/01-introduction.html, the What is MarcEdit? is above the Overview section whereas Working with MARC files, https://fishtree-attempt.github.io/lc-marcedit/03-working-with-MARC-files.html, is below.

3. Lesson 3: The tables are a bit wonky. We are wondering if you have any suggestions on how to deal with MARC tag, indicators and subfield where there are a lot of \, $ such as 655 \4 $aElectronic books in this new format?

• First call out (“Working with MARC files”) not displaying correctly, call out markdown visible maybe because of the erroneous >?

• In MARC field breakdown table, $ displaying as ( despite being wrapped in , see : $aThe Lord of the Rings /$c J.R.R. Tolkien.

• Funky display in MARC field breakdown table where $ is not wrapped in , see: The field content contains the subfields (indicated using the '$' symbol) and the text. Because the subfields use the '$' symbol, any real occurrences of the dollar symbol (e.g. for currency) is shown as "[dollar]" instead. Unlike in some cataloguing applications, there are no spaces between subfield codes and the subfield text.

4. Switch between instructor and learner view
   When we go to switch, the box is slightly outside of the window frame. I can read half of it and know which view it is but it is hard to read and view the entire box to click on.

Again thanks for doing this. Overall this is a new look at our lesson and we already have ideas on how to improve it.

[zkamvar]

Hi @jenmawe, thank you for your comments. Please note that while I can fix a lot of things in the automation, there are some things that are much more efficient to fix in the source (e.g. #67).

1. Set Up
   Should this bit be removed? It appears right under the Design section (Set Up)
   {% comment %} This is a comment in Liquid {% endcomment %}

Ah yes, the nefarious liquid comment. I'll try to get something to clean that since it's definitely something that should be scrubbed.

2. Headings either above or below the Overview section. Could these all be below the Overview section?
   For example, in https://fishtree-attempt.github.io/lc-marcedit/01-introduction.html, the What is MarcEdit? is above the Overview section whereas Working with MARC files, https://fishtree-attempt.github.io/lc-marcedit/03-working-with-MARC-files.html, is below.

This is an off-by-one error from me. I'll fix it so that the objectives are a the top. That being said, I'm not sure why the callout at the top is not working :(

3. Lesson 3: The tables are a bit wonky. We are wondering if you have any suggestions on how to deal with MARC tag, indicators and subfield where there are a lot of , $ such as 655 \4 $aElectronic books in this new format?

yes, wrap all the MARC tags (especially dollar signs) in backticks like #67

• First call out (“Working with MARC files”) not displaying correctly, call out markdown visible maybe because of the erroneous >?
• In MARC field breakdown table, $ displaying as ( despite being wrapped in backtics , see : $aThe Lord of the Rings /$c J.R.R. Tolkien. ```
  `` * Funky display in MARC field breakdown table where $ is not wrapped in backtics, see: The field content contains the subfields (indicated using the '$' symbol) and the text. Because the subfields use the '$' symbol, any real occurrences of the dollar symbol (e.g. for currency) is shown as "[dollar]" instead. Unlike in some cataloguing applications, there are no spaces between subfield codes and the subfield text.`` `` ``

4. Switch between instructor and learner view When we go to switch, the box is slightly outside of the window frame. I can read half of it and know which view it is but it is hard to read and view the entire box to click on. Again thanks for doing this. Overall this is a new look at our lesson and we already have ideas on how to improve it.

I'm not sure I understand this question. In any case, this is not something I can work on during the transition.

[jenmawe]

Hi @zkamvar. This is great information to have. We were wondering what you could do on your end and what needed to be done on ours.

Once the transition is done, we'll look at those tables in all our lessons to make sure that they display correctly. We are also going to look at some of our images as well.

[zkamvar]

Hi @zkamvar. This is great information to have. We were wondering what you could do on your end and what needed to be done on ours.

Please wrap all the MARC tags (especially dollar signs) in backticks like #67

[zkamvar]

I have addressed the issues with the headings. It will be rebuilt on the preview soon

[jenmawe]

Headings look great @zkamvar

[tobyhodges]

I have opened #69, which I think will fix the issue of that table in the first callout of episode 3 not being rendered in the Workbench version of the lesson.

[zkamvar]

Nice. Thank you, Toby. I will check it out

[zkamvar]

It looks like that DID fix the issue THANKYOU!. I'm still not exactly sure why it was problematic in the first place, but I'm okay with moving forward.

Note for the maintainers: a lot of the tables are encoded in HTML. I would recommend, pasting the HTML source from these tables into https://pandoc.org/try/ and converting them from HTML to markdown_github. This will give you a table that will be easier to edit. You can find a reference on what The Workbench expects from tables in https://carpentries.github.io/sandpaper-docs/episodes.html#tables

[jenmawe]

Thanks @tobyhodges and @zkamvar. Do we consider the transition over at this point?

Another question, we're trying to get this lesson to the alpha stage. Do you have any recommendation for that?

Jennifer

[zkamvar]

Thanks @tobyhodges and @zkamvar. Do we consider the transition over at this point?

Not quite yet. The transition will happen tomorrow. This process was to address any issues that needed to be fixed before the automated transition. I will make comments here during my progress transitioning tomorrow. See swcarpentry/shell-novice-es#65 (comment) for an example.

[zkamvar]

This lesson will be converted to use The Carpentries Workbench
To prevent accidental reversion of the changes, we are temporarily revoking
write access for all collaborators on this lesson:

• @jt14den (admin)
• @ostephens (admin)
• @jenmawe (admin)
• @abigailsparling (admin)

If you no longer wish to have write access to this repository, you do not
need to do anything further.

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

If you wish to regain write access, please re-clone the repository on your machine and
then comment here with I am ready for write access :rocket: and the
admin maintainer of this repository will restore your permissions.

If you have any questions, please reply here and tag @zkamvar

[zkamvar]

The deed is done. The infrastructure takes a few minutes to bootstrap and cache the packages for the lesson build. Once the build is done, I will switch github pages to deploy from the gh-pages branch and you will have your workbench lesson.

Thank you all for your enthusiasm and your patience!

[zkamvar]

The Workbench version is now live: https://librarycarpentry.github.io/lc-marcedit/

In addition, here is map of commits that were changed during the transition

[jenmawe]

@zkamvar Thank you for all the work you've done to switch us to Workbench! And also a big thanks to @tobyhodges.

I've gone ahead and forked this report. I am ready for write access 🚀

[zkamvar]

@jenmawe I have granted you access to the maintianer team. This repository was peculiar in that you were listed as an outside collaborator. You will find an invite to the team in your email.

[abigailsparling]

@zkamvar I am ready for write access 🚀

[zkamvar]

@abigailsparling I have granted you access to the maintianer team. This repository was peculiar in that you were listed as an outside collaborator. You will find an invite to the team in your email.

[ErinBecker]

Hi @jt14den and @ostephens - You have not yet responded here to report that you completed the steps listed by @zkamvar above to regain your Maintainer access to this repository. The lesson infrastructure transition required a second Maintainer team to be temporarily created for all lessons, which can only be removed when all Maintainers have confirmed that they are ready to have their access restored. Maintenance of both teams is not sustainable for The Carpentries in the long run. At the beginning of November 2023 (note the deadline has been extended) we will remove access for Maintainers who have not taken the necessary action to continue working on the repository.

The Curriculum Team is truly grateful for everything you have already done as a Maintainer and we do not want to lose you! But we also understand that circumstances change and you may no longer have capacity to continue in your role. If you wish to retain your access and keep supporting the community, please follow the steps above then confirm that you are ready by commenting I am ready for write access 🚀 on this thread before the end of your day on Wednesday 1st November.

[ostephens]

@zkamvar I am ready for write access 🚀

[tobyhodges]

Thank you @ostephens. Zhian is out of office for the next few days but we will restore your access ASAP

[jt14den]

I am ready for write access 🚀

[zkamvar]

Congratulations, everyone has write access!