Skill-up: GitHub for Maintainers and Lesson Developers: All in One View

Content from Managing issues

Last updated on 2023-10-11 | Edit this page

Estimated time: 30 minutes

Overview

Questions

How can labelling help me manage issues on a repository?
How do I add labels to issues?
What are the recommended labels, and when should I use them?

Objectives

After following this section, participants will be ready to practice the following skills:

explain the value of labelling issues
apply labels to issues
explore the set of labels recommended by The Carpentries

Issue Triage

Maintainers typically do not have time to respond immediately to every new issue and comment that is added to their repository. In a more common scenario, a Maintainer visits their repository and finds several new issues and pull requests, plus some new comments and changes to those that were open at the end of their previous visit.

A good first step to take in these circumstances is issue triage: time spent processing the open issues and figuring out what should be prioritised, what can be closed, what needs to be brought to the attention of others in the community (co-Maintainers, Curriculum Advisors, would-be contributors, Core Team, etc), and so on.

The Value of Teamwork

Note that this triage process is usually made much easier, more efficient, and more fun when co-Maintainers of a lesson can meet synchronously to work through issues and pull requests together.

Community members have reported positive experience with short, regularly scheduled e.g. monthly coworking sessions with their Maintainer team, using screen-sharing and focussed discussion to distribute tasks and collaboratively determine how to process and respond to contributions on their repositories.

It can also be a good opportunity for Maintainers to get know each other better, and to share their skills and experience with Git, GitHub, and the lesson infrastructure.

Labelling Issues

The triage process can be improved with effective use of labels applied to issues. Issues are tags that can be applied to issues (and pull requests), annotating them according to their status, type, complexity, etc. When labels are applied to an issue, they appear next to it in the issue listing for the repository. Clicking on a label will show you a list of all issues with that label.

When returning to a lesson repository after some time away, labels applied to old issues can help to remind you of the context for each of those, and labels can be added/updated as you triage the issue list.

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

Inviting Community Contributions

Lesson repositories are open source and publicly-visible, and you can expect some spontaneous contributions from the wider community. However, in some circumstances, you may want to bring particular items to the attention of community members.

Refer to CAC

When you want or need to refer an issue/contribution to the Curriculum Advisory Committee for your lesson, you should add the status:refer to cac label, and tag the CAC in the relevant issue/pull request discussion thread (e.g. @datacarpentry/curriculum-advisors-image).

Adding this label will help members of the CAC more easily identify and browse through the items they need to discuss, increasing the likelihood that you will receive a timely response.

Help Wanted & Good First Issue

The help wanted and good first issue labels can be useful to draw attention from new contributors. In particular, the help wanted label can be used to flag up issues that the Maintainers would particularly appreciate external support on. Issues with this label in any of The Carpentries official lesson repositories will appear in the listing on the Help Wanted Issues page of the website, where new community members are often directed to find opportunities to contribute to a lesson repository.

The good first issue label is used to identify issues that do not require in-depth knowledge of the project and its infrastructure, etc. Newcomers to the project can use this label to find opportunities to make their first contribution. GitHub provides a view of all of a repository’s issues with the good first issue label on the /contribute page for that repository, e.g. https://github.com/github/docs/contribute

Batch Labelling

Labels can be applied to issues in batches from the issue listing page. Check the box next to each issue you want to apply a given label to, then click the “Label” dropdown in the top bar of the listing, and choose the label(s) you want to apply to these issues.

Key Points

Labelling issues can help you prioritise issues and bring them to the community’s attention.
Labels can be added to an issue using the right sidebar menu of the GitHub web interface.
The Carpentries provides a recommend set of labels, and has systems and processes that work with some of these.

Content from Referencing pull-requests and issues

Last updated on 2023-10-11 | Edit this page

Estimated time: 10 minutes

Overview

Questions

How do I reference issues and pull requests?
How can issues be automatically closed when a pull request is merged?

Objectives

After following this section, participants will be ready to practice the following skills:

reference issues and pull requests by their number
implement keywords to trigger automatic closue of issues when fixed by a pull request

It can be helpful to refer to issues and pull requests in conversations elsewhere in a repository
Every issue and PR has a unique number (based on the order in which they were created)
These numbers can be used, preceded by #, to reference a given issue or PR.
Additionally, PRs (and commit messages) that include particular phrases will trigger the automatic closure of an issue:
- “closes”
- “fixes”
- “resolves”

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.

Key Points

Issues and pull requests can be referred to by their number within a repository.
Pull requests descriptions that include “fixes #XYZ”, “resolves #XYZ”, or “closes #XYZ” will all close issue number XYZ when they are merged.

Content from Reviewing pull-requests

Last updated on 2023-10-11 | Edit this page

Estimated time: 30 minutes

Overview

Questions

What features does GitHub provide to facilitate reviewing pull requests?
What are the different options for the outcome of a pull request review, and when should I use each one?

Objectives

After following this section, participants will be ready to practice the following skills:

create comments on particular lines and ranges of lines in the changes proposed by a pull request
suggest specific changes to a pull request
select the “approve”, “comment”, or “request changes” outcomes of a pull request review

reviewing PRs is one of the most important tasks for a Maintainer
the way you review a pull request, and communicate with the person who opened it, can have an enormous impact on their motivation to contribute again
GitHub provides several features that can improve your experience as a reviewer, and make it easier for contributors to follow up on your review

Line-by-Line Comments

see the changes proposed in a PR via the Files Changed tab
if you want to comment on a particular line, hover your mouse over it and click the + symbol
comments can be added on their own, or as part of a Review: a commentary on the pull request as a whole
to comment on a range of lines, click-and-hold on the + for the first line in the range, and drag your cursor down the range, then release

Suggesting Changes

as well as adding comments line-by-line, you can also suggest specific changes, e.g. to fix a typo, suggest improved wording, etc.
take the same approach to start a comment on a line or range of lines, then click the “add a suggestion” button, and edit the source content that appears in the input box
this makes it much easier for contributors to a) understand reviewers’ suggestions, and b) implement them

Finishing a Review

when you have finished commenting on particular lines, and suggesting changes, you can finish your review by clicking the “Review changes” or “Finish your review” button near the top-right of the screen
add general comments, a summary of your review, etc - don’t forget to thank them for taking the time to contribute! - and choose one of the three options:
- “Comment” - a general comment, with no firm outcome. Can be used to complete a review before a pull request is closed.
- “Approve” - approve the PR for merging. Some people use this when suggesting only very minor or optional changes - if you want to do this, make sure you are explicit about what changes you are suggesting etc before the PR can be merged
- “Request changes” - indicates that changes would be required to the PR before you would be willing to merge it.

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:

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

Saved Replies

You can add “saved replies” to your GitHub account
These can be used to automatically input a template response, on issues, PRs, etc
Use these if you find that you are often saying the same or similar things to people

Key Points

What features does GitHub provide to facilitate reviewing pull requests?
What are the different options for the outcome of a pull request review, and when should I use each one?

Content from Resolving conflicts

Last updated on 2023-10-11 | Edit this page

Estimated time: 15 minutes

Overview

Questions

When might I encounter merge conflicts while maintaining/developing a lesson?
How can I resolve simple conflicts in the GitHub web interface?

Objectives

After following this section, participants will be ready to practice the following skills:

resolve merge conflicts using the GitHub web interface

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

What is a merge conflict?

A merge conflict occurs when Git is not able to automatically integrate (merge) the changes in a branch with the version of the relevant file(s) into another branch (usually the default or main branch) of the project.

Conflicts are seen when the target branch (usually main) has changed since the branch for the pull request was created. Often, Git is able to combine the two sets of changes without any trouble. But sometimes it gets stuck, and requires a human to intervene and decide how multiple changes should be combined, which change should take precedence, etc.

When these conflicts arise within a file, Git marks up the file contents to highlight them. The conflicts looks something like this:

<<<<<<< pr-branch
this is one version of the line. it exists in the version of this file in the pr-branch branch.
=======
this is another version of the same line. it exists in the version of this file in the main branch.
>>>>>>> main

Resolving a Merge Conflict

Before the PR can be merged, someone (usually the contributor who opened the pull request, or one of the repository Maintainers) needs to resolve each of these conflicts by:

Figuring out which version (or combination of versions) of the lines should be kept in the file.
Removing all other lines (including the <, =, and > symbols) to leave only that resolved version.

After that has been done, and no conflicts remain to be resolved, the branch can be updated, bringing it back in line with the changes in the target branch.

GitHub provides an interface to help you do this, with buttons for quick navigation between multiple conflicts, highlighting of the conflicting parts of the file, etc.

Larger Conflicts

Sometimes the conflicts between branches will be too large or too complex to be resolved within the GitHub web interface. In these cases, the conflicts will need to be resolved on the command line.

GitHub provides a guide to resolving conflicts on the command line, and other tools exist to help with merging and resolving conflicts.

Still Have Time Left?

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

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

Key Points

You may encounter merge conflicts in large pull requests and those that have been open for some time.
GitHub provides an interface to resolve simple conflicts in the GitHub web interface.