| 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, labels, author, related_issues, related_issues_truncated} objects sorted by PR number.
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:
- Total PR count and count per category
- List of PRs proposed for "Highlights" tier โ allow user to promote/demote
- Any unlabeled PRs flagged in Step 3, with suggested classifications
- For borderline Highlights candidates, consider linked issue ๐ counts from
related_issues as one prioritization signal (not the only signal)
- 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
- 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: Rewrite descriptions and generate output
Generate the file in the work-tmp/ directory: work-tmp/changelog-website-<new-tag>.md
Entry writing style by category
- Highlights: Announcing tone โ "Introducing...", "Announcing...". PR links may be included or omitted at your discretion.
- Features / new parameters (Notable Changes): User-perspective voice โ "You can now...", "
st.foo has a new bar parameter to...", "st.foo supports..."
- Bug fixes: Always prefixed with "Bug fix:" โ "Bug fix:
st.spinner avoids a race condition..."
- Deprecations/removals: Plain description with specific emojis (see emoji list below).
- Other non-bug entries: Plain present-tense descriptions, no prefix.
Formatting rules
Output structure
## **Version <new-tag>**
_Release date: <Month Day, Year>_
**Highlights**
- ๐ฟ Introducing [`st.new_thing`](/develop/api-reference/widgets/st.new_thing) โ a widget that lets you do something amazing ([#14200](https://github.com/streamlit/streamlit/pull/14200)).
**Notable Changes**
- ๐ [`st.dataframe`](/develop/api-reference/data/st.dataframe) has a new `selection_mode` parameter that lets you configure row and column selection behavior ([#14139](https://github.com/streamlit/streamlit/pull/14139), [#9836](https://github.com/streamlit/streamlit/issues/9836)).
- โ ๏ธ `st.legacy_thing` is deprecated and will be removed in a future version. Use `st.new_thing` instead ([#14050](https://github.com/streamlit/streamlit/pull/14050)).
- ๐ App menu redesign:
- New "Settings" option in the app menu ([#14100](https://github.com/streamlit/streamlit/pull/14100)).
- Reorganized menu items for better discoverability ([#14101](https://github.com/streamlit/streamlit/pull/14101)).
**Other Changes**
- ๐ Bug fix: `st.spinner` avoids a race condition when used right before a cache miss ([#13849](https://github.com/streamlit/streamlit/pull/13849), [#13634](https://github.com/streamlit/streamlit/issues/13634)).
- ๐ฆ Bug fix: `st.number_input` no longer resets to default when the step value changes ([#14125](https://github.com/streamlit/streamlit/pull/14125)). Thanks, [contributor](https://github.com/contributor)!
- ๐ชฒ Bug fix: Fixed a layout shift in `st.columns` when using `gap="small"` ([#14080](https://github.com/streamlit/streamlit/pull/14080)).
When the release has no Highlights, omit that section entirely (do not include an empty Highlights header).
Step 7: Final summary
After writing the file, print:
- File path for the generated changelog
- PR counts per category
- Reminder to review the file before publishing
Key references
.github/release.yml โ canonical label-to-category mapping (also used for auto-generated GitHub release notes)- Website changelog format reference:
https://docs.streamlit.io/develop/quick-reference/release-notes
- Example docs markdown file (style inspiration):
https://raw.githubusercontent.com/streamlit/docs/997b19a5eda68b72ce091d69be9d6921a37e3da0/content/develop/quick-references/release-notes/2026.md
