carpentries-incubator / carpentries-incubator/collaborative-git-and-github-lesson

Add option for alternative shorter collaborative workflow exercise

Open
#36 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
R
Stars
0
Forks
3
PR merge metrics
No merged PRs in 30d

Description

## 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`](https://github.com/NLeSC/python-template/blob/main/template/%7B%25%20if%20HasWorkflows%20%25%7D.github%7B%25%20endif%20%25%7D/workflows/%7B%25%20if%20HasWorkflows%20%25%7Dnext_steps.yml%7B%25%20endif%20%25%7D.jinja) 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"](https://github.com/sjvrijn/git-workshop-radboud) repository with 26 issues asking for a new file with some (arbitrary) facts about an animal (aardvark, bee, chihuahua, ... [xerus](https://a-z-animals.com/animals/xerus/), yak, zebra) in a new `.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 `-` 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](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) 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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.