Software Carpentry Lesson

Content

Collection of materials to host a Software Carpentries workshop. These materials are adaptations from the lessons provided by the Software Carpentry.

The data and exercises for participants are provided in a separate repository: https://github.com/mwakok/software_carpentry_learner and should be cloned or downloaded as a zipfile prior to the workshop. They will create all further materials in the local directory of the repository.

I am currently exploring the useability of Jupyterlite either as a backup environment for participants who encounter issues with their own installation or as general workshop environment. The workshop materials can be executed through the Jupyterlite instance running in this repository.

Branching Policy

Note that this is the MAIN branch -- which is not the one that should be used for actual workshops. Each run of the workshop should be associated with a branch names with the Carpentries slug for the run. At the end of the run, the review meeting should consider whether any materials committed to that branch should be merged in order to become part of the template for future runs.

Feedback

Feel free to use these materials and I welcome any feedback (mistakes, suggestions) in the form of an issue.

Workshops

Nov 2021

• Workshop homepage
• Python lesson plan
• Status of repository at time of workshop

Oct 2022

• Workshop homepage
• Python lesson plan day 1 day 2
• [Status of repository at time of workshop]

Tools

For online teaching, I use the following tools

• Git and Gitbash

• Python installation with Anaconda

• Windows Terminal Preview with split screen

• Display the terminal history. For compatibility with gitautopush, see the instructions below. For easy management of the two terminals, I use the (horizontal) split window feature of Windows Terminal Preview.

• Gitautopush to upload the notebooks to a GitHub repository during the workshop for reference. This setup requires a passsword-less ssh key. For more details, see below.

• Windock for quickly managing the position, aspect ratio, and size of my windows for screen sharing in online teaching.

• For plenary exercises, I use polls for Zoom

• To control my webcam background, I pipe a virtual webcam from XSplit VCam into OBS, ensuring consistent backgrounds across various online meeting programs (Teams, Zoom, Skype)

Set up gitautopush

During the workshop, I want to provide a link to a copy of the notebooks I develop as part of hands-on teaching. This allows the participants to look up past commands and quickly rejoin the session after getting stuck, without needing to access all the lesson materials. The most practial solution I settled on is using gitautopush. gitautopush lets you automatically commit and push the latest changes in a git repository to GitHub. By letting gitautopush track the changes I make in the lesson notebooks, they are progressively made available in a GitHub repository at a defined interval (default is 10 seconds). You can then ask the participants to visit the GitHub url with the notebook, and they will be able to see the latest version of your notebook. Participants will need to refresh the webpage to see the latest changes.

Steps

1. Install gitautopush with pip install gitautopush. As I use a conda environment for the Python lesson, I recommend installing the package in the conda environment you use for teaching.

2. gitautopush requires permission to push to your GitHub repository. A password-protected ssh key will ask for a password for each push, stalling the automated push. Two possible solutions are:

   • (Recommended) Use an ssh-agent for a single sign-on. In a terminal, start the ssh-agent with

     eval `ssh-agent` 
     

     Then, run

     ssh-add ~/.ssh/id_rsa
     

     to add the id_rsa private key (replace ssh-key name for other keys if needed). You will get prompted for your password, and after providing this, no further password prompts are required for the provided key during this terminal session.

   • (If all else fails) You can create a passwordless ssh-key for GitHub. Create a new rsa ssh-key called id_rsa_open, leaving the password blank, and add the key to GitHub. Then, configure ssh to use this key by adding the following lines to ~/.ssh/config (create the file if it doesn't exist yet):

     Host github
         HostName github.com
         IdentityFile ~/.ssh/id_rsa_open
     

     As passwordless ssh-keys are a security risk, make sure to change the IdentityFile to your regular ssh-key and delete the key after teaching.

3. Either create a new repository (local and online) or create a new branch in the repository you want to upload the changes to. In my case, I use a notes branch in the repository that contains the learner materials. Note that gitautopush requires that the repository has at least a single previous push.

4. In the same terminal you set up the ssh-agent, run gitautopush in the local (git) folder you will use for teaching, by executing

   gitautopush .
   

   Minimize the terminal to run it in the background. For more details, visit the gitautopush documentation.

Sharing terminal history with gitautopush

If your lesson requires you to upload your executed terminal commands with gitautopush, we will need to adjust the settings for displaying the terminal history. Credits go to Giordano Lipari (@wmotion) for this solution.

1. Follow steps 1-2 in the gitautopush setup.

2. Create a new git repository separate from your working directory and create the file command_history.txt. We will pipe your command history to this file.

3. Commit and push your (empty) file to a GitHub repository.

4. Next, we will set up two new terminals to display the command history. In a new(!) terminal, set up your terminal to store each command in the history by executing

   export PROMPT_COMMAND="history -a;$PROMPT_COMMAND"
   

   Then, in a second terminal (or horizontal terminal split in Windows Terminal Preview), execute

   FILE="<path-to-command_history.txt>"
   tail -n 0 -f ~/.bash_history | tee $FILE
   

   In addition to displaying the command history, all commands will be written to command_history.txt. If needed, you can use tee -a $FILE to append to command_history.txt instead of overwriting the file.

5. Start gitautopush in the repository containing command_history.txt. Ensure that you have enabled the ssh-agent for single sign-on. You can now commit and push all changes to the command history to your GitHub repository.

License

This work is licensed under a Creative Commons Attribution 4.0 International License.