Update Changelog

Skill: update-changelog

Update CHANGES.md with entries for all issues and PRs in a given GitHub milestone. Each entry references the user-facing issue (not the PR) as the primary link, with the fix PR inline on the same line.

When to Use

• Before a new release, to populate the changelog with all fixed issues
• When new issues are added to an existing milestone and the changelog needs to be refreshed
• To ensure every entry follows the correct format for the changelog

Prerequisites

• gh CLI authenticated (gh auth status)
• Python 3.8+
• scripts/gh.py for GitHub queries, scripts/changelog.py for changelog checks (run python3 scripts/changelog.py <command> --help for usage)

Workflow

1. Determine the target version

The version is typically a semver string like 2.15.3. Confirm with the user if not specified.

2. Fetch all issues in the milestone

# All closed issues (default)
python3 scripts/gh.py issues "2.16.0"

# Include open issues too
python3 scripts/gh.py issues "2.16.0" --state all

# Exclude entries that should not go in the changelog
python3 scripts/gh.py issues "2.16.0" --exclude "release blocker,no changelog"

Exclusion rules (issue-level):

• no changelog label — chore/refactor work, no entry needed
• release blocker label — blocked issues not yet ready for changelog
• Task issue type — internal chores, not user-facing; excluded by gh.py (use --include-tasks to override)
• Rejected project status — issues with "Rejected" status on the "Main" project board are excluded by gh.py (use --include-rejected to override). This status is independent of the GitHub issue state.

Exclusion rules (PR-level): PRs with these labels stay out regardless of their linked issue's labels: release blocker, no issue required.

Each entry carries number, title, state, issue_type, labels, closing_prs, and project_status.

3. Identify missing entries (optional)

python3 scripts/gh.py issues "2.16.0" --exclude "release blocker,no changelog" --compare CHANGES.md

Returns only milestone issues not yet referenced in the changelog. Note: it compares issues only. For unreferenced merged PRs, use the cross-reference in step 8.

4. Fetch additional PR details when needed

# One or more PR numbers (also: --file prs.txt, or --stdin)
python3 scripts/gh.py prs 9179 9204 9311

# All merged PRs in a milestone (default); --state all/open/closed for others
python3 scripts/gh.py prs --milestone "2.16.0"

Returns number, title, body, state, merged_at, author, labels, and closing_issues. Milestone mode uses paginated GraphQL (100 per page).

5. Categorize entries — strictly by issue type, never by labels or emoji

Use the Issue Type field (issue_type in the gh.py output). No separate query is needed.

⚠️ CRITICAL: Never use labels or title emoji prefixes for categorization. Labels like bug/enhancement and prefixes like :bug:/:sparkles: are often wrong or missing. issue_type is the single source of truth.

Breaking changes override everything: an issue with the breaking change label goes under ### :boom: Breaking changes & Deprecations, no matter its issue type. This and release highlight below are the only label-based rules — explicit exceptions to the "never by labels" principle above. The :boom: subsection goes first in the version, before :rocket: (matching the existing precedent).

Highlights come from the release highlight label: an issue with that label also gets an entry under ### :rocket: Epics and highlights, on top of its regular entry (usually :sparkles:). In the section being refreshed, :rocket: lists exactly the labelled issues: never pick highlights yourself and never keep an unlabelled entry there. Product decides the highlights by labelling issues on GitHub, so a regeneration cannot undo that choice. Older version sections are left as they are.

Community attribution: if the issue or its fix PR has the community contribution label, add (by @<github_username>) on the entry line, before the issue/PR references. Use the PR author (the author field from step 4), not the issue author:

- Fix description of the bug (by @username) [#<ISSUE>](...) (PR: [#<PR>](...))

Only closed issues are included, even if open ones are tracked in the milestone.

Pairing rules:

False-positive associations: a PR may wrongly claim to close an issue from another context (ancient PR, cross-project reference). If titles are clearly unrelated or the PR predates the issue by years, treat it as a data glitch and skip it.

5a. Verify PR merge status before writing

A closed issue may list closing PRs that were closed without merging (e.g. a superseded community PR). Only merged PRs go in the changelog:

python3 scripts/changelog.py check-merged <ALL_PR_NUMBERS>
# also accepts: --file prs.txt, or numbers via --stdin

If a closing PR is closed-unmerged, find the merged PR that superseded it (other PRs in the issue's closing list, similar titles, or pointers in the closed PR's timeline) and reference that one instead.

5b. Security advisory (GHSA) entries

Advisories fixed in a release go in the changelog even though they are neither milestone issues nor PRs. The GHSA ID and description come from the user or the release notes — never from the milestone fetch.

- Fix <user-facing description> (https://github.com/penpot/penpot/security/advisories/GHSA-XXXX-XXXX-XXXX)

Rules: place under ### :bug: Bugs fixed with no issue or PR link; do not fetch or verify the URL (it may be draft/unpublished and 404); write the description in imperative mood from the advisory title. These entries are invisible to the automation — add them by hand, and in step 9 apply only the backport/duplicate check to them.

6. Read the current CHANGES.md and run pre-flight checks

Newest version goes at the top, right after the # CHANGELOG header:

## <VERSION>

### :boom: Breaking changes & Deprecations

- <breaking change or deprecation> [#<ISSUE>](https://github.com/penpot/penpot/issues/<ISSUE>) (PR: [#<PR>](https://github.com/penpot/penpot/pull/<PR>))

### :bug: Bugs fixed

- Fix description of the bug [#<ISSUE>](https://github.com/penpot/penpot/issues/<ISSUE>) (PR: [#<PR>](https://github.com/penpot/penpot/pull/<PR>))
- Fix another bug (by @contributor) [#<ISSUE>](https://github.com/penpot/penpot/issues/<ISSUE>) (PR: [#<PR>](https://github.com/penpot/penpot/pull/<PR>))

### :sparkles: New features & Enhancements

- Add new feature description [#<ISSUE>](https://github.com/penpot/penpot/issues/<ISSUE>) (PR: [#<PR>](https://github.com/penpot/penpot/pull/<PR>))

Format details: entries start with - plus a short imperative description; PR refs stay inline ((PR: [#<N>](<url>)), comma-separated for several); (by @<username>) goes before the issue link; only include non-empty sections; blank line between a section's last entry and the next title; never duplicate an entry from an earlier version section (the earlier version wins for backports).

Pre-flight checks — fix violations directly in CHANGES.md before writing the new section. Reconcile every existing entry (any version section) and every milestone candidate against the current milestone state (re-fetch, do not trust cached data):

1. Duplicate across versions → remove from the current section.
2. Stale milestone assignment (issue moved out of this milestone) → remove the entry (or drop it if the section does not exist yet).
3. Newly applied exclusion labels (no changelog, release blocker) → remove the entry.
4. Issue no longer closed/deleted/Rejected → remove the entry.
5. Unmerged or moved PR reference → fix the reference or remove the entry (a PR merged in a different milestone is a step-9 anomaly, do not silently remove it).
6. Issue type changed to Task → remove the entry.
7. Breaking change misplaced (issue has the breaking change label but sits in another section) → move the entry to :boom:.
8. Highlight out of sync (:rocket: entry without the release highlight label, or a labelled issue missing from :rocket:) → remove the :rocket: entry or add it (step 7b). The regular entry stays.
9. Missing valid issues (closed, non-excluded, unreferenced anywhere) → add them to the current section per step 5.