Instructor Notes

Using the Example Repository

Callout

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

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).

Collaborating with your Team

Collaborating with Newcomers

Share an example of a good README

It is helpful to share an example of a README when teaching this section. Use your own example if you have one, or otherwise share the README from the source repository of this training curriculum. We try to keep it updated and aligned with the recommendations here. If you identify anything that could be improved, please let the Maintainers know by opening an issue or a pull request.