classify-changelog-pr

# Classify Changelog PR This document provides classification rules for PRs that lack explicit `CHANGELOG-*` markers. The changelog-draft agent follows these rules inline when deciding whether to include an unmarked PR. ## Categories - **NEW-FEATURE** — A substantial new user-facing capability. Reserve for features that would warrant docs, marketing, or social media attention. - **IMPROVEMENT** — Enhances an existing feature in a way users would notice (performance, UX, new options). - **BUG-FIX** — Fixes a user-visible bug or regression. - **OZ** — Changes to Oz / AI agent capabilities. At most 4 per release in the stable changelog. - **TUI** — User-visible changes that impact the Warp Agent CLI/headless TUI, including shared Agent capabilities. - **NONE** — Explicitly opt out of changelog inclusion. Handled upstream by `fetch_prs.py` marker extraction. ## Decision rules ### Always exclude - PRs with an explicit `CHANGELOG-NONE` marker (contributor opted out) - PRs authored by known bots (dependabot, renovate, github-actions, codecov) - PRs that exclusively modify CI workflows (`.github/workflows/`), test files, or dev tooling - PRs that only update internal docs, comments, or README files - Dependency bumps with no user-facing behavior change - Refactors with no observable behavior change (code moves, renames, formatting) ### Always include - PRs with explicit `CHANGELOG-*` markers (handled before this guidance applies) - PRs that fix a crash, data loss, or security issue — even without a marker ### TUI surface classification - Treat explicit `CHANGELOG-TUI` and `CHANGELOG-OZ` markers as authoritative entries. They are independent and may coexist with each other or with regular changelog categories. - Determine TUI impact independently from the regular New Feature, Improvement, or Bug Fix category. A shared Agent capability may belong in both its regular category and `TUI`. - Classify a user-visible entry as impacting `TUI` when `commit_subject` contains `TUI` as a standalone token. - For stable releases, also use the PR title/body and TUI-owned paths such as `crates/warp_tui` or `crates/warpui_core/src/elements/tui`. Shared capabilities such as Agent tool-call or edit-file behavior also impact TUI when Warp Agent CLI users observe the change. If metadata is ambiguous, inspect the commit diff. - Do not infer TUI impact from file paths alone; confirm that Warp Agent CLI users observe the changed behavior. - A TUI-only entry belongs only in the TUI category. An entry that impacts both TUI and another surface should appear in both `TUI` and its regular category. ### Conditional on channel - **Stable channel:** Only include changes that are live for all users. Exclude PRs gated behind `DOGFOOD_FLAGS` or `PREVIEW_FLAGS`. - **Preview channel:** Include PRs gated behind `PREVIEW_FLAGS`. Still exclude `DOGFOOD_FLAGS`-only changes. - **Dev channel:** Include everything that's user-visible, regardless of flag gates. ### Feature-flagged PRs If a PR mentions a `FeatureFlag` variant in its diff or title: 1. Check which flag list it belongs to (`RELEASE_FLAGS`, `PREVIEW_FLAGS`, `DOGFOOD_FLAGS`). 2. Apply the channel rules above. 3. If the flag is in `RELEASE_FLAGS` or enabled by default in `app/Cargo.toml`, treat it as live. 4. Set `feature_flag` in the classification output to the flag name. ### Confidence levels - **high** — Clear user-visible change with obvious category. - **medium** — Likely user-visible but category or scope is somewhat ambiguous. - **low** — Unclear whether users would notice; or the PR touches both internal and user-facing code. Set `needs_review: true`. ## Writing changelog text - Write from the user's perspective: "Added X", "Fixed Y", "Improved Z". - Keep it to one sentence, ≤ 120 characters. - Don't reference internal implementation details, file paths, or function names. - Don't start with "PR" or the PR number — those are added as metadata. - Use active voice and present tense for new features ("Adds dark mode"), past tense for fixes ("Fixed crash on startup").