/generating-changelog

name: generating-changelog
description: Generates polished website release notes between two git tags for docs.streamlit.io. Use when preparing a new Streamlit release or reviewing changes between versions.

Generating changelog

Generate publish-ready website changelog (docs.streamlit.io format) between two git tags. Uses PR labels (`impact:users`, `impact:internal`, `change:*`) for categorization and rewrites PR titles into user-friendly descriptions.

The GitHub release changelog is auto-generated from `.github/release.yml` — this skill only produces the website format.

**Usage:** `/generating-changelog <previous-tag> <new-tag>` (e.g., `/generating-changelog 1.44.1 1.45.0`)

If only one tag is given, treat it as the new release tag and fetch the previous tag automatically.

Step 1: Validate input

• Parse the two tags from user args. First = previous release, second = new release.
• If only one tag is given, fetch the previous tag:

  gh api repos/streamlit/streamlit/releases/latest --jq '.tag_name'

• Validate both tags exist using exact references (no pattern matching):

  git rev-parse -q --verify "refs/tags/<tag>" > /dev/null

This command must succeed (exit code 0) for each tag.

• Get the release date from the newer tag:

  git log -1 --format=%ai <new-tag>

Step 2: Fetch PR data

Run the fetch script to extract PR numbers from `git log` and batch-fetch metadata via GitHub GraphQL:

uv run python scripts/changelog_fetch_prs.py <prev-tag> <new-tag>

This produces `work-tmp/pr-data.json` — a JSON array of `{number, title, body, labels, author, related_issues, related_issues_truncated}` objects sorted by PR number. The `body` field contains the first 2500 characters of the PR description.

`related_issues` is sourced from the same batched GraphQL query (no per-PR N+1 requests) and includes linked issue numbers plus 👍 counts:

"related_issues": [{"number": 9836, "thumbs_up": 42}]

Step 3 & 4: Filter and categorize

Run the categorization script to exclude noise and categorize PRs by labels:

uv run python scripts/changelog_categorize_prs.py

This reads `work-tmp/pr-data.json`, applies the following rules, and writes `work-tmp/pr-categorized.json`:

**Excluded:** bot authors, release/version/docstring PRs, internal-only PRs (`impact:internal` without `impact:users` — this includes internal features with `change:*` labels).

**External contributors:** Each non-excluded PR includes an `is_external` boolean field. Authors matching `sfc-gh-*` or a known internal set are marked `is_external: false`; all others are `is_external: true`. The summary output lists external contributors separately — use this to attribute contributions without needing to look up GitHub profiles.

**Script categories** (by label priority: `breaking` > `feature` > `bugfix` > other):

| Label | Script Category | | ----------------------------------- | -------------------- | | `change:breaking` | **Breaking Changes** | | `change:feature` | **New Features** | | `change:bugfix` | **Bug Fixes** | | `impact:users` or unrecognized `change:*` labels | **Other Changes** |

PRs with no `impact:*` or `change:*` labels are flagged as **unlabeled** for user review.

Note: `change:*` labels are typically required by release labeling conventions. The "Other Changes" fallback is a defensive catch-all for `impact:users` PRs and non-standard `change:*` values not covered by `breaking`/`feature`/`bugfix`.

**Important:** These script categories are intermediate groupings for triage. The website changelog does **not** have a "Breaking Changes" or "New Features" section. All entries are mapped into the three website tiers below. Breaking changes, deprecations, and removals fold into Notable Changes or Other Changes with appropriate emojis (see Step 6).

Map into three website tiers:

• **Highlights** (optional — omit entirely when no PRs qualify): Only 0–4 items per release. Reserve for truly major user-facing additions: entirely new capabilities (e.g., a new widget-to-URL-params system, dynamic container control), significant new API parameters that unlock new workflows, or major breaking changes. Incremental improvements, new config options, and additional parameters on existing commands belong in Notable Changes, not Highlights. Some releases (e.g., patch releases) have no Highlights section at all.
• **Notable Changes**: Remaining features, impactful improvements, new parameters, breaking changes not promoted to Highlights
• **Other Changes**: Bug fixes, docs, chores, minor improvements

Step 5: Present classification for review

**Before generating final output**, present a summary to the user:

1. Total PR count and count per category 2. List of PRs proposed for "Highlights" tier — allow user to promote/demote 3. Any unlabeled PRs flagged in Step 3, with suggested classifications 4. For borderline Highlights candidates, consider linked issue 👍 counts from `related_issues` as one prioritization signal (not the only signal) 5. External contributors identified by the script (from the `is_external` field) — verify any edge cases but no need to look up GitHub profiles for `sfc-gh-*` or known internal authors 6. Ask the user to confirm or adjust before proceeding

Note: Internal-only feature PRs (e.g., e2e infra, CI workflows, agent skills) are already excluded by the categorize script. You should not need to manually filter these.

Do NOT proceed to Step 6 until the user confirms.

Step 6: Read PR descriptions and generate output

For each user-facing PR in `work-tmp/pr-categorized.json`, read its `body` field before writing the changelog entry. Use the PR description as the primary source of truth for what actually changed — the title alone can be imprecise. Focus on the opening summary paragraph(s) of the body; ignore che