Content from Managing issues

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

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.

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

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”

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

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.

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

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

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:

  1. Figuring out which version (or combination of versions) of the lines should be kept in the file.
  2. 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.

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.