Changelog Generation

Principles and inputs

Deduplicate: multiple PRs for one feature become one user-facing line. Link issues, PRs, and doc anchors as needed. For multi-package repos, fix whether each package gets its own section or a single root CHANGELOG—state it in the SKILL.

Keep a Changelog sections

Prefer Keep a Changelog English section titles for tooling and community consistency. Within each release block, order by reader value—not merge chronology.

• Added — New capabilities, APIs, user-visible options.
• Changed — Behavior adjustments that stay compatible; user-perceptible performance wins belong here too.
• Deprecated — Still available but slated for removal; note replacements and removal timeline.
• Removed — Public APIs or behaviors deleted in this release.
• Fixed — Bug fixes; pure internal refactors with no behavior change usually skip the public CHANGELOG.
• Security — Security-related fixes (align disclosure policy; not every detail needs a line).

# CHANGELOG.md — Keep a Changelog format example

# Changelog

All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- OAuth2 login support via Google and GitHub providers
- User profile avatar upload (max 5MB, JPEG/PNG)

### Changed
- `/api/users` response now returns paginated results (breaking: see migration guide)

## [1.4.0] - 2026-03-15

### Added
- Dark mode support across all dashboard pages
- CSV export for analytics reports

### Changed
- Upgraded Node.js runtime from 18 to 20

### Fixed
- Cart total rounding error on items with fractional quantities (#234)
- Session token not refreshed after password change (#256)

### Security
- Patched XSS vulnerability in markdown renderer (CVE-2026-1234)

## [1.3.2] - 2026-02-28

### Fixed
- Payment timeout not handled gracefully on slow networks

[Unreleased]: https://github.com/org/repo/compare/v1.4.0...HEAD
[1.4.0]: https://github.com/org/repo/compare/v1.3.2...v1.4.0
[1.3.2]: https://github.com/org/repo/compare/v1.3.1...v1.3.2

SemVer and version numbers

Semantic versioning MAJOR.MINOR.PATCH (optional prerelease and build metadata) should align with “breaking / feature / fix” groupings in the CHANGELOG so agents and release tools share one rule set.

• MAJOR — Incompatible API or behavior changes; CHANGELOG needs BREAKING or Removed-style notes.
• MINOR — Backward-compatible additions; maps to Added (and non-breaking Changed).
• PATCH — Backward-compatible fixes; mainly Fixed / Security when nothing breaks.

If the team uses CalVer or marketing version numbers, document that in the SKILL so agents do not “infer” the next SemVer anyway.

Drafting workflow

From raw commits to publishable text, a fixed order reduces misses and misclassification.

  [ Lock scope: tag / date / commit range ]
                    │
                    ▼
              [ Aggregate PRs / issues: dedupe, add links ]
                    │
                    ▼
         [ Classify into KaC sections + mark BREAKING? ]
                    │
                    ▼
              [ Draft version against SemVer rules ]
                    │
                    ▼
         [ Human polish: tone, migrations, security wording ]
                    │
                    ▼
              [ Diff against automation output: dedupe paragraphs ]

Automation and boundaries

Alongside release-please, semantic-release, changesets, etc., spell out “machine-generated blocks” versus “human-edited blocks”: e.g. titles and dates from CI, bullets from PR templates, agents only rewriting user-facing sentences.

Avoid duplicate narratives for the same release; if tools append commit lists, the SKILL can require “summary sentence + link only, no repeated hashes”.

// semantic-release configuration (.releaserc.json)
{
  "branches": ["main", {"name": "beta", "prerelease": true}],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@semantic-release/changelog", {
      "changelogFile": "CHANGELOG.md"
    }],
    ["@semantic-release/npm", {
      "npmPublish": false
    }],
    ["@semantic-release/git", {
      "assets": ["CHANGELOG.md", "package.json"],
      "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
    }],
    "@semantic-release/github"
  ],
  "releaseRules": [
    {"type": "feat", "release": "minor"},
    {"type": "fix", "release": "patch"},
    {"type": "perf", "release": "patch"},
    {"breaking": true, "release": "major"}
  ]
}

# GitHub Actions workflow: release-please
# .github/workflows/release.yml
name: Release Please
on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: google-github-actions/release-please-action@v4
        with:
          release-type: node
          package-name: my-package
          changelog-types: |
            [
              {"type":"feat","section":"Features"},
              {"type":"fix","section":"Bug Fixes"},
              {"type":"perf","section":"Performance"},
              {"type":"docs","section":"Documentation","hidden":true}
            ]

Section cheat sheet and version bump

Expand the sections below for quick reminders (this page only). Version bumping follows plain MAJOR.MINOR.PATCH without prerelease semantics. All computation runs locally in the browser—nothing is uploaded.