Skip to content

chore: migrate area and topic labels to the new taxonomy #5151

Open

Description

@purp

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

  1. purp commented on Nov 2, 2026

    @purp
    CollaboratorAuthor

    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 retiring area:* and topic:* 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.

  2. rhuss commented on Nov 3, 2026

    @rhuss
    Contributor

    I'm wondering whether we can have a label topic:ux. We have topic: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:cli and area:tui don't really belong under topic:dx. topic:operability doesn'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:

    • CLI command and flag design, naming, and consistency across subcommands
    • help text, error messages, exit codes, and output formats (human and machine readable)
    • TUI interaction design
    • the first-run path from install to a working sandbox

    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:ux roster. Since topics are cheap compared to areas, I think even a small roster is worth it, because otherwise these items land in area:platform next to persistence and API machinery.

  3. purp commented on Nov 3, 2026

    @purp
    CollaboratorAuthor

    I'll add that in #4863 and we should remap above accordingly.

  4. purp commented on Nov 4, 2026

    @purp
    CollaboratorAuthor

    We need to also true up existing label descriptions as noted by @elezar:

    I see my triage of an issue printed the following:

    Next human decision: a maintainer to record disposition. I did not change labels: state:validated has no description in the repo, so I can't confirm it is the right replacement for state:triage-needed.
    #5241 (comment)

    We probably need to just audit our label descriptions.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions