Issue types should mean the same thing across repositories

A shared issue type is useful when a reader can interpret it without first learning which repository produced it. Its meaning should remain stable while priority, ownership and delivery state change. Otherwise, an organization can collect neatly classified issues and still be unable to answer a basic question about the work they represent.

This November 2026 retrospective returns to the week of 15 January 2025. GitHub's 13 January public-preview announcement introduced a wider rollout of issue types, sub-issues and advanced search after an earlier opt-in preview. Issue types were presented as a shared language across repositories in an organization. Willison discussed the changes on 16 January. The relevant design question is what that language should mean, rather than how many categories the interface can hold.

Separate the nature of work from its current treatment

A defect can be urgent this week and deferred next week while remaining a defect. An enhancement can move between teams without becoming a different kind of request. Type should help describe the nature of the work; labels and other fields can describe changing concerns such as priority or the area involved.

This separation is an editorial recommendation, not a requirement imposed on every team by GitHub. Its value depends on the question being asked. A cross-repository query for defects is meaningful only if repositories use a sufficiently similar definition. Shared spelling alone does not provide shared interpretation.

Consider an illustrative organization with a web application and an integration service. One team calls every customer request a bug. The other reserves that word for behavior that violates an accepted requirement. A combined defect count now mixes unmet expectations with agreed behavior that stopped working. The query may be technically correct while the management inference is wrong.

Before adopting shared types, identify the decision the comparison is meant to support. If the concern is recurring failures of agreed behavior, define that explicitly. If the concern is all customer dissatisfaction, a narrow defect type will not capture it. Choose the vocabulary after the question, rather than choosing a chart and hoping its categories explain themselves.

Start with a few proposed definitions

A minimal vocabulary could define a bug as behavior that violates an accepted expectation, a feature as a requested change to what the product can do, and a task as enabling or maintenance work without a new user capability. These are proposed definitions for discussion. They are starting points, not a claim that GitHub mandates these meanings.

The definitions need examples at their boundaries. Suppose an import accepts a format the team never promised to support and produces an unhelpful error. Supporting that format may be a feature; improving the error may be a separate change. If the product did promise that format, the failed import belongs under a different interpretation. The accepted expectation matters more than the requester's choice of noun.

Security work is similarly not one automatic type. Repairing behavior that violates a permission requirement differs from introducing a capability for a new access model. Priority can be high in either case. Keeping urgency separate avoids turning a type into a shortcut for deciding what must happen first.

When classification remains ambiguous, preserve the uncertainty until the underlying expectation is clear. Forcing an early label can create false precision. A short description of the unresolved question may be more useful than a category that everyone reads differently.

Hierarchy describes decomposition

GitHub's announcement separately describes sub-issues as a parent-child structure for breaking work down. That relationship answers how pieces contribute to a larger effort. It does not establish whether a piece is a bug, feature or maintenance task. A parent initiative can contain several kinds of work without losing a coherent purpose.

For the hypothetical import improvement, a parent might include a parser change, documentation and recovery behavior. Giving every child the parent's type merely to keep the tree uniform would weaken the vocabulary. Conversely, a shared type does not imply that unrelated issues belong under one parent. Structure and meaning should serve separate questions.

There is a business consequence to this distinction. A progress view can show decomposition without establishing comparable scope or effort across repositories. Counting completed children does not make two initiatives equally complete in business terms. The type vocabulary helps interpretation, but it cannot turn issue counts into a reliable measure of developer productivity.

Labels alone can be enough

The strongest counterargument is a small, single backlog whose participants already share context. Labels may answer its questions perfectly well. Adding organization-wide types can introduce classification work without improving a decision. The availability of a feature is not a reason to create a governance exercise.

Even across repositories, the payoff can be limited if nobody needs a combined interpretation. Keep the vocabulary as small as the real question permits. If two categories repeatedly produce the same decisions, their distinction may not earn the effort required to maintain it.

The historical announcement establishes the January preview and its intent. It is not a statement that all interface details, availability conditions or limits remain identical in November 2026. A current implementation should consult current product documentation. The semantic recommendation here survives independently: definitions should remain understandable as issues change state.

For custom software development, start with one cross-repository question and a handful of ambiguous examples. See whether proposed definitions lead different teams to the same interpretation. Adopt shared types only where that consistency improves a real decision, and leave priority, temporary concerns and decomposition free to describe their own dimensions of the work.