Upgrade to new carpentries template

[bouweandela]

There is a new template for carpentries style lessons. It would be nice to upgrade. The template can be found here: https://github.com/carpentries/workbench-template-md

More information is available here: https://carpentries.github.io/workbench/

[ehogan]

https://carpentries.github.io/sandpaper-docs/migrating-from-styles.html details the steps required to migrate to the new Software Carpentry template. I managed to do the following two steps:

• Created a fork:
  • https://github.com/ehogan/ESMValTool_Tutorial
• Setup the transition tools:

  git clone https://github.com/carpentries/lesson-transition.git && cd lesson-transition
  git checkout -b ESMValTool_Tutorial-transition
  git submodule update --init git-filter-repo
  

But then couldn't complete the "install dependencies" step. I have opened carpentries/lesson-transition#107 to try to resolve this.

Once there is a usable installation, I believe the following steps in the instructions above should be straight forward.

Before doing this for real, we must:

• Merge or close all open pull requests on your lesson repository. Any open pull requests will be rendered invalid by the migration between infrastructures.
• Archive a final version of the tutorial in the old infrastructure by e.g. publishing a release to Zenodo.

[ehogan]

I managed to complete the "install dependencies" step:

• Install dependencies:
  • First, create and activate a Conda environment:

    (at the MO: module unload R)
    conda create --name transition-tutorial -c conda-forge --override-channels "r-base>4.4" r-gert libxml2 libxslt pandoc
    conda activate transition-tutorial
    export PKG_CONFIG_PATH=${CONDA_PREFIX}/lib/pkgconfig
    (at the MO: export CURL_CA_BUNDLE=$SSL_CERT_FILE  # for proxy reasons)
    

  • Update versions in the renv.lock file:
    • sandpaper to 0.16.10
    • gert to 2.1.4
  • Open R:

    R
    (answered "y" to the question "Would you like to restore the project library? [y/N]:")
    

  • Close R:

    q()  # Exit R
    (answered "n" to the question "Save workspace image? [y/n/c]:")
    

  • Create PAT token:
    • Instructions available at GitHub Docs: Creating a fine-grained personal access token
  • Cache the PAT token; instructions are available at GitHub Docs: Caching your GitHub credentials in Git:

    % gh auth login
    ? Where do you use GitHub? GitHub.com
    ? What is your preferred protocol for Git operations on this host? HTTPS
    ? Authenticate Git with your GitHub credentials? Yes
    ? How would you like to authenticate GitHub CLI? Paste an authentication token
    Tip: you can generate a Personal Access Token here https://github.com/settings/tokens
    The minimum required scopes are 'repo', 'read:org', 'workflow'.
    ? Paste your authentication token: ****
    - gh config set -h github.com git_protocol https
    ✓ Configured git protocol
    ✓ Logged in as ehogan
    

But then the next step fails:

Rscript establish-template.R template/

with:

Error in libgit2::git_clone : 
  failed to connect to github.com: Connection timed out
Calls: <Anonymous> -> raise_libgit2_error
Execution halted

😞

[tobyhodges]

Hi @ehogan, here are some details of what I did to produce https://github.com/tobyhodges/ESMValTool_Tutorial

But then couldn't complete the "install dependencies" step. I have opened carpentries/lesson-transition#107 to try to resolve this.

This is my fault. The instructions assume that the environment description on the lesson-transition repository is up-to-date but I have not been keeping on top of that effectively. To update the environment, I ran renv::update() followed by renv::snapshot(), instead of renv::restore() as written in the migration guide. Sorry about that.

Error in libgit2::git_clone : 
  failed to connect to github.com: Connection timed out
Calls: <Anonymous> -> raise_libgit2_error
Execution halted

The issue here is probably that your network does not allow HTTPS connections (an educated guess based on something @astroDimitrios mentioned on Slack), and the transition scripts are configured to run over that protocol.

On my side, I ran into one issue with the _episodes/06-preprocessor.md file. I had to tweak the number of > lines in a callout box to get the transition to work. The reasons for these failures are a bit of a mystery to me, but based on past experience and some trial and error, I was able to resolve it.

The transition ran pretty smoothly after that.

Next steps

If you want to take my transitioned version you will need to clone it, adjust the remote URL to point to this repository, then follow steps 4.3 onwards at https://carpentries.github.io/sandpaper-docs/migrating-from-styles.html#github (My guess is that the curl command will not run, due to the HTTPS block I mentioned above. Hopefully you can download the relevant workflow file manually and copy it into the repository instead.

How many other lessons do you have that need to be transitioned? If you can share links to the relevant repositories and are willing to wait a couple of weeks, I will be happy to take care of them for you.