Issue Management

This document defines the repository issue operating model for reporters, contributors, and maintainers. It aligns issue intake with the engineering constraints in AGENTS.md and the contributor workflow in CONTRIBUTING.md.

Goals

  • Keep issue titles predictable and searchable.

  • Separate classification from titles by using structured metadata and labels.

  • Make epics and work items decomposable without title hacks such as [Step 1].

  • Ensure every issue is actionable before implementation begins.

Issue hierarchy

The repository uses three levels of work tracking:

Initiatives

Optional portfolio-level trackers for multi-epic programs. Use these sparingly and only when several epics must be coordinated together.

Epics

Multi-PR efforts with a clear objective, scope, non-goals, and linked child issues.

Work items

Single implementable outcomes such as a bug fix, feature, refactor, docs improvement, or test task.

Use GitHub sub-issues or explicit parent/child links in the issue body instead of prefixes such as [Step 2].

Title convention

Issue titles should follow this format:

<type>(<area>): <concise outcome>

Examples:

  • bug(http): delegate URL path construction to httpx

  • refactor(core): decouple async and sync client hierarchies

  • docs(contributing): document issue triage workflow

  • epic(core): architecture modernization and thread-safety

Avoid the following title patterns:

  • [Step 1] ...

  • [P1] ...

  • [EPIC] ...

  • Initiative: ...

  • numbered defect titles such as 4 Brittle URL Path Construction

Priority, sequence, and hierarchy belong in labels, linked issues, and the issue body rather than in the title.

Label taxonomy

Apply labels across consistent dimensions. Each ready work item should have one label from the type:, area:, and priority: groups at minimum.

Type labels

  • type:bug

  • type:feature

  • type:refactor

  • type:docs

  • type:test

  • type:ci

  • type:security

  • type:maintenance

  • type:epic

Priority labels

  • priority:p0

  • priority:p1

  • priority:p2

  • priority:p3

Area labels

  • area:core

  • area:models

  • area:http

  • area:auth

  • area:pagination

  • area:cli

  • area:docs

  • area:tests

  • area:ci

  • area:release

  • area:workflows-plugin

  • area:airflow-provider

  • area:contributing

Status labels

  • status:triage

  • status:ready

  • status:in-progress

  • status:blocked

  • status:needs-info

  • status:done

Size labels

  • size:xs

  • size:s

  • size:m

  • size:l

  • size:xl

Risk labels

  • risk:low

  • risk:medium

  • risk:high

Required issue content

Every implementation issue should capture the following:

  • problem statement

  • expected outcome

  • constraints or non-goals

  • acceptance criteria

  • test impact

  • docs impact

  • affected package

  • API surface impact

  • compatibility impact

  • verification requirements

The issue templates in .github/ISSUE_TEMPLATE/ enforce this structure for new issues.

Definition of Ready

An issue is ready when it has:

  • a normalized title

  • one type:* label

  • one area:* label

  • one priority:* label

  • a clear problem statement

  • explicit acceptance criteria

  • dependency notes when relevant

  • documented test and docs impact

Definition of Done

An issue is done when:

  • the linked PR is merged

  • tests were added or updated when required

  • docs and examples were updated when applicable

  • status labels reflect the merged state

  • the parent epic or initiative was updated when the work was part of a larger effort

Epic requirements

Each epic should include:

  • objective

  • scope

  • non-goals

  • acceptance criteria

  • linked child issues

  • sequencing or dependency notes

An epic should track delivery, not duplicate full design documents.

Implementation issue requirements

Each work item should answer:

  1. What is wrong or missing today?

  2. What outcome should exist when the issue is complete?

  3. What constraints must be preserved?

  4. How will reviewers know it is complete?

When a work item is derived from a larger effort, link the parent epic and avoid duplicating milestone or sequencing information in the title.

PR linkage

Pull requests should reference the issue they implement and use a Conventional Commit title such as fix:, feat:, or refactor:. Issue titles and PR titles do not need to be identical, but they should describe the same outcome.

Migration guidance for existing issues

When retrofitting legacy issues:

  1. Rename the issue to match the normalized title format.

  2. Replace title prefixes with labels and body metadata.

  3. Add parent or child links for epics and decomposed work.

  4. Add missing acceptance criteria, dependency notes, and verification expectations.

  5. Mark duplicates or superseded work explicitly instead of leaving overlapping issues ambiguous.