yonlu/yellowjacket
1
1
Fork 0
Code Issues 55 Pull Requests 6 Actions Packages Projects Releases 12 Wiki Activity

Make the issue tracker the source of truth for what we are working on #92

New Issue
Closed
opened 2026-08-18 20:23:12 +00:00 by yonlu · 3 comments
yonlu commented 2026-08-18 20:23:12 +00:00
Owner
Copy Link
Copy Source

Work has been starting from a chat message and a plan file, which means two people can pick up the same thing and neither can see the other. The tracker is where that is visible, so it should be the source of truth for what is wanted and what is in flight — not a place work is recorded after the fact.

What changes

Before any work: search the tracker, and claim what you find. Claiming happens before the first edit, not before the commit, because the point is that the other person can see the work is taken while it is being done. A claim is an assignee, Status/In Progress and a comment naming the branch — all three, so it is visible in the issue list, filterable, and says what is being attempted.

If no issue covers the work, open one first. That is what makes the tracker a description of the project rather than a description of the past. Findings get filed too: a bug tripped over while doing something else is an issue with a repro, and so is a decision not to do something.

.planning/ stops being a queue. It keeps design documents and measured history — NOTES.md, the audits, the completed plans and their arguments. plans/pending/ is gone: a plan nobody is executing is an issue. Everything unimplemented in it has been filed as #85–#91, and each completed plan now says which issue carries its remainder.

What this does not change

The commit grammar. Conventional Commits are load-bearing for semantic-release, so the issue number lives in the branch name and the PR body rather than the commit subject.

The existing conventions, all of which were already right and are now written down rather than reinvented: the Kind/Area/Priority/Platform/Reviewed/Status taxonomy, #73 as the roadmap, Gitea dependencies for hard blockers, and PR #83's body shape.

Two things this fixes on the way past

Five issues were closed that had shipped a fortnight ago. #83 ended with a Closes list of ten and exactly half of them fired; #13, #19, #26, #29 and #37 were in main and still open. So the workflow now says closing is a step you take and verify, not a keyword you trust.

scripts/issue.sh is the interface, so "search the tracker" is one command rather than a curl re-derived from prose each time — which is how the CI-log endpoint came to cost two sessions. Issue bodies cross to the API as JSON and never as shell, on the same reasoning that keeps release notes out of gitea-release.sh's argument list.

Done when

CLAUDE.md describes this workflow, .planning/ holds no unimplemented ideas, and the tracker is accurate about what has shipped.

Work has been starting from a chat message and a plan file, which means two people can pick up the same thing and neither can see the other. The tracker is where that is visible, so it should be the source of truth for what is wanted and what is in flight — not a place work is recorded after the fact. ## What changes **Before any work: search the tracker, and claim what you find.** Claiming happens before the first edit, not before the commit, because the point is that the other person can see the work is taken *while it is being done*. A claim is an assignee, `Status/In Progress` and a comment naming the branch — all three, so it is visible in the issue list, filterable, and says what is being attempted. **If no issue covers the work, open one first.** That is what makes the tracker a description of the project rather than a description of the past. Findings get filed too: a bug tripped over while doing something else is an issue with a repro, and so is a decision *not* to do something. **`.planning/` stops being a queue.** It keeps design documents and measured history — `NOTES.md`, the audits, the completed plans and their arguments. `plans/pending/` is gone: a plan nobody is executing is an issue. Everything unimplemented in it has been filed as #85–#91, and each completed plan now says which issue carries its remainder. ## What this does not change The commit grammar. Conventional Commits are load-bearing for semantic-release, so the issue number lives in the branch name and the PR body rather than the commit subject. The existing conventions, all of which were already right and are now written down rather than reinvented: the `Kind/Area/Priority/Platform/Reviewed/Status` taxonomy, #73 as the roadmap, Gitea dependencies for hard blockers, and PR #83's body shape. ## Two things this fixes on the way past **Five issues were closed that had shipped a fortnight ago.** #83 ended with a `Closes` list of ten and exactly half of them fired; #13, #19, #26, #29 and #37 were in `main` and still open. So the workflow now says closing is a step you take and verify, not a keyword you trust. **`scripts/issue.sh`** is the interface, so "search the tracker" is one command rather than a curl re-derived from prose each time — which is how the CI-log endpoint came to cost two sessions. Issue bodies cross to the API as JSON and never as shell, on the same reasoning that keeps release notes out of `gitea-release.sh`'s argument list. ## Done when CLAUDE.md describes this workflow, `.planning/` holds no unimplemented ideas, and the tracker is accurate about what has shipped.
yonlu added the Kind/Documentation
Priority
High
2
 labels 2026-08-18 20:23:12 +00:00
yonlu self-assigned this 2026-08-18 20:23:25 +00:00
yonlu added the
Status
In Progress
 label 2026-08-18 20:23:26 +00:00
yonlu commented 2026-08-18 20:23:26 +00:00
Author
Owner
Copy Link
Copy Source

Starting work on this on docs/issue-driven-workflow.

Starting work on this on `docs/issue-driven-workflow`.
yonlu commented 2026-08-18 20:24:48 +00:00
Author
Owner
Copy Link
Copy Source

Opened as #93 from docs/issue-driven-workflow.

Opened as #93 from `docs/issue-driven-workflow`.
yonlu commented 2026-08-18 21:10:10 +00:00
Author
Owner
Copy Link
Copy Source

Shipped in main via #93 (ae82fd2 + eb139cf).

Closing by hand, which this issue's own rule predicted. The Closes line lived in the PR body, and #93's merge commit carried only a Reviewed-on: trailer — so no commit message on main ever contained the keyword and Gitea had nothing to parse.

Shipped in `main` via #93 (`ae82fd2` + `eb139cf`). Closing by hand, which this issue's own rule predicted. The `Closes` line lived in the PR body, and #93's merge commit carried only a `Reviewed-on:` trailer — so no commit message on `main` ever contained the keyword and Gitea had nothing to parse.
yonlu closed this issue 2026-08-18 21:10:10 +00:00
yonlu removed the
Status
In Progress
 label 2026-08-18 21:10:10 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Area/Design
Area/Downloads
Area/Explore
Area/Library-UI
Area/Metadata
Area/Packaging
Area/Player
Area/Queue
Area/Settings
Area/Shell-Nav
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
 Platform/Android
Platform/Desktop
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Medium
3
The priority is medium
Priority
Low
4
The priority is low
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
In Progress
Somebody is actively working on this right now
No labels Kind/Documentation
Priority
High
2
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
logan yonlu
No Assignees yonlu
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: yonlu/yellowjacket#92