changelog-cleanup

name	changelog-cleanup
description	Analyze and clean up the Upcoming Release section in CHANGELOG.md. Reviews each entry for grammar and logic issues, then sorts entries into named sections (New features, Changes, Bugfixes, Dependencies, Internal for non-customer-facing work, and Other as needed). Use when the user mentions changelog cleanup, changelog sorting, release notes review, or preparing a release.

Changelog Cleanup

Cleans up the ## Upcoming Release section of CHANGELOG.md in two phases: grammar/logic review, then sorting into named sections.

Changelog structure

Each release is a ## heading (e.g., ## Upcoming Release, ## 2.3.6). Within a release, entries are organized under named sections — plain-text labels followed by a colon, each followed by a blank line and then bullet entries. For ## Upcoming Release, use the section order defined in Phase 2 below. Older releases may use different section names (e.g., Deprecations:, Breaking changes:, Performance:) or the legacy flat list.

Example structure:

## 2.3.6

New features:

- Entry one

Changes:

- Entry two

Bugfixes:

- Entry three
- Entry four

Dependencies:

- Entry five

Internal:

- Entry visible only in Snowflake-internal or non-customer contexts (see below)

Older releases (before 2.3.6) use a legacy flat list of bullets with no named sections. That format is no longer valid for new releases.

Phase 1: Grammar and Logic Review

1. Read CHANGELOG.md and extract all content under ## Upcoming Release (stop at the next ## heading).
2. For each entry, check for:
   • Spelling and grammar mistakes
   • Unclear or ambiguous phrasing
   • Logical issues (e.g., an entry starting with "Fixed" that actually describes a new feature, or contradictory statements)
   • Entries placed under the wrong section (e.g., a bug fix listed under "New features:", or a customer-visible change under Internal:)
3. When an issue is found, use the AskQuestion tool to present the proposed fix to the user. Provide two options: "Accept" and "Reject". Batch related fixes into a single AskQuestion call when possible to reduce round-trips, but keep each fix clearly labeled.
4. Apply only accepted fixes. Do not modify entries the user rejects.

Phase 2: Sort Entries into Sections

After grammar/logic fixes are applied, sort entries into named sections. The five sections below are the defaults, but you may rename, split, or combine them when it makes the release easier for an end-user to scan — for example, Bugfixes and Performance: instead of a single Bugfixes: bucket. When proposing custom section names, use the AskQuestion tool to confirm them with the user.

Default sections, in this order:

Section 1 — New features:

Entries that semantically describe something new (e.g. Added), regardless of the leading verb.

Section 2 — Changes:

Entries that describe enhancing, changing, updating, removing, refactoring, or modifying existing behavior (e.g. Improved, Changed, Updated, Removed, Replaced), regardless of the leading verb. Dependency bumps belong in Dependencies: (see Section 4), not here.

Section 3 — Bugfixes:

Entries that semantically describe fixing incorrect behavior (e.g. Fixed), regardless of the leading verb.

Section 4 — Dependencies:

Customer-visible dependency changes: bumps (e.g. Bumped axios to ...), removals, replacements, or pins of third-party packages that ship to customers. Include CVE-driven bumps here. Omit this section if the release has no dependency changes.

Internal-only dependency or tooling changes (e.g. dev-dependency bumps, CI tooling) belong in Internal: instead.

Section 5 — Internal:

Entries that do not affect end customers in any meaningful way: no change to public API, connection options, query behavior, error handling, packaging, or documented runtime for typical self-hosted or customer Snowflake workloads.

Use Internal: for Snowflake-internal execution contexts (e.g. driver behavior only when running inside SPCS or similar), internal-only request fields or telemetry that customers do not configure or observe, CI/release automation, or repo hygiene with zero customer-visible impact.

Do not put here: dependency bumps that address CVEs or change shipped binaries for customers, fixes to connection/auth/query bugs, or any feature a customer could rely on outside Snowflake-managed environments.

Example (from this repo’s changelog):

Internal:

- Included `spcs_token` when driver runs inside SPCS (org/repo#1372)

Section 6 — Other (custom name)

If there are entries that don't fit the five default sections above, or if the release would be clearer with different groupings (e.g., merging Bugfixes: and a perf cluster into Bugfixes and Performance:), use the AskQuestion tool to propose custom section names to the user.

Sorting rules

• Use the first word after - as a signal, but override when the meaning clearly fits a different section.
• Multi-line entries (parent + indented sub-bullets) stay as one unit.
• Preserve original relative order within each section.
• Omit sections that have no entries (don't output an empty section heading).
• Each section heading is followed by a blank line, then its bullet entries.
• Separate sections from each other with a blank line after the last bullet.
• Entries must not end with a trailing period. Remove any trailing . from bullet entries for consistency (a trailing (...#1234) reference already has no period after it, so nothing to remove in that case).

Output format

The final output under ## Upcoming Release must use named sections with bullet entries. You may use the default section names or custom ones — whichever makes the release easiest for an end-user to understand at a glance.

Example with default sections:

## Upcoming Release

New features:

- Added support for OAuth tokens
- Added new `timeout` option

Changes:

- Improved error details when OAuth fails
- Changed default `jsonColumnVariantParser` to `JSON.parse`

Bugfixes:

- Fixed a crash when loading config
- Fixed typo in error message

Dependencies:

- Bumped axios to 1.15.1 to address CVE-2025-62718
- Dropped `uuid` dependency in favor of Node built-in `crypto.randomUUID()`

Internal:

- Included `spcs_token` when driver runs inside SPCS (org/repo#1372)

Example with custom sections (e.g., for a patch release):

## Upcoming Release

Bugfixes and Performance:

- Reduced peak memory usage when streaming large result sets
- Fixed a crash when loading config

Dependencies:

- Bumped axios to 1.15.1 to address CVE-2025-62718

Internal:

- Extended login-request telemetry to detect cloud VMs