Repository navigation
Description
User Story
As an OpenShell maintainer, I need unresolved issues and unmerged PRs to use the agreed area and topic taxonomy so that current and potentially reopened work can be found and routed to the right reviewers.
Description
After #4863 lands, inventory the current area:* and topic:* labels and migrate applicable issues and PRs to the agreed new taxonomy. Develop and review an initial mapping, then revise it using the actual contents of affected items. This issue is for planning and carrying out the follow-up; the mapping below is a starting point for discussion, not an approved bulk transformation.
Include items regardless of open or closed state. Leave merged PRs and resolved issues unchanged where possible. An issue is resolved if any of the following applies:
- It is closed as completed.
- It has an attached merged PR that closed it.
- Its author commented that they are closing it, including abandonment or displacement by another issue.
- A maintainer commented that the project is not accepting the work.
Review closure comments and maintainer status in context; do not infer resolution solely from a closed state or silently guess when evidence is ambiguous. Record uncertain cases for human disposition. Treat PRs as merged based on their merge status, including merged PRs later reverted.
Initial mapping for discussion
These are candidate classifications based on the scopes in #4863; one old label may map to multiple new labels depending on the item. Preserve any existing intended labels and unrelated labels. Do not blindly add every suggested category to every item.
| Existing label | Candidate new labels or disposition |
|---|---|
area:build |
retain area:build |
area:cli, area:tui |
area:platform; consider topic:dx where applicable |
area:cluster |
review for area:drivers, topic:kubernetes, and/or topic:operability |
area:compute |
review for area:drivers; consider the relevant runtime or hardware topic |
area:docs |
topic:documentation; choose an area only when supported by the item |
area:gateway |
area:platform; consider area:enterprise or topic:operability as applicable |
area:inference |
review for area:runtime and/or topic:networking; do not assume all items have the same scope |
area:policy |
topic:policy; add an appropriate area based on the affected component |
area:providers, area:sandbox, area:supervisor |
area:runtime; consider relevant topics such as topic:policy or topic:networking |
area:sdk, area:sdk:go, area:sdk:python, area:sdk:rust, area:sdk:typescript |
area:platform and topic:sdk; review how language-specific discovery will be preserved |
topic:compatibility |
review by item: topic:api for API compatibility, area:drivers for backend or platform compatibility, or another appropriate category |
topic:l7 |
review for topic:networking and/or topic:policy based on the item |
topic:networking, topic:observability, topic:security, topic:testing |
retain matching labels; review meanings against the final taxonomy |
Create missing intended labels, including topic:extensions, with reviewed descriptions and colors. Determine which old labels should be retired and how to prevent future use. Deleting a GitHub label removes it from historical items too, so preserve labels on resolved issues and merged PRs where possible; explicitly decide how to handle labels that cannot be globally removed without changing that history.
Context
- Depends on the final taxonomy in feat(review): add area and topic reviewer rosters and routing #4863 landing; reconcile the mapping with the merged version before executing.
- Reviewer-routing automation may react to label changes on ready PRs. Assess and plan for notifications and review requests during migration.
- Include a dry run or reviewable inventory showing proposed additions and removals, ambiguous cases, and skipped resolved/merged items. Keep a record sufficient to audit and reverse changes if needed. Recheck item status before applying changes to account for concurrent updates.
Definition of Done
- Inventory the existing and intended taxonomy, discuss and revise the mapping, and identify ambiguous cases for human review.
- Establish the intended labels and prevent further use of retired labels without inadvertently stripping labels from historical items.
- Identify eligible issues and PRs across open and closed states using the resolution rules above, and document any exceptions.
- Review the proposed changes and account for reviewer-routing side effects before applying them.
- Migrate eligible items, preserve unrelated labels, and retain a reviewable change record and recovery path.
- Verify coverage, skipped items, and any remaining exceptions; report the outcome.
Activity
purp commentedon Nov 2, 2026
Assume that the taxonomy in #4863 is final. There may be future modifications, but that's a problem for future us.
I think retired labels could just be prefixed
retired:*in all cases and change color to dark grey or something. That would also avoid agent confusion when it decides to ignore instructions and go shopping for what's in the repo's history. We can remove any retiringarea:*andtopic:*labels that aren't in use.Given that many of the migrated labels will be case-by-case, we should prepare a per-issue migration spreadsheet that can be reviewed (agentically and perhaps by humans) so that we've got a determinate plan to execute rather than leaving it to the whim of the agent.
rhuss commentedon Nov 3, 2026
I'm wondering whether we can have a label
topic:ux. We havetopic:dx, but developer experience is something fundamentally different from user experience. Developer experience is about how easy it is to contribute to OpenShell, which is how #4863 defines it ("easy to contribute to for humans and agents"). User experience is about how OpenShell feels to the people (and agents) who drive it: whether the command grammar is consistent, whether flags are named predictably, and whether error messages and defaults make sense without reading the docs.That's why I'd change the mapping above:
area:cliandarea:tuidon't really belong undertopic:dx.topic:operabilitydoesn't fit them either, since it covers installing, upgrading, and maintaining a deployment. For example, #4280 (inconsistent command grammar across subcommands) matches neither scope. It has gone stale without triage, which I think shows the routing gap.Scope I'd propose for
topic:ux:Agents benefit as well: the public skills use the installed CLI help as their source of truth, so a consistent CLI is also easier for agents to use.
On reviewers: I'm happy to be on the
topic:uxroster. Since topics are cheap compared to areas, I think even a small roster is worth it, because otherwise these items land inarea:platformnext to persistence and API machinery.purp commentedon Nov 3, 2026
I'll add that in #4863 and we should remap above accordingly.
purp commentedon Nov 4, 2026
We need to also true up existing label descriptions as noted by @elezar: