Instructor Notes

Using the Example Repository

Setup for Hosts

See Setting Up Example Repositories for instructions on how to automate the creation of example repos for the skill-up.

The example repository contains source files for a lesson about how to bake sourdough cinnamon rolls.

The content of the lesson itself is largely inconsequential for the skill-up, except that it contains several deliberate errors.

The repository has three open issues and three open pull requests, designed to be used as illustrations of the various concepts taught in the lesson.

After the Skill-up

At the end of the skill-up, I recommend transferring ownership of the individual repositories to their respective participants, and deleting the repositories for any participants who did not show up. At the moment, you will need to do these things manually but I hope to add another script to automate this soon.

Pair Programming-like Approach to Teaching

Instead of sharing your screen and running through the live demo yourself, try asking for a volunteer at the beginning who will share their screen and follow your instructions while you guide them through the process. Feedback suggests that this is a more effective and impactful way of running the session. Even better, why not try asking for a new volunteer at regular points throughout the skill-up, e.g. one volunteer for issue triage, another for PR reviews, another for conflict resolution, etc.

Managing issues

Example Issues

Use your example repository to demonstrate how to label issues, and to discuss the appropriate use of some important labels here.

If you are using example repositories generated with the accompanying script, I recommend the following labels:

  • Issue 1 (“Typos in recipe instructions”): type:typo text, good first issue, help wanted
  • Issue 2 (“Cinnamon rolls burnt 🔥”): type:bug, good first issue, help wanted
  • Issue 3 (“Alternative to sourdough cinnamon rolls”): status:refer to cac, type:discussion

Referencing pull-requests and issues

Example Issues/PRs

If you are using example repositories generated with the accompanying script, Issues 1 & 2 should have pull requests associated with them already, which you can use to highlight this.


Reviewing pull-requests

Reviewing Example Pull Requests

Use the example repository to show an example of reviewing a pull request, demonstrating:

  • line-specific comments
  • suggesting a change
  • approving/requesting changes at the end of the review

If you are using example repositories generated with the accompanying script, I recommend using the “Add detail to the project README” pull request to demonstrate line-by-line commenting and suggesting changes: you can suggest that the contributor uses a different email address, for example.

The purpose of the other two pull requests is to:

  1. Repeat the reviewing workflow two more times, giving you a chance to emphasise the important steps and encourage good communications practices.
  2. Create a merge conflict that can be resolved in the GitHub web browser interface (see the Instructor Note for the next episode).

Resolving conflicts

Example Conflicts

Use the example repository to show an example of a pull request that is blocked by a simple conflict, then demonstrate how you can resolve this using the web interface.

If you are using example repositories generated with the accompanying script, a simple conflict can be introduced by merging one of the two pull requests suggesting changes to recipe_instructions.Rmd. These two pull requests (“Fix typos in recipe instructions” and “Fix oven temperature conversion”) make edits to the same line in the file.

To resolve the conflict, keep the changes made by both pull requests (i.e. the typo fix and the temperature conversion).


Still Have Time Left?

If you still have time remaining in the skill-up session, consider using it to:

  1. Demonstrate the VS Code Web IDE interface to a repository, accessed by hitting . while browsing the contents of the repository.
  2. Talk about debugging strategies when GitHub Actions fail on a repository/pull request.
  3. Open up a discussion about how Maintainers could coordinate their efforts on a lesson.