docs(triage): complete part of Phase 0 of the roadmap #522

Closed

nicholasgower wants to merge 2 commits from roadmap-followup into main

nicholasgower commented

2026-11-08 08:08:30 +00:00

(Migrated from github.com)

Summary

Completes the repository-side part of Phase 0 - Triage and release hygiene from ROADMAP.md. It is stacked on the previous roadmap PR, #518: this branch is based on that commit, so #518 should be reviewed and merged first. This PR does not modify #518.

Phase 0 is about making the tracker usable before writing more fixes. It adds the label definitions, a dry-run triage tool, a manual workflow to apply it, rewritten issue forms, a known-issues page, issue guidelines and a maintainer runbook. It does not change game code.

What is in this PR

.github/labels.json - label definitions for area, vendor, type, status and priority.
scripts/triage_issues.py - reads the roadmap appendix and can add labels, link duplicates, ask for missing logs, mark retests and pin canonical trackers. Dry run by default.
.github/workflows/triage-issues.yml - manual Actions > Apply issue triage workflow with apply, comments, close_duplicates and pin switches.
.github/ISSUE_TEMPLATE/1-game-problem.yml, 2-build-problem.yml, 3-idea.yml and config.yml - rewritten around version, log, steps, worker line, known issues and one problem per issue.
docs/known-issues.md - the first-30-minutes page: shader warm-up, AV1 movies, black screens, cache reset, AMD/RADV, exposure flicker, 4 GB cards, build stops and the canonical tracker for each.
docs/issue-guidelines.md - replaces the old #159 guidance with what to send and what happens after a report.
docs/triage.md - the maintainer runbook for labels, pinning, duplicates, needs-info and retests.
tests/test_triage_plan.py - game-free check that the roadmap appendix is complete and that every duplicate points at a real canonical issue.
ROADMAP.md, readme.md, CONTRIBUTING.md and the source-regressions workflow updated to point at the new material.

Verification

python -I -B tests/test_triage_plan.py: 133 issues, 61 duplicate links, 29 labels
The issue-form and workflow YAML parses cleanly.
scripts/triage_issues.py --dry-run completes against the live tracker, including new reports such as #519, #520 and #521, which it marks needs-triage.
No upstream write was performed: the credential used for this work has only pull permission on NotRexed/Hookshot. That is why the remaining actions are listed below.

What the repository owner must do to finish Phase 0

Merge #518 first, then this PR. The Phase 0 files depend on the roadmap appendix. The triage workflow only runs from the default branch.
Run the triage workflow once in dry-run mode. After merge: Actions > Apply issue triage, leave apply off. Review the labels, the duplicate links and the new needs-triage reports.
Apply the labels and dispositions. Run the workflow again with apply on. Add comments to post the duplicate / needs-info / retest text. This creates the labels from .github/labels.json and labels the 133 snapshot issues plus the new ones.
Pin the canonical trackers. Run with pin on, or pin manually from docs/triage.md: #503, #493, #287, #500, #150, #309, #195, #145, #319, #468, #36, #302, #361, #352, #11, #105, #17, #388, #413, #312, #148 and #454. If the workflow token cannot use GraphQL pinIssue, pin them from the issue UI.
Decide when to close duplicates. The tool defaults to keeping them open. close_duplicates is separate because the rule is: link first, close only when the canonical fix is verified and the reporter has been told what to retest.
Triage reports that arrived after the snapshot. #519, #520, #521 and later ones are intentionally left as needs-triage rather than guessed into a phase.
Enforce the release habits. Do not update the builder while a build is running; batch releases and name the P0 fixes in the notes. Installer retention is PR #514; this part is a project habit rather than code.
Confirm the Phase 0 exit criteria. Every open issue has a label and a disposition, the canonical trackers are pinned, and a new reporter can find the right tracker in under a minute.

Notes

Version display was already implemented in gpu/vk/vk_menu.cpp and host/hos_main.c; no code change was needed for #325/#481.
The repository contains no game files or generated game content.
Previous PR: #518.

## Summary Completes the **repository-side part of Phase 0 - Triage and release hygiene** from [ROADMAP.md](https://git.magicbean.dev/MagicBeanDev/Hookshot/src/branch/main/ROADMAP.md). It is stacked on the previous roadmap PR, **#518**: this branch is based on that commit, so #518 should be reviewed and merged first. This PR does not modify #518. Phase 0 is about making the tracker usable before writing more fixes. It adds the label definitions, a dry-run triage tool, a manual workflow to apply it, rewritten issue forms, a known-issues page, issue guidelines and a maintainer runbook. It does not change game code. ## What is in this PR - `.github/labels.json` - label definitions for area, vendor, type, status and priority. - `scripts/triage_issues.py` - reads the roadmap appendix and can add labels, link duplicates, ask for missing logs, mark retests and pin canonical trackers. Dry run by default. - `.github/workflows/triage-issues.yml` - manual **Actions > Apply issue triage** workflow with `apply`, `comments`, `close_duplicates` and `pin` switches. - `.github/ISSUE_TEMPLATE/1-game-problem.yml`, `2-build-problem.yml`, `3-idea.yml` and `config.yml` - rewritten around version, log, steps, worker line, known issues and one problem per issue. - `docs/known-issues.md` - the first-30-minutes page: shader warm-up, AV1 movies, black screens, cache reset, AMD/RADV, exposure flicker, 4 GB cards, build stops and the canonical tracker for each. - `docs/issue-guidelines.md` - replaces the old #159 guidance with what to send and what happens after a report. - `docs/triage.md` - the maintainer runbook for labels, pinning, duplicates, needs-info and retests. - `tests/test_triage_plan.py` - game-free check that the roadmap appendix is complete and that every duplicate points at a real canonical issue. - `ROADMAP.md`, `readme.md`, `CONTRIBUTING.md` and the source-regressions workflow updated to point at the new material. ## Verification - `python -I -B tests/test_triage_plan.py`: **133 issues, 61 duplicate links, 29 labels** - The issue-form and workflow YAML parses cleanly. - `scripts/triage_issues.py --dry-run` completes against the live tracker, including new reports such as #519, #520 and #521, which it marks `needs-triage`. - No upstream write was performed: the credential used for this work has only `pull` permission on NotRexed/Hookshot. That is why the remaining actions are listed below. ## What the repository owner must do to finish Phase 0 1. **Merge #518 first, then this PR.** The Phase 0 files depend on the roadmap appendix. The triage workflow only runs from the default branch. 2. **Run the triage workflow once in dry-run mode.** After merge: **Actions > Apply issue triage**, leave `apply` off. Review the labels, the duplicate links and the new `needs-triage` reports. 3. **Apply the labels and dispositions.** Run the workflow again with `apply` on. Add `comments` to post the duplicate / needs-info / retest text. This creates the labels from `.github/labels.json` and labels the 133 snapshot issues plus the new ones. 4. **Pin the canonical trackers.** Run with `pin` on, or pin manually from `docs/triage.md`: #503, #493, #287, #500, #150, #309, #195, #145, #319, #468, #36, #302, #361, #352, #11, #105, #17, #388, #413, #312, #148 and #454. If the workflow token cannot use GraphQL `pinIssue`, pin them from the issue UI. 5. **Decide when to close duplicates.** The tool defaults to keeping them open. `close_duplicates` is separate because the rule is: link first, close only when the canonical fix is verified and the reporter has been told what to retest. 6. **Triage reports that arrived after the snapshot.** #519, #520, #521 and later ones are intentionally left as `needs-triage` rather than guessed into a phase. 7. **Enforce the release habits.** Do not update the builder while a build is running; batch releases and name the P0 fixes in the notes. Installer retention is PR #514; this part is a project habit rather than code. 8. **Confirm the Phase 0 exit criteria.** Every open issue has a label and a disposition, the canonical trackers are pinned, and a new reporter can find the right tracker in under a minute. ## Notes - Version display was already implemented in `gpu/vk/vk_menu.cpp` and `host/hos_main.c`; no code change was needed for #325/#481. - The repository contains no game files or generated game content. - Previous PR: **#518**.

NotRexed commented

2026-11-09 05:29:42 +00:00

(Migrated from github.com)

Thank you for all the triage work! I'm closing this one: it adds a workflow that writes labels and comments on issues with the repository token, and the project keeps automation with write access out of contributed PRs; the issue forms and docs also depend on the roadmap in #518 (closed as out of date) and conflict with main now. Issue-form or docs improvements on their own are welcome as new PRs.