56 lines
3.1 KiB
Markdown
56 lines
3.1 KiB
Markdown
---
|
|
name: classify-changelog-pr
|
|
description: Reference guidance for classifying whether an unmarked PR should appear in the changelog and under which category. Used inline by the changelog-draft skill — not dispatched as a separate agent.
|
|
---
|
|
|
|
# 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.
|
|
- **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
|
|
|
|
### 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").
|