---
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:

```markdown
## 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):

```markdown
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:

```markdown
## 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):

```markdown
## 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
```