Triage Team: Goals and Processes

[AJMansfield]

How do you eat an elephant? One bite at a time.

As of writing, there are 1392 open issues and 495 open PRs on micropython/micropython --- including some that were opened all the way back in 2014, twelve years ago!

With the creation of the new @micropython/triage-team, I'd like to propose we break this backlog into a series of more achievable short term triage goals, and to as part of that, adopt and document some specific model workflow for triaging them.

I don't think it would be useful or appropriate to go full middle-manglement with an ISO9000-style process document, or to really even do something that's that close. Many of us, I'm sure, are already far too traumatized for that, by the sort of managers who see such standards as threats to their ego or as conveniently thick to roll up and bludgeon underlings with. Applied conscientiously with the correct motivations at the forefront, though, and abstracted out from more corrupt motives, the underlying ideas do offer something of value even to a community like ours.

In general, as a group of trusted senior members of our volunteer community:

• We need collective goals to bolster morale, and validate the value our efforts have to both ourselves and the community.
• We need means for locating specific tasks to suit any quantum of time/motivation/skill that can feasibly advance those goals.
• We need effective communication that establishes responsibility for parts of an issue's life-cycle to avoid wasteful redundant work.
• We need a standard of etiquette for when and how to call other volunteers to an issue to limit social-anxiety-based collective procrastination.
• We need specific guidance that empowers us to interpret the community's expectations and close issues expediently rather than anxiously.

MicroPython should only adopt official goals and recommendations for Triage Team that stand firmly atop the underlying norms we mean them to explain and encourage, and the principled reasons we'd have to encourage them. But for all of the above reasons, we should adopt a set of short-term goals and an accompanying "model workflow" that's as specific and actionable as possible within that.

I have my own specific proposal for how to break the backlog into smaller goals, and model workflow I've framed in a way I think would be appropriate, submitted below. I encourage everyone who cares to to offer their own competing ideas as top-level comments beside it, and any concerns or offered tweaks in replies to them. If you disagree with the concept itself, please make that known with your 👎s and your own top-level comment. (And, if you're motivated to satire, we all need an ego haircut occasionally: call this foolish ten ways and link whichever dilbert strip you need.)

@jonnor @dhylands @mattytrentini @agatti @Josverl @andrewleech @dpgeorge @peterhinch @robert-hh

[AJMansfield]

I propose we should use a proliferation of small GitHub Projects, to track a set of short-term goals based around suitably-sized buckets for the date that each issue in the backlog was last updated.

I've compiled a table of the counts of still-open issues at time of writing, bucketed by creation year and last-updated year:

Year	Created	Updated
2014	6	0
2015	20	5
2016	27	5
2017	41	8
2018	59	23
2019	118	74
2020	180	81
2021	206	112
2022	239	158
2023	232	178
2024	250	424
2025	382	603
2026	91	180

'Last Updated' feels like the more important signal here, with issues updated recently being much more likely to still merit technical review than issues that are years stale (i.e. different sorts of effort required). Note that several of these years would need to be broken down further --- I'd offer 1-month buckets for 2026, 2025, and 2024; and quarterly buckets for 2023 and 2022.

Point is, to use these features to:

1. Have large visual progress indication that meaningfully moves with even a single closed issue. (Don't underestimate line-go-up as a tool to motivate people responsibly, too!)
2. Create frequent excuses to recognize and celebrate our own and our peers' intermediate successes in fully emptying each next bucket.
3. Allow for multiple distinct life-cycle phases for an issue, and credit the work to send an issue to a later triage stage as a chunk of progress equal to closing the issue.
4. Provide multiple pre-filtered issue lists that are at least roughly segregated on the sort of time-and-effort quantum likely required to make permanent progress.

And as far as a model workflow framed to be as actionable as possible:

Initial Setup

• Determine support for this idea, and if it's found create and assign issues for relevant steps.
  • Self-assigning @AJMansfield to this.
• Ask for other volunteers willing to be assigned these tasks.
  • You're reading this, right? Comment below if you can commit to taking on one of these setup tasks.
• Create a GitHub Projects template with separate "Basic Triage" and "Technical Triage" statuses in addition to "Resolvable" and "Resolved".
  • https://github.com/orgs/micropython/projects/3
• Create a GitHub Project from this template for each selected bucket.
  • I've created https://github.com/orgs/micropython/projects/2 to test from the issue filter is:open repo:micropython/micropython no:milestone updated:>=2026-01 updated:<2026-02; not sure how to use a advanced import filter with a custom template though.
  • Might be faster to do manually, might be faster to write an ad-hoc script.
• Edit the wiki: Write up and endorse this process.
  • IDK wiki perms yet, but anyone can offer the text copy.
• Edit the wiki: Write appropriate close message templates to use when triaging.
  • IDK wiki perms yet, but anyone can offer the text copy.

Ongoing Process

A member of @micropython/triage-team volunteers to take responsibility for the triage of the Issues or Pull Requests that they choose to, and executes that responsibility by following the steps of either the Basic Triage or Technical Triage process where they remain a useful communication tool to save time and effort, and by applying common sense to deviate from them where appropriate.

Basic Triage

1. The triage volunteer who chooses a basic triage task checks an active incomplete Basic Triage milestone to find an unassigned issue (or PR) that they have the time and ability to triage immediately on selection.
2. The volunteer immediately assigns themselves to it, so other triage volunteers don't waste their effort on the same redundant triage.
   
3. The volunteer reads the issue and review the issue's comment history.
4. The volunteer applies appropriate labels to their issue, if they know of a suitable one:
   
5. The volunteer closes the issue with a templated close message, or with a custom message; or they endorse the issue or PR as worth their or another volunteer's time to perform a technical triage.
   1. When closing with a templated message, they save effort by copy-pasting from an appropriate section in the wiki, such as:
      • Out of Scope for MicroPython
      • Not Enough Information
      • Follow the Submission Template
      • Spam Warning
   2. When using a custom close message, they make sure to invite the PR's submitter to re-open or re-submit their issue if they disagree or when they have resolved the underlying deficiency.
   3. When endorsing for technical triage, they unset the "{year} Basic Triage" milestone and set the "{year} Technical Triage" milestone.
6. If sufficiently nerd-sniped, the volunteer continues on into Technical Triage at the appropriate step.
   Otherwise, or if at other time they lose interest or availability or can't complete the triage, they un-assign themselves from the issue.

Technical Triage

1. The triage volunteer who chooses a technical triage task checks an active incomplete Technical Triage milestone and filters it by issue label to find an unassigned issue (or PR) that they have the time, technical knowledge, and interest to triage soon after selection.
2. The volunteer immediately assigns themselves to it, so other triage volunteers don't waste their effort on the same redundant triage.
3. The volunteer reads the issue and review the issue's comment history.
4. The volunteer closes the issue with a templated close message, or with a custom close message; or they endorse the issue as worth an effort to fix (or to review for merging, for PRs).
   1. When closing with a templated message, they save effort by copy-pasting from an appropriate section in the wiki, such as:
      • Fixed by (PR / commit / version)
      • Could Not Reproduce
      • Superceded by (other PR / Issue)
      • Consider Rebasing to Latest Master
      • Consider Resubmitting to (micropython-lib / community-boards / upstream dependency)
   2. When writing a custom close message, they make sure to invite the PR's submitter to re-open or re-submit their issue if they disagree or when they have resolved the underlying deficiency.
   3. When endorsing for full review:
      1. They unset the "{year} Technical Triage" milestone and set an appropriate MicroPython release-version milestone. (i.e. Next open micro version for a bug fix; next open minor version for a feature improvement; all based on which versions are still open for additions.)
      2. They report any symptoms or other details they were able to observe or reproduce about a bug.
      3. They use the github's search function, git-blame records, and their knowledge of the community and its members to comment with missing #-citations to related issues and @-mentions of relevant contributors.
5. If sufficiently nerd-sniped, they comment about their intent to submit a PR that fixes an Issue and then do so; or submit a Code Review for a PR.
   Otherwise, or if at other time they lose interest or availability, they un-assign themselves from the issue.

[Josverl]

Collaboration Tooling

I very much prefer prefer to use GH Projects over Milestones for this work.

I think of it as :

• Milestones = “When do we want this done?”
  • single Repro
• Projects = “How do we organize and track the work?”
  • works across multiple repos
  • can do simple thigs , and more complex things
  • has a kanban board view ( can be driven by simple automation rules for several of the actions mentioned above by @AJMansfield )
  • can be scripted via GH-CLI

Project sneakpeak

An old one of mine:

not sure if you can access : ttps://github.com/users/Josverl/projects/4/views/7

Ad hoc & repeatable queries

I have been using VSCode + GitHub Issue Notebooks to query and look for issues based on text and properties.
The only downside is that it does not provide to automated updates (I think that may be intentional)

SneakPeak

[AJMansfield]

I'm not as familiar with how projects function tbh, but it might be suitable. The main virtues that attract me to Milestones here, and which I'd hope to find in GH Projects:

• Some way to divide up issues into eminently finite blocks small enough that even a single 'close' meaningfully shortens the list.
• A very visible progress bar for each such block to make increments easy to see and celebrate as small wins along the way.
• Some way to track issues through multiple life-cycle stages.
• Lists of issues segregated at least heuristically on the type and quantity of effort likely needed to usefully advance them to another life-cycle stage.

[AJMansfield]

For the sake of testing out how a GH Project here might look, I set up one that's more-or-less how I'd imagine it, for a January 2026 bucket: https://github.com/orgs/micropython/projects/2

[agatti]

For the sake of testing out how a GH Project here might look, I set up one that's more-or-less how I'd imagine it, for a January 2026 bucket: Triage: January 2026

That looks fine by me. It could also work with @Josverl's suggestion of focusing efforts on specific topics first (at least until most of the backlog is taken care of) and maybe later switch to a per-date model as you suggest?

I also thought about having default people being assigned to issues that get tagged with a specific label but then I realised some people would get most of the assignments. This could work with an increased label granularity, but right now I believe there are enough of them anyway (maybe a label for mpy-cross could be nice to have).

Everything else I've read so far looks reasonable.

[Josverl]

Lets put the 🐘 on the barbie :-)

I think it is best to separate triaging from fixing , or adding features or chiseling bytes from firmware sizes.
Triage

• should allow for a quicker decision (avoid limbos)
• we can teach submitters to self triage ( see issue templates)
• can driven distributed daily / weekly, and aided by labels and some light automation
• when clearly communicated, Issues can be re-opened.
• adding a few Labels should help : needs info, needs reproduction, confirmed, duplicate, won't-fix

Fixing vs adding features / functionality.

I feel this is a tougher nut to crack - what is important to me may not be relevant to the community, or it may be orthogonal to Damien's goals.
It is hard to "mind-melt" on this - especially across the different time zones

• 3 - Australia East (UTC+10 to UTC+11)
• 2 - North America (UTC−8 to UTC−6)
• 5 - UK+Europe (UTC+0 to UTC+2)

So

• The good news: There is always someone awake ☀️
• The bad : there is always someone asleep as well 🌔

[AJMansfield]

I do think making more use of labels to categorize issues is a good idea.

Could we trigger an automation to close with a templated message on the addition of a corresponding label? On a technical level, a submitter can re-open their issue just as easily as a triage volunteer can close it, but it could help usefully shape the social sensation involved for both the triage volunteer and the issue submitter --- e.g. reduce the social "being mean" energy it costs a triage volunteer to close an issue, while ensuring that the submitter has the appropriate guidance on when and whether to re-open it.

[Josverl]

yes automation can help, but should not take the human out of the loop

• Auto Close issues (or PRs) that have had a "Human reply && Labllled "more info needed | repro needed | ..." AND have not been responded to in X days , with a nice thank you , please reopen when needed, are a good automation candidate

• Initially assigning labels based on description ( AI are quite decent at classification ) and there are actions specifically created for this, but they will need to be configured with a set of rules.
  Lets start by defining these rules - and validating then in the good old human powered way.
  IMO automation only comes later, and can use pattern matching algorithms , regexes or AIs - plenty of options.

[AJMansfield]

AND have not been responded to in X days

I don't think we actually should leave fundamentally deficient issues or PRs open for their submitters to correct --- we should just close them with an explanation of what's wrong and ask the submitter to re-open them once they've corrected it.

but should not take the human out of the loop

100%, I'm not proposing to take the human out of the loop --- I'm proposing to give the human an automation-shaped mask, that also benefits the submitter by not forcing them to feel like they're calling a fellow human wrong to their face by re-opening their issue. What I'd imagine, is a workflow where human clicks the "out-of-scope" label, and two seconds later a bot account closes the issue with this sort of message:

Triage Bot
This issue seems to be: Out of Scope for MicroPython. See {wiki link} for information on what this means.
Triage-Bot sometimes makes mistakes; if you feel this is incorrect or have made edits that address this, please click 'reopen' to reopen this issue for @{assignee} to manually review.

[agatti]

AND have not been responded to in X days

I don't think we actually should leave fundamentally deficient issues or PRs open for their submitters to correct --- we should just close them with an explanation of what's wrong and ask the submitter to re-open them once they've corrected it.

Well, maybe we can do that right now for old PRs where it is obvious that the submitter is no longer involved (eg. account being inactive since X months/years, nothing Python/embedded related in their activity for a long while, etc). Otherwise, asking for a (timed) feedback is something we can maybe afford to do, we've got the resources to keep track of the backlog now.

[Josverl]

I have been pondering and reading about what works / does not work in other OSS projects
Interestingly there is a conversation in CPython discuss about cleaning up issues that I find relevant.
From our friends at CPython I found 2 triage documents from C-Python triaging and issues and triaging that we could use as a starting point

Then I found and I watched a non-technical talk form a very technical guy, Brett Cannon, on OSS Participation.

That has me thinking about what I could or cannot do, and what would actually that actually help most, and enjoy it.

• I do not expect to get pleasure from trying to get to 0 issues , (empirical evidence suggest that wont happen anytime soon )
  -If I "Just" create more PRs, even to fix issues , will require more reviews, integration testing, etc. and there are some 500 ones waiting, and it takes real time and effort.
  -I think I can spend some of my time on the quality of the issues and PRs and help bring them on PAR , just to save someone else time.
  -I would rather work on a specific topic of issues PRs ( like I tried to do on Unicode - find issues - label them - repro them - then fix them) - But I did not check up-front if there was any desire to support Unicode - Micro does mean not including all features after all.

"Always remember, your focus determines your reality."
For me it would help if there were a few more or less defined "buckets" or things to jointly focus on for a few months or weeks at a time.
Whether that is getting deepsleep more consistent, giving zephyr a boost, boosting mpremote, or doing a docsprint are all good.

So shared focus, over than volume.