Changelog Draft Generator

Changelog Draft Generator

Inputs

Workflow

Step 1 — Determine the release range

Infer the previous release cut for comparison. Release tags follow the pattern v0.YYYY.MM.DD.HH.MM.<channel>_NN, where _NN is the RC/hotfix number within that release cut. Multiple tags can share the same date prefix (e.g. _00, _01, _02 are all part of one release cut).

The base tag must be the _00 tag of the previous release cut (i.e. a different date), not just the previous tag. For example, if generating a changelog for v0.2026.04.29.08.57.stable_01, the base should be v0.2026.04.22.08.57.stable_00, not v0.2026.04.29.08.57.stable_00.

# 1. Extract the date prefix from the release_tag (everything before _NN)
release_date_prefix="${release_tag%_*}"

# 2. List all _00 tags for the channel (these are release cut points), sorted descending
git tag --list "v0.*.${channel}_00" --sort=-version:refname

# 3. Pick the first _00 tag whose date prefix differs from release_date_prefix

Record the range as previous_cut_tag..release_tag.

Step 2 — Fetch PR data

Run the fetch_prs.py script to collect all public-release PRs merged in the release range and extract explicit changelog markers. Pass the repository that the workflow checked out, not necessarily the public repository. Release workflows run from warpdotdev/warp-internal, and the script deterministically resolves warp-repo-sync[bot] PRs back to their original public warpdotdev/warp PR metadata before emitting JSON. When running from warpdotdev/warp-internal, the script intentionally omits PRs that were not authored by the repo-sync bot, because those are private internal changes that must not be exposed to the changelog agent or generated artifacts.

python3 .agents/skills/changelog-draft/scripts/fetch_prs.py \
  --repo "${GITHUB_REPOSITORY:-warpdotdev/warp}" \
  --base-ref <previous_tag> \
  --head-ref <release_tag>

The script outputs JSON to stdout with this structure:

{
  "range": { "base": "<previous_tag>", "head": "<release_tag>" },
  "prs": [
    {
      "number": 1234,
      "url": "https://github.com/warpdotdev/warp/pull/1234",
      "title": "...",
      "commit_subject": "... (#1234)",
      "author": "username",
      "body": "...",
      "labels": ["..."],
      "merged_at": "2026-05-01T...",
      "explicit_entries": [
        { "category": "NEW-FEATURE", "text": "Added dark mode" }
      ],
      "linked_issues": [5678],
      "changed_files": ["app/src/ai/agent.rs", "crates/warp_features/src/lib.rs"],
      "source_repo": "warpdotdev/warp",
      "internal_pr": {
        "number": 25712,
        "url": "https://github.com/warpdotdev/warp-internal/pull/25712",
        "author": "warp-repo-sync[bot]",
        "title": "...",
        "repo": "warpdotdev/warp-internal"
      }
    }
  ]
}

Use the top-level number, url, commit_subject, author, body, labels, changed_files, and source_repo fields as the source of truth. internal_pr is audit-only and must never be used for contributor attribution or user-facing changelog links. If url is empty, omit the PR link from user-facing markdown rather than synthesizing one.

Step 3 — Classify contributors

Run the classify_contributors.py script with the unique author logins from Step 2:

python3 .agents/skills/changelog-draft/scripts/classify_contributors.py \
  --org warpdotdev \
  --authors author1,author2,author3

Output JSON:

{
  "internal": ["author1"],
  "external": ["author3"],
  "bot": ["author2"],
  "unknown": []
}

Step 4 — Extract feature flags

Run the extract_feature_flags.py script to get the current flag gate lists:

python3 .agents/skills/changelog-draft/scripts/extract_feature_flags.py \
  --file crates/warp_features/src/lib.rs

Output JSON:

{
  "release_flags": ["Autoupdate", "Changelog", ...],
  "preview_flags": ["Orchestration", ...],
  "dogfood_flags": ["LogExpensiveFramesInSentry", ...]
}

Step 5 — Fetch issue reporters

Collect all unique linked_issues from Step 2 and fetch the original reporter for each. Pass --org so the script checks org membership and filters out internal reporters automatically:

python3 .agents/skills/changelog-draft/scripts/fetch_issue_reporters.py \
  --repo warpdotdev/warp \
  --org warpdotdev \
  --issues 5678,9012

Output JSON (only external reporters are included):

{
  "issue_reporters": [
    {
      "issue_number": 5678,
      "title": "Crash when opening large file",
      "reporter": "community-user",
      "reporter_url": "https://github.com/community-user",
      "url": "https://github.com/warpdotdev/warp/issues/5678"
    }
  ]
}

The --org flag checks each reporter's org membership via the GitHub API, filtering out internal members so they aren't misattributed as external community reporters. These reporters will be credited in the "Community" section of the changelog. Whenever the markdown draft credits a PR author, contributor, or issue reporter, render the username as a GitHub profile link such as [@username](https://github.com/username).

Step 6 — Classify unmarked PRs

Determine TUI impact independently from the regular changelog category for every PR. Explicit CHANGELOG-TUI and CHANGELOG-OZ markers are authoritative entries and may coexist with New Feature, Improvement, or Bug Fix entries. When a PR has an explicit TUI entry, preserve its other explicit entries. Otherwise, if commit_subject contains TUI as a standalone case-insensitive token, route any explicit New Feature, Improvement, or Bug Fix text to TUI instead of its regular category. This keeps clearly TUI-labeled changes out of the desktop changelog while allowing explicitly marked shared changes to appear on both surfaces.

For each PR that has no explicit CHANGELOG-* entries, decide whether to include it and under which category.

Follow the classification guidance in .agents/skills/classify-changelog-pr/SKILL.md.

For each unmarked PR, produce a classification:

{
  "pr_number": 1234,
  "include": true,
  "category": "IMPROVEMENT",
  "text": "Proposed changelog line",
  "impacts_tui": true,
  "confidence": "high",
  "rationale": "...",
  "feature_flag": null,
  "needs_review": false
}

Key rules:

• PRs that only touch CI, tests, docs, or internal tooling → include: false
• PRs behind dogfood-only feature flags → include: false for stable channel
• PRs behind preview flags → include: false for stable, include: true for preview
• Set impacts_tui: true when Warp Agent CLI users observe the change, including shared Agent capabilities such as tool-call or edit-file behavior
• When in doubt, set needs_review: true and confidence: "low"
• Bot PRs (dependabot, renovate, etc.) → include: false

Feature-flag detection: Use the changed_files list from Step 2 to check if any PR touches crates/warp_features/src/lib.rs or references a FeatureFlag variant in its title/body. Cross-reference with the flag lists from Step 4 to determine channel visibility.

Unknown contributors: Authors in the unknown bucket (org membership check failed due to auth) should be treated conservatively — do not attribute them as external. Note them in the output for manual verification.