How to Label Issues

"status" labels

  • help wanted
    • Hex code: #DCECC7
    • Short Description: Looking for Contributors
    • Long Description: Issue reviewed by Maintainers, and ready to be addressed. Maintainers are looking for Contributors to address this issue, anyone is welcome to work on addressing the issue. Issues with this label will be listed on the Help Wanted page of The Carpentries website.
  • status:in progress
    • Hex code: #9BCC65
    • Short Description: Contributor working on issue
    • Long Description: A Contributor is actively working on addressing the issue, this label should be used once someone has been assigned the issue. Because, we can only assign people using GitHub's interface when they are part of the organization, the assignment is done by tagging them in a comment of the issue. The Maintainer should set an initial deadline for a PR to be submitted. We suggest 7 days, but it can be adapted to the discretion of the Maintainer depending on the complexity of the task.
  • status:waiting for response
    • Hex code: #679F38
    • Short Description: Waiting for Contributor to respond to maintainers' comments or update PR
    • Long Description: Maintainers responded to the Contributor's inquiry and are either waiting on the Contributor to reply back or implement proposed changes.
  • status:wait
    • Hex code: #FFF2DF
    • Short Description: Progress dependent on another issue or conversation
    • Long Description: Progress on addressing issue or merging PR is dependent on another issue or ongoing conversation and cannot be addressed at this time. Ideally this other conversation should be referenced in the comments.
  • status:refer to cac
    • Hex code: #FFDFB2
    • Short Description: Curriculum Advisory Committee input needed
    • Long Description: Maintainers need advice from the Curriculum Advisory Committee to make a decision on how to proceed with the issue or pull request.
  • status:need more info
    • Hex code: #EE6C00
    • Short Description: More information needed
    • Long Description: Not enough information is provided to proceed with the issue or pull request.
  • status:blocked
    • Hex code: #E55100
    • Short Description: Progress on addressing issue blocked
    • Long Description: A technical problem is hindering progress. A Maintainer or someone else in the community should be notified to ensure that progress is being made.
  • status:out of scope
    • Hex code: #EEEEEE
    • Short Description: Proposed changes are out of scope
    • Long Description: Changes proposed in the issue or in the pull request does not fall within the scope of the lesson
  • status:duplicate
    • Hex code: #BDBDBD
    • Short Description: Issue or PR already exists
    • Long Description: The concern raised in the issue or pull request has already been mentioned. This previous issues/PR should be mentioned in the comment before this label is used.

"type" labels

  • type:typo text
    • Hex code: #F8BAD0
    • Short Description: Typo in text for the lesson,
    • Long Description: Typo in the text/code of the lesson
  • type:bug
    • Hex code: #EB3F79
    • Short Description: Code included in the lesson needs to be fixed
    • Long Description: Issue about the code, including challenges, answers.
  • type:formatting
    • Hex code: #AC1357
    • Short Description: Formatting needs to be fixed
    • Long Description: Issue about something being wrong in the formatting of the lesson
  • type:template and tools
    • Hex code: #7985CB
    • Short Description: Issue about template and tools
    • Long Description: Issue or feature request about a technical aspect of the lesson (e.g., in the scripts used to render the lesson), including the documentation of these tools. Pull requests should probably be directed to https://github.com/carpentries/styles
  • type:instructor guide
    • Hex code: #00887A
    • Short Description: Issue with the instructor guide
    • Long Description: Issue related to the content of the instructor guide. Best suited to be addressed by someone familiar with the content of the lesson
  • type:discussion
    • Hex code: #B2E5FC
    • Short Description: Discussion or feedback about the lesson
    • Long Description: Issue used to ask a question about how the lesson is taught, ask for clarification. Such issues might indicate that the instructor guide or the documentation may need to be updated.
  • type:enhancement
    • Hex code: #7FDEEA
    • Short Description: Propose enhancement to the lesson
    • Long Description: Proposal to add new content to the lesson (e.g., introducing additional function, library, command, flag), or adding more technical detail on a topic already covered in the lesson. Such issues may need to be considered by the infrastructure sub-committee, the curriculum advisory committee, or other relevant group.
  • type:clarification
    • Hex code: #00ACC0
    • Short Description: Suggest change for make lesson clearer
    • Long Description: Part of a lesson which, while not incorrect (i.e., not a bug) is presented in a way that is potentially confusing or misleading. Existing content could benefit from rephrasing or rearranging.
  • type:teaching example
    • Hex code: #CED8DC
    • Short Description: PR showing how lesson was modified in a workshop
    • Long Description: PR that illustrates how someone modified the lesson in their workshop. Not intended to be merged, but as a way to document how other instructors have used the lesson. Can be closed once the label has been applied.
  • type:accessibility
    • Hex code: #2F1D46
    • Short Description: improve content compatibility with assistive technology as well as unassisted access
    • Long Description: PR with suggested accessibility improvements or issue used to ask a question or draw attention to an accessibility issue that needs to be addressed in the lesson content or across other Carpentries resources.
  • invalid
    • Hex code: #CCCCCC
    • Short Description: PR considered as spam.
    • Long Description: Mostly around Hacktoberfest repositories receive spammy pull requests (insignificant, useless, or unnecessary changes). Tagging PRs with this label ensures that these PRs are not counted toward Hacktoberfest.

"difficulty" labels

  • good first issue
    • Hex code: #FFEB3A
    • Short Description: Good issue for first-time contributors
    • Long Description: Good issue for a new Contributor to our lesson.

"priority" labels

  • high priority
    • Hex code: #D22E2E
    • Short Description: Need to be addressed ASAP
    • Long Description: For issues and pull requests that needs to be addressed as soon as possible because the lesson uses code that doesn’t work anymore or includes information that is out of date.

How to Populate a GitHub Repository with these Labels

The chisel R package provides helper functions to create these labels from a CSV file using the GitHub API. To use the GitHub API, you need to obtain a GitHub Personal Access Token (PAT). This PAT is a way for GitHub to identify you and should be treated as a password.

  1. Once you have installed R and RStudio, at the RStudio console, install the remotes package:

install.packages("remotes")

  1. Go to https://github.com/settings/tokens, and click on the “Generate new token” button.

  2. Choose a name that will help you remember what you use this token for, and click on the repo box. Finish the creation of the token by clicking on “Generate token” at the bottom of the page. The token will be displayed on the screen.

  3. Using RStudio or text editor, open (or create if it does not exist), a ~/.Renviron file, and add (replacing the XXXX with your actual PAT):

    GITHUB_PAT=XXXXXXXXXXXXXXXXXXXXXXXXXXXX

  4. Restart RStudio and check that your PAT is available by typing:

    Sys.getenv("GITHUB_PAT")

    If everything worked, you should see your PAT being displayed. If something did not work it will display empty quotes ("").

  5. Use the remotes package to install chisel. Type at the R console in RStudio:

    remotes::install_github("fmichonneau/chisel")

  6. Make sure you have downloaded the CSV file that contains the information about the GitHub labels. It is in the repository for The Carpentries handbook in the data folder.

  7. Load the chisel package and create the labels on one repository:

    library(chisel)
create_github_labels(label_csv = "~/path/to/csv/file/github_labels.csv",
  owner = "owner_of_github_repo",
  repo = "name_of_github_repo",
  delete_previous = FALSE)

    If you set delete_previous to TRUE, all existing labels will be deleted from the repository (and removed from issues/PR that had it).