From 49646a0977c3ca68a2c73f9b653eee93c1f65d8b Mon Sep 17 00:00:00 2001 From: Miranda Mundt Date: Mon, 22 Jun 2026 15:36:11 -0600 Subject: [PATCH 1/3] Yearly overhaul - fix boringness, add in genAI references --- episodes/basic-issues.md | 83 ++++++++++++++++++++++----------- episodes/introduction.md | 71 +++++++++++++++++++--------- episodes/labels.md | 71 +++++++++++++++++----------- episodes/templates.md | 44 +++++++++++++---- instructors/instructor-notes.md | 51 +++++++++++++++++++- learners/reference.md | 12 +++++ 6 files changed, 244 insertions(+), 88 deletions(-) diff --git a/episodes/basic-issues.md b/episodes/basic-issues.md index 00c3469..e32cf06 100644 --- a/episodes/basic-issues.md +++ b/episodes/basic-issues.md @@ -5,54 +5,80 @@ exercises: 10 --- ::::::::::::::::::::::::::::::::::::::: objectives -- Become familiar with basic actions on GitHub Issues +- Recognize what makes an issue clear and actionable. +- Become familiar with basic actions on GitHub Issues. :::::::::::::::::::::::::::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::: questions +- What makes a *good* issue? - How do you make an issue? - How do you interact with an open issue? - How do you close an issue? :::::::::::::::::::::::::::::::::::::::::::::::::: -## Open an Issue +## What Makes a *Good* Issue? -To open a new issue, navigate to the issue page. Here you will see a green -"New issue" button in the top-right. Click this to start the creation of a new issue. +Anyone can click "New issue" and type "it's broken." The skill worth learning is writing an +issue a teammate can actually *act on* without a follow-up conversation. A good bug report +usually has: -![](fig/new-issue.png){alt='New issue button circled in red. Button is on the top-right on the Issues page.'} +| Ingredient | Why it matters | +|------------|----------------| +| **Clear, specific title** | "Crash when sorting empty folder" beats "bug" — it's findable and scannable. | +| **Steps to reproduce** | If we can't trigger it, we can't fix it. Number the steps. | +| **Expected vs. actual** | What *should* have happened, and what *did*. | +| **Environment** | OS, version, language version — the details that change behavior. | +| **One issue = one problem** | Don't bundle five bugs in one ticket; they can't be tracked or closed independently. | -This will load a new page with an empty issue. +A good *feature request* is similar: what you want, **why** (the motivation/use case), and any +alternatives you considered. Keep these in mind for every issue you open today. -![](fig/empty-issue.png){alt='Empty issue page after clicking new issue button. All details (Title, Write, Assignees, etc.) are empty.'} +## Open an Issue -A new issue has several parts: +Click the green **New issue** button (top-right of the Issues page) to start a new issue. -- _Title_: This will display on the main "Issue" page. -- _Write_: This is an open area for the details of the issue. GitHub support Markdown formatting. -- _Preview_: This will preview the Markdown-rendered version of the details. +![](fig/new-issue.png){alt='New issue button circled in red. Button is on the top-right on the Issues page.'} -Once an issue is filled out, the "Submit new issue" button will highlight. +A new issue has a few parts: + +- _Title_: displays on the main Issues page. +- _Write_: the details of the issue — GitHub supports **Markdown** formatting. +- _Preview_: shows the Markdown-rendered version before you submit. + +Once it's filled out, the **Submit new issue** button activates. ![](fig/submit-new-issue.png){alt='Submit new issue button is now highlighted and available to press'} ::::::::::::::::::::::::::::::::::::::: challenge -## Open a New Issue +## File Your First StarSort Bug -Navigate to your practice repository's issue page. - -* Open a new issue titled "[YOUR NAME]'s First Issue" -* In the "Write" section, make a heading entitled "Description" -* Write a short sentence telling us what you ate for breakfast this morning -* Add a code block with "Hello, World" coded in your favorite language -* Preview your issue to make sure it looks right -* Submit the issue! +You're testing StarSort and it crashes when you point it at an empty image folder. Time to file +a proper bug report! In **your practice repository's** issue page: + +* Open a new issue with a clear, specific **title** +* In the "Write" section, add a `## Steps to Reproduce` heading and number the steps. +* Add a section for **Expected vs. Actual** behavior. +* Include a code block showing the (made-up) error message StarSort printed. +* **Preview** to check your Markdown, then **submit**! :::::::::::::::::::::::::::::::::::::::::::::::::: +:::::::::::::::::::::::::::::::::::::::::: callout + +## GenAI: from messy notes to a clean report + +Bug reports often start as a jumble: "it broke when the folder was empty, error said +IndexError, was on my mac." Try pasting notes like that into an LLM and asking it to format a +bug report with steps to reproduce and expected/actual sections. Then **check it against the +good issue table** — did it invent steps or details you didn't give it? You supply the facts; the AI +just tidies the structure. + +:::::::::::::::::::::::::::::::::::::::::::::::::::::: + On the right-hand side, there are more options that can be modified. - _Assignee_: Here you can choose a specific person to this issue. @@ -99,20 +125,21 @@ tag other users, link to other issues or pull requests, and more. ::::::::::::::::::::::::::::::::::::::: challenge -## Tag Your Instructor +## Loop in a Maintainer + +A StarSort maintainer should know about your bug. Navigate to your issue from the previous +exercise. -Navigate to your issue from the previous exercise. - * Write a new comment on the issue, mentioning your instructor using the `@` symbol. -* Add the comment to the issue +* Add the comment to the issue. :::::::::::::::::::::::::::::::::::::::::::::::::: ## Close an Issue -We are done with this issue. We have completed the work on it, had our -discussion, and now we don't want it cluttering up our issue list. +Good news — a maintainer "fixed" your StarSort bug! The work is done and the discussion is +over, so we don't want it cluttering up the open-issues list anymore. Closing an issue is simple - just click the "Close issue" button. @@ -141,9 +168,11 @@ You now know the basic actions you can take on a GitHub issue! :::::::::::::::::::::::::::::::::::::::: keypoints +- A good issue has a clear title, steps to reproduce, expected vs. actual behavior, and covers one problem. - New issues can be opened in a repository using the 'New issue' button. - Text on issues use Markdown styling for formatting. - A user can interact with issues in multiple ways: commenting, mentioning others, linking to other issues and pull requests, and more. +- GenAI can format messy notes into a structured report, but you must supply and verify the facts. :::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/episodes/introduction.md b/episodes/introduction.md index e305df2..5dc7373 100644 --- a/episodes/introduction.md +++ b/episodes/introduction.md @@ -34,13 +34,41 @@ Issue trackers can be internal (team-facing) or external (user-facing). In this lesson, students will learn about issue tracking through the use of GitHub Issues. +:::::::::::::::::::::::::::::::::::::::::: callout + +## Your mission: welcome to the StarSort team! + +To make this concrete, you'll spend this lesson role-playing a new contributor to +**StarSort** — a (fictional) open-source research tool that sorts and catalogs telescope +images. The maintainers are friendly but swamped, and the issue tracker is how the whole team +tracks work. Throughout the lesson you'll file bug reports, triage the backlog, and set up +templates — just like a real contributor would. + +(You'll do all of this in **your own practice repository** — StarSort is just the story we'll +use to make it fun.) + +:::::::::::::::::::::::::::::::::::::::::::::::::::::: + ## The Benefits of Issue Tracking -Issue tracking has numerous benefits. Some of the main ones are: +Why bother, instead of a pile of sticky notes and "I'll remember it" promises? + +| Benefit | What it gives you | +|---------|-------------------| +| **Visibility** | All the work to be done lives in one place every team member can see. | +| **Collaboration** | Work can be captured, organized, discussed, and assigned in a single location. | +| **Transparency** | If the tracker is user-facing, users can follow progress and chime in. | + +:::::::::::::::::::::::::::::::::::::::::: callout + +## Where does genAI fit? + +Generative AI (LLMs like ChatGPT and Claude) is surprisingly handy for issue tracking — it can +turn messy notes into a clear bug report, suggest labels, or summarize a long discussion +thread. We'll point out useful spots throughout the lesson. The catch, as always: the AI +drafts, but **you** review for accuracy. -- _Visibility_: Work to be done is captured in one location where all team members can access it -- _Collaboration_: Issue trackers enable good project collaboration. Work can be captured, organized, managed, and discussed in a single location -- _Transparency_: If the issue tracking system is user-facing, users can see the status of work completed and add more information +:::::::::::::::::::::::::::::::::::::::::::::::::::::: ## GitHub Issues @@ -48,38 +76,35 @@ Issue tracking has numerous benefits. Some of the main ones are: Numerous different issue tracking systems exist - both commercial and open-source, integrated and stand-alone. -GitHub integrates issue tracking into their version control system. Every project -on GitHub can enable an integrated issue tracker. +GitHub integrates issue tracking right into version control: every project on GitHub can +enable an issue tracker, reached from the **Issues** tab in the repository's navigation bar. ![](fig/intersect-nav.png){alt='INTERSECT training repository navigation bar, showing, from left to right: Code, Issues, Pull Requests, Actions, Projects, Security, Insights'} -To access a repository's issues, navigate to the repository root -page and click on "Issues" in the navigation bar. This will take you to the -page of all "Open" issues. +The Issues page lists all open issues; click any one to read its details and discussion. You +can filter the list by status (Open/Closed), author, label, and more. ![](fig/intersect-issues.png){alt='INTERSECT training repository Issues pages'} -Click on an issue to open it and read its details, plus any discussion -on that issue. - -![](fig/intersect-issue-13.png){alt='INTERSECT training repository issue 13, titled "add merely useful + turing way to list resources?"'} - -You can also change the default filter on the Issues page by status ("Open" or -"Closed"), author, and more. - -![](fig/intersect-filter.png){alt='Issue top-bar filter options which include Open, Closed, Author, Label, Projects, Milestones, Assignee, and Sort'} - - ::::::::::::::::::::::::::::::::::::::: challenge -## Browsing Open Issues +## Scavenger Hunt: Browsing Open Issues + +A real project's tracker can be huge. Let's explore one. Navigate to +[https://github.com/spack/spack](https://github.com/spack/spack) and find the issues page. -Navigate to [https://github.com/spack/spack](https://github.com/spack/spack) and find the issues page. - * How many issues are currently open? * How many have been closed? * How many labels are there? +:::::::::::::::::::::: solution + +Open vs. closed counts are the toggles at the top of the issues list; the label count is on the +**Labels** button (or the `/labels` page). The exact numbers change daily — that's the point: +the tracker is dynamic and constantly updated. + +:::::::::::::::::::::: + :::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/episodes/labels.md b/episodes/labels.md index 241d928..e3163dd 100644 --- a/episodes/labels.md +++ b/episodes/labels.md @@ -1,17 +1,19 @@ --- title: "Labelling Issues" -teaching: 5 +teaching: 6 +exercises: 8 --- ::::::::::::::::::::::::::::::::::::::: objectives -- Learn how to use labels for GitHub issues. +- Learn how to make, modify, apply, and filter by labels for GitHub issues. :::::::::::::::::::::::::::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::: questions - How do you make and assign labels to issues? +- How do labels help you triage and prioritize work? :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -46,27 +48,21 @@ Engineering, however, so we will need to modify these. ## Modifying Labels -Labels can be added, edited, or deleted from the labels page. - -![](fig/label-highlights.png){alt='On the Labels page, individual label actions (Edit, Delete) circled'} - -Each label has three attributes: - -* Label name -* Description -* Color (Hex code) +Labels can be added, edited, or deleted from the **Labels** page. Each label has three +attributes: a **name**, a **description**, and a **color** (hex code). ![](fig/label-attributes.png){alt='Label attributes - label name, description, color - and the buttons "Cancel" and "Save changes"'} ::::::::::::::::::::::::::::::::::::::: challenge -## Label Maker +## Tidy Up StarSort's Labels + +The StarSort maintainers want the label set to fit their small research team. In **your +practice repository's** Labels page: -Navigate to your practice repository's label page. - * Add a new label for `discussion` * Remove the label for `good first issue` -* Modify the color on the `wontfix` label to your favorite color +* Change the color of the `wontfix` label to your favorite color :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -94,15 +90,27 @@ your preferred label(s). ::::::::::::::::::::::::::::::::::::::: challenge -## Stick the Label +## Triage Time -Navigate to your practice repository's issue page. - -* Create a new issue entitled "[YOUR NAME]'s label issue" -* Add the `discussion` label +A new idea came in for StarSort: supporting a new image format. In **your practice +repository's** issue page: + +* Create a new issue entitled "[YOUR NAME]: support FITS image format" +* Add the `discussion` label so the team knows it needs further discussion :::::::::::::::::::::::::::::::::::::::::::::::::: +:::::::::::::::::::::::::::::::::::::::::: callout + +## GenAI: Triage assistant + +Faced with a backlog of 50 unlabeled issues? An LLM can read an issue's text and *suggest* a +label (bug, enhancement, question...) or even a priority. It's a great way to get a first pass — +but a human should confirm before the labels drive real decisions, since a mislabeled issue +hides in the wrong filter. + +:::::::::::::::::::::::::::::::::::::::::::::::::::::: + ## Filter by Labels Another feature of labels within GitHub is the ability to filter issues by @@ -123,14 +131,21 @@ You can select multiple labels or use the hints at the bottom of the ::::::::::::::::::::::::::::::::::::::: challenge -## Practice Filtering +## Filter Like a Pro + +Let's go back to some real research software. Navigate to +[https://github.com/spack/spack](https://github.com/spack/spack) and find the issues page. + +* Filter by the `environments` label? +* Filter by both the `environments` and `bug` labels? +* (CHALLENGE) Filter by `question` but *exclude* `bug`? + +:::::::::::::::::::::: solution + +The last one uses the exclusion syntax in the search bar: `is:issue is:open label:question +-label:bug`. The `-label:` prefix is the trick most people don't know. -Navigate to [https://github.com/spack/spack](https://github.com/spack/spack) and -find the issues page. - -* Filter by the `architecture` label -* Filter by both the `architecture` and `architectures` labels -* (CHALLENGE) Filter by `question` but exclude `bug` +:::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -140,6 +155,8 @@ GitHub Issues. :::::::::::::::::::::::::::::::::::::::: keypoints - Labelling issues can help with organization and filtering. +- Curate the default label set to fit your project and team size. +- Filtering (including exclusion, e.g. `-label:bug`) makes a big backlog manageable. :::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/episodes/templates.md b/episodes/templates.md index bc3cdee..4609cb0 100644 --- a/episodes/templates.md +++ b/episodes/templates.md @@ -1,7 +1,7 @@ --- title: "Issue Templates" -teaching: 10 -exercises: 10 +teaching: 8 +exercises: 8 --- ::::::::::::::::::::::::::::::::::::::: objectives @@ -27,6 +27,11 @@ sections, data, instructions, etc. They are customizable for every project. You can add as many templates as makes sense for your project, or you can have none at all. +Remember the good-issue table from earlier? A template is how you incorporate those items right +into the "New issue" experience, so *every* contributor's bug report comes with steps-to- +reproduce and expected-vs-actual sections already laid out. It's the StarSort maintainers' +favorite trick for getting reports they can actually act on. + In this episode, we will learn the basics of issue templates. ## Default Issue Templates @@ -81,9 +86,10 @@ whatever you'd like. ## Custom Issue Templates -We now have templates for both bug reports and feature requests. For this -project, however, we also want to create a template for Design Discussions. -Let's make this custom template. +We now have templates for both bug reports and feature requests. The StarSort maintainers have +a request, though: they want a template for **Design Discussions**, so proposals like your +"support FITS format" idea from earlier come in with a consistent shape. Let's build that +custom template. When we created our first template, GitHub did the setup for us. If you navigate back to your main page, you will see a new @@ -147,6 +153,17 @@ Then commit the changes directly to your main branch. :::::::::::::::::::::::::::::::::::::::::::::::::: +:::::::::::::::::::::::::::::::::::::::::: callout + +## GenAI: Draft a template in seconds + +Templates are structured, repetitive text — exactly what LLMs do well. Try asking one: +*"Write a GitHub issue template (with YAML front matter) for reporting a performance problem in +a scientific Python tool."* Then **review and trim** it to fit your project — AI +tends to over-produce sections you don't need, and "less is more" still applies. + +:::::::::::::::::::::::::::::::::::::::::::::::::::::: + We now have three issue templates available for use. ![](fig/three-issue-template-list.png){alt='New issue page with three templates available - Bug report, Design discussion, and Feature request'} @@ -179,27 +196,34 @@ that will show up in the template chooser. ::::::::::::::::::::::::::::::::::::::: challenge -## Ask Google +## Ask a Friend -Create a `config.yml` for your repository. In the `config.yml`: +Not every question belongs in the issue tracker — usage questions are often better in a +discussion forum or chat. StarSort has a community discussions page, so let's send people there +instead of letting "how do I...?" issues pile up. Create a `config.yml` for your repository. In +it: * Enable blank issues -* Create a link with the name, "Ask Google," a link to www.google.com, and the description, "Google may know your answer." +* Add a contact link named "StarSort Community Q&A" pointing to a discussions/forum URL of your + choice (e.g., your repo's GitHub Discussions page), with a description like "Ask usage + questions here." Then commit the changes directly to your main branch. :::::::::::::::::::::::::::::::::::::::::::::::::: -Our template chooser now has our three templates and a link to Google. +Our template chooser now shows our three templates plus the external community link. -![](fig/ask-google-template.png){alt='New issue page with three templates available - Bug report, Design discussion, and Feature request - plus an additional button with custom external link to "Ask Google"'} +![](fig/ask-google-template.png){alt='New issue page with three templates available - Bug report, Design discussion, and Feature request - plus an additional button with a custom external contact link'} And that's all, folks! You now know much more about GitHub Issues. :::::::::::::::::::::::::::::::::::::::: keypoints - Templates can be incorporated into any GitHub repository and can make issue creation more structured. +- A good template incorporates the "good issue" table into every new report. - External links can be listed with the templates to help direct users to external resources. +- GenAI can draft a template quickly — review and trim it to fit your project. :::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/instructors/instructor-notes.md b/instructors/instructor-notes.md index d9a67aa..bf92524 100644 --- a/instructors/instructor-notes.md +++ b/instructors/instructor-notes.md @@ -2,4 +2,53 @@ title: 'Instructor Notes' --- -This is a placeholder file. Please add content here. +## Timing and Schedule + +This lesson is designed for a **single 60-minute slot**, taught after the collaborative-git +section (so learners already know branches, commits, and `@`-mentions). + +| Time | Episode | Notes | +|------|---------|-------| +| ~8 min | **Introduction** | Benefits table, the **StarSort** scenario setup, and the first scavenger hunt on spack. | +| ~22 min | **Basic Issue Tracking** | The new **"What makes a good issue?"** content + the roleplay bug report. The heart of the lesson — protect this. | +| ~14 min | **Labelling Issues** | Triage roleplay + the filtering scavenger hunt. | +| ~16 min | **Issue Templates** | Custom template + external contact link, reskinned into the scenario. | + +Total ~60 min. + +## The StarSort scenario + +To make it more fun and interactive, the lesson is wrapped in scenario: +learners are new contributors to **StarSort**, a fictional open-source tool that +sorts/catalogs telescope images. All the hands-on work still happens in each learner's **own +practice repository** — StarSort is just the framing that makes it feel like real teamwork. + +The story threads through the episodes: + +- **Basic Issues** — file a good bug report for a StarSort crash; loop in a "maintainer" (you). +- **Labels** — tidy StarSort's label set; triage a new feature idea. +- **Templates** — the maintainers request a Design Discussion template and a community link. + +Lean into it: play the "maintainer" when learners `@`-mention you, react to their bug reports, +etc. The more you ham it up, the better it lands. + +## Gamification (keep it light) + +Two optional bits of friendly competition. They're fun but skippable — don't let them eat the +core exercises: + +- **Scavenger hunts** (Intro + Labels): first to call out the correct spack numbers / fastest + to build the filter wins. Great energy resets. +- **Best Bug Report** (Basic Issues): spotlight 2–3 of the clearest reports and ask the room + *why* they're easy to act on — reinforces the checklist. + +## GenAI thread + +GenAI is woven through rather than tacked on: + +- **Introduction** — seeds "AI drafts, you review." +- **Basic Issues** — turn messy notes into a structured bug report (then verify). +- **Labels** — LLM as a triage/label-suggestion assistant. +- **Templates** — generate a template from a prose description, then trim. + +Reinforce the through-line: **AI drafts; you own the review.** diff --git a/learners/reference.md b/learners/reference.md index 6ed803e..8de7ab2 100644 --- a/learners/reference.md +++ b/learners/reference.md @@ -5,3 +5,15 @@ - Gorohovsky, J. (2023). Best Practices for Using GitHub Issues. Rewind Backups. https://rewind.com/blog/best-practices-for-using-github-issues/ - Johnson, J. N., & Dubois, P. F. (2003). Issue tracking. Computing in Science & Engineering, 5(6), 71-77. +## Writing Good Issues and Templates + +- [How to write a good bug report (MDN)](https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelines) +- [Configuring issue templates for your repository (GitHub Docs)](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) +- [Filtering and searching issues (GitHub Docs)](https://docs.github.com/en/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests) + +## GenAI for Issue Tracking + +- General-purpose assistants (e.g., ChatGPT, Claude) can turn messy notes into a structured bug + report, suggest labels for triage, draft issue templates, and summarize long discussion + threads. Always supply the real facts and review the output for accuracy. + From a48ac912e203308f6e1f6ffb10988593fdf5d85a Mon Sep 17 00:00:00 2001 From: Miranda Mundt Date: Mon, 22 Jun 2026 15:37:47 -0600 Subject: [PATCH 2/3] Change phrasing --- instructors/instructor-notes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/instructors/instructor-notes.md b/instructors/instructor-notes.md index bf92524..cdb4d28 100644 --- a/instructors/instructor-notes.md +++ b/instructors/instructor-notes.md @@ -38,9 +38,9 @@ Two optional bits of friendly competition. They're fun but skippable — don't l core exercises: - **Scavenger hunts** (Intro + Labels): first to call out the correct spack numbers / fastest - to build the filter wins. Great energy resets. + to build the filter wins (brownie points) - **Best Bug Report** (Basic Issues): spotlight 2–3 of the clearest reports and ask the room - *why* they're easy to act on — reinforces the checklist. + *why* they're easy to act on ## GenAI thread From 0ea14a74eab5d94c63b40a44f86a4f82e7c544f5 Mon Sep 17 00:00:00 2001 From: Miranda Mundt Date: Mon, 22 Jun 2026 15:38:38 -0600 Subject: [PATCH 3/3] Outdated URL checking --- .github/workflows/check-pr-urls.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/check-pr-urls.yml b/.github/workflows/check-pr-urls.yml index c701db8..1bf11eb 100644 --- a/.github/workflows/check-pr-urls.yml +++ b/.github/workflows/check-pr-urls.yml @@ -8,11 +8,11 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v7 - id: files # uses: jitterbit/get-changed-files@v1 ### Hasn't been updated to Node16 - uses: masesgroup/retrieve-changed-files@v2 + uses: masesgroup/retrieve-changed-files@v4 with: format: 'csv'