Add option for alternative shorter collaborative workflow exercise

[sjvrijn]

Motivation

During a recent half-day workshop in Nijmegen, we were very time-constrained and only had ~30 minutes left for the collaborative workflow exercise. Following the standard pairwise task which would most likely have meant that the participants did not actually get to experience a full iteration of the collaborative workflow.

We devised the exercise listed below instead, which basically substitutes an instructor/helper for the pairwise participant. This significantly speeds up the process at the cost of needing one instructor/helper to serve as repo maintainer. During the one workshop we did, the feedback of participants was that they enjoyed the exercise.

Suggestion

It should be possible to create a template repository that includes a GH action to create a pre-specified, fixed set of demo issues automatically. See next_steps.yml in the NLeSC Python template repository for an example action that automatically creates issues. This would mean the instructors only have to create the repo based on the template with no further setup needed on the GitHub/repository side for the distributed collaboration case.

Important

My suggestion would be to prepare the template repo and to include it as an alternative exercise, to be used by the instructors if they have run out of time to perform the full exercise instead.

Exercise Description

1. Instructor creates a public GitHub repo

2. Instructor creates an issue for each of the N participants, asking for contributing a new file, unique for each participant to avoid merge conflicts.

   • For example: an "animal facts" repository with 26 issues asking for a new file with some (arbitrary) facts about an animal (aardvark, bee, chihuahua, ... xerus, yak, zebra) in a new <animal>.txt file.

3. Participant forks the repo

   • Could also be added as collaborator for the centralized collaboration, but that required gathering all github usernames beforehand.

4. Participant is assigned an issue

   • E.g. by numbering each participant in the classroom manually, or by using their index number in the collaborative document roll call list

5. Participant creates a feature branch using the <Issue-number>-<description> format, e.g. 5-add-eel-facts

6. Participant writes/adds/commits the file, and pushes

7. Participant creates a PR, using GH’s specific syntax in the description to automatically close the relevant issue when merged.

8. Instructor review the PR in the role of maintainer

9. [optional] Instructor request (arbitrary) change

10. [optional] Participant performs requested update, pushes new code and pings maintainer for re-review.

11. Instructor approves PR and merges.

    • In the centralized case, you could consider letting the instructor only approve the PR, and let the participant merge the PR themselves.

[loostrum]

This worked very well at the Nijmegen workshop, so I'm in favor of adding the exercise as you describe it here it to the lesson material.

[svenvanderburg]

Love your on-the-spot creativity! I wonder if we should work this out in a detailed and reviewed exercise (which takes time) or that we should just dump this workflow in an instructor note saying: "Hey if you are short on time you can do something like this."

@liekelotte I think you once shared this repo that creates a repo with a bunch of issues with me, do you know what I mean and can you share it again?

Can you paste the exercise text that you used here as well?

[sjvrijn]

@svenvanderburg In my suggestion text I'm linking to a GH action used by the NLeSC Python Template repo that generates a bunch of issues: next_steps.yml Ignore the jinja/copier templating stuff though 😅 (I've edited the text to make my link to the example more clear)

All improvisational effort at the time went into setting up the repo, so there was no time to write down any exercise text. We created issues and told the (9) participants what we wanted them to do.