Watch me groom GitHub Issues for KFG
Channel: Knowledge for Good
Date: 2021-07-29

Disclaimer: I am not an authority on GitHub issue grooming, and this is simply one way (a way that I find works well for me) of many.

Come on a journey with me. No edits, no do-overs, and ALL the mistakes 😂

Have you ever made an issue on GitHub? Have you ever commented on someone else's issue on GitHub? I'd love to hear about your experiences with  GitHub Issues 😉

# WIP Timestamps & Video Notes

0:00 Hi & context (skip this)
0:39 Screen recording start
0:47 Repo page overview
  - files
  - readme
  - issues tab
1:03 Issues address (skip this)
1:28 Issues Intro
1:50 Goal/purpose of issues
2:16 Missing labels observed
2:24 Missing milestones observed
2:32 What are milestones?
2:50 Let's focus on "Org Setup"
2:56 How to focus on a milestone
3:03 How to read an "issue filter"
3:37 I say I'm going to focus on these six issues
4:00 Note, labels may be missing some context, or seem unclear
4:16 "New questions can be asked as new issues"
  - Questions about labels, milestones can be asked as new issues. Questions about issues I believe are better asked directly on the issues themselves.
4:21 I say I want to make sure that all "tasks" have "time" assigned to them, but I do not do this, I apologize. The context here is still useful for doing what I suggest I am to do.
4:59 I start looking at the first issue of six for the "org-setup" milestone
  - An epic issues is an issue made up of smaller issues.
5:15 I talk about the context & history of issue 87
  - Issues marked in green are unresolved
  - Questions can be discussions
  - I believe that issues are better than discussions for accountability, b/c they hold "(un)resolved" status
  - Linnea converted discussions to issues, "closed" the issue
  - Avi wanted greater visibility on questions, "reopened" issue
  - 6:49 Avi added more questions below as "comments"
  - 7:30 Avi has no nonprofit experience, Linnea has experience & context
  - 7:40 Avi sees comment questions as "orphaned questions" (to increase visibility, accessibility, clarity Avi will convert them to issues)
8:13 Avi converts comments (raw text) into GitHub issues
  - 8:47 Demo how to make new issues
  - 9:05 Avi comments for context because he is editing/moving text/info around
  - 10:00 Avi shows how to do "bi-directional linking" by referencing a pre-existing issue, and siting the importance of "capturing the context"
  - 10:56 Looking back at issues tab, and the newly created issue, to see the created link inside
  - Avi creates the other two question issues
  - 12:31 recap that 3 new issues have been created, but they have no labels on them yet
  - 12:42 Avi shows how to add labels to one or more issues at once
     - 13:05 Avi thinks out loud, what is the label "attention-requested"
  - 13:17 Question issues can be "progressed" or "helped" in a number of ways, "how to brainstorm list":
    - suggesting answers
    - suggesting knowledgeable people to answer
    - suggesting related issues
    - add context you believe is missing
    - asking clarifying questions if anything is vague/ambiguous
    - proposing a brainstorming session to generate answers
       - 13:25 Avi demos proposing by commenting, suggesting an "AutoFocus" session, adds a few labels which seem helpful
       - 15:18 Avi re-assesses the issue with its current labels, is inspired to add a new label: "has-proposal" 
       - 16:15 Avi notes that, with a question on this issue, the issue probably needs attention from someone else, he demos how to "at" (@) Linnea
       - 17:00 What is an AutoFocus session? It's a "awareness of priority"-increasing activity
17:30 Back to viewing the six issues in the "org setup" milestone
17:50 What is my guiding question today?
  - "What is one tiny thing I can add to move this issue towards resolution?"
19:40 "epics are convenient high-level, birds-eye view of issues"
20:05 How to change an issue's name
  - (changes issue #87's name to clarify it's new role/purpose (it's not a task anymore, it's just a collection))
21:02 Avi asks himself, "does epic issue #87 warrant more attention?"
  - Avi is inspired to schedule a working session to prioritize critical/key questions. Talks out whether to just do, or to ask first, why or why not.
  - 22:43 Avi recaps progress made on issue #87, and leaves a comment on the issue for context to others
24:20 Look at issue #60 "register as a coop"
  - Notes that epics can live within epics
  - Notes that the checklist in this issue needed to be converted to issues
  - 25:12 Notes button that GitHub displays to the right of checklists for you, the "convert to issue" button 
  - 25:25 First Avi says he wants the checklist items to be "clear" (but what he meant to say was "clear, concrete, and supported w/ sufficient context")
  - 25:48 How to edit an issue's description text
     - Avi attempts to clarify & add context & create clearly worded tasks out of each checklist item
29:03 Avi makes a mistake and cuts too much text, fixes it immediately afterward