structured-changelog

Structured Changelog

A canonical, deterministic changelog framework with JSON IR and Markdown rendering.

Structured Changelog provides a machine-readable JSON Intermediate Representation (IR) as the source of truth for your changelog, with deterministic Markdown generation for human readability. It supports optional security metadata (CVE, GHSA, SARIF) and SBOM information.

Overview

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  CHANGELOG.json │ ───► │    Renderer     │ ───► │  CHANGELOG.md   │
│  (Canonical IR) │      │ (Deterministic) │      │ (Human-Readable)│
└─────────────────┘      └─────────────────┘      └─────────────────┘

Key Principles

1. JSON IR is canonical — Markdown is derived, not the source of truth
2. Deterministic rendering — Same input always produces identical output
3. Keep a Changelog format — Compatible with keepachangelog.com - github.com/olivierlacan/keep-a-changelog
4. Semantic Versioning — Follows semver.org conventions
5. Extensible metadata — Optional security (CVE/GHSA/SARIF) and SBOM fields
6. Spec + tooling together — Single source of truth for humans and machines

Comparison

Keep a Changelog (the specification)

Keep a Changelog is the de-facto standard for human-readable changelogs. Structured Changelog implements this specification with a machine-readable JSON layer:

Keep a Changelog is the human spec; Structured Changelog is the structured implementation.

The generated CHANGELOG.md conforms to Keep a Changelog 1.1.0 formatting conventions, while adding JSON schema for machine parsing, security fields (CVE/GHSA/CVSS), and SBOM metadata.

Changelog Generation Tools

Several tools generate changelogs from git history. Here's how Structured Changelog differs:

When to use Structured Changelog:

• You need a machine-readable changelog for automation or APIs
• You want deterministic output (same input → identical output)
• You track security vulnerabilities with CVE/GHSA identifiers
• You need SBOM integration for compliance
• You use LLMs for changelog generation

When to use other tools:

• conventional-changelog: You're in a Node.js ecosystem and want automatic version bumping
• git-chglog: You want maximum template customization
• chyle: You need to enrich changelog data from external APIs (Jira, GitHub)
• semverbot: You primarily need automated semantic version tagging

Installation

Homebrew (macOS/Linux)

brew tap grokify/tap
brew install structured-changelog

This installs the schangelog CLI (also available as structured-changelog).

Go Install

go install github.com/grokify/structured-changelog/cmd/schangelog@latest

Go Library

go get github.com/grokify/structured-changelog

Quick Start

Define your changelog in JSON

{
  "ir_version": "1.0",
  "project": "my-project",
  "releases": [
    {
      "version": "1.0.0",
      "date": "2026-01-03",
      "added": [
        { "description": "Initial release with core features" }
      ]
    }
  ]
}

Generate Markdown

package main

import (
    "fmt"
    "os"

    "github.com/grokify/structured-changelog/changelog"
    "github.com/grokify/structured-changelog/renderer"
)

func main() {
    // Load changelog from JSON
    cl, err := changelog.LoadFile("CHANGELOG.json")
    if err != nil {
        panic(err)
    }

    // Render to Markdown
    md := renderer.RenderMarkdown(cl)
    fmt.Println(md)
}

CLI Usage

Validate a changelog:

schangelog validate CHANGELOG.json

Generate Markdown:

# Output to stdout
schangelog generate CHANGELOG.json

# Output to file
schangelog generate CHANGELOG.json -o CHANGELOG.md

# Full output (default: includes commit links and reference linking)
schangelog generate CHANGELOG.json

# Minimal output (no references/metadata/commit links)
schangelog generate CHANGELOG.json --minimal

Show version:

schangelog version

LLM-Assisted Generation

The CLI includes tools optimized for AI-assisted changelog generation. Commands default to TOON format (Token-Oriented Object Notation) for ~8x token reduction:

schangelog parse-commits --since=v0.3.0           # Structured git history (TOON)
schangelog parse-commits --since=v0.3.0 --format=json  # JSON output
schangelog parse-commits --since=v0.3.0 --changelog=CHANGELOG.json  # Mark external contributors
schangelog suggest-category "feat: ..."           # Category suggestions
schangelog validate --format=toon CHANGELOG.json  # Rich error output

See the LLM Guide for prompts and workflows.

Reference Linking

When a repository URL is provided, references (issues, PRs, commits) are automatically linked by default:

# Generate with linked references (default behavior)
schangelog generate CHANGELOG.json

Example output:

- Add OAuth2 support ([#42](https://github.com/example/repo/issues/42), [`abc123d`](https://github.com/example/repo/commit/abc123def))

Supports GitHub and GitLab URL formats.

Author Attribution

External contributors are automatically attributed when an author field is set and maintainers are defined:

{
  "maintainers": ["grokify"],
  "releases": [{
    "added": [{ "description": "New feature", "author": "@contributor" }]
  }]
}

Generates: - New feature by [@contributor](https://github.com/contributor)

Common bots (dependabot, renovate, etc.) are auto-detected and excluded from attribution.

Compact Maintenance Releases

Consecutive maintenance-only releases (dependencies, documentation, build) are automatically grouped:

## Versions 0.71.1 - 0.71.10 (Maintenance)

10 releases: 8 dependency update(s), 2 documentation change(s).

Use --full to disable grouping and show all releases expanded.

JSON IR Schema

Change Types

Structured Changelog supports 20 change types organized into 4 tiers. The core tier contains the standard Keep a Changelog categories, while higher tiers provide extended functionality.

Tiers

Canonical Ordering

The following table shows all change types in canonical order, grouped by purpose:

┌─ OVERVIEW & CRITICAL ─────────────────────────────────────────┐
│  1. Highlights      standard   Release summaries/key takeaways│
│  2. Breaking        standard   Backward-incompatible changes  │
│  3. Upgrade Guide   standard   Migration instructions         │
│  4. Security        core       Vulnerabilities/CVE fixes      │
├─ CORE KACL ───────────────────────────────────────────────────┤
│  5. Added           core       New features                   │
│  6. Changed         core       Modified functionality         │
│  7. Deprecated      core       Future removal warnings        │
│  8. Removed         core       Removed features               │
│  9. Fixed           core       Bug fixes                      │
├─ QUALITY ─────────────────────────────────────────────────────┤
│ 10. Performance     standard   Speed/efficiency improvements  │
│ 11. Dependencies    standard   Dependency updates             │
├─ DEVELOPMENT ─────────────────────────────────────────────────┤
│ 12. Documentation   extended   Docs updates                   │
│ 13. Build           extended   CI/CD and tooling              │
│ 14. Tests           extended   Test additions and coverage    │
├─ OPERATIONS ──────────────────────────────────────────────────┤
│ 15. Infrastructure  optional   Deployment/hosting changes     │
│ 16. Observability   optional   Logging/metrics/tracing        │
│ 17. Compliance      optional   Regulatory updates             │
├─ INTERNAL ────────────────────────────────────────────────────┤
│ 18. Internal        optional   Refactors only (not tests)     │
├─ END MATTER ──────────────────────────────────────────────────┤
│ 19. Known Issues    extended   Caveats and limitations        │
│ 20. Contributors    extended   Acknowledgments                │
└───────────────────────────────────────────────────────────────┘

Tier-Based Filtering

Use tiers to control which change types to include:

# Validate: ensure changelog covers at least core types
schangelog validate --min-tier core

# Validate: require core + standard coverage
schangelog validate --min-tier standard

# Generate: output only core types (KACL-compliant)
schangelog generate --max-tier core

# Generate: include everything up to extended
schangelog generate --max-tier extended

Optional Security Metadata

Entries can include security-specific fields:

{
  "description": "Fix SQL injection vulnerability",
  "cve": "CVE-2026-12345",
  "ghsa": "GHSA-xxxx-xxxx-xxxx",
  "severity": "high"
}

Optional SBOM Metadata

Track component changes with SBOM fields:

{
  "description": "Update dependency",
  "component": "example-lib",
  "version": "2.0.0",
  "license": "MIT"
}

CHANGELOG vs RELEASE_NOTES

Structured Changelog addresses CHANGELOG.md specifically. Understanding the difference between changelogs and release notes is important:

Content Placement Guidelines

Example: Breaking change workflow

In CHANGELOG.json — flag it concisely:

{
  "changed": [
    { "description": "Module renamed to go-opik", "breaking": true }
  ]
}

In RELEASE_NOTES_v0.5.0.md — provide migration details:

## Migration

Update all imports:

​```go
// Before
import opik "github.com/example/old-name"

// After
import opik "github.com/example/go-opik"
​```

When to Use Each

CHANGELOG.md:

• Quick reference for all historical changes
• Automated tooling (version bumps, release automation)
• Scanning to find when a feature was added/removed

RELEASE_NOTES_vX.Y.Z.md:

• Breaking change migration guides with before/after code
• Detailed feature explanations with usage examples
• Dependency change implications
• File-level change lists for major releases

See docsrc/guides/release-notes-guide.md for recommended release notes structure.

Project Structure

structured-changelog/
├── README.md
├── LICENSE
├── go.mod
├── changelog/          # JSON IR structs + validation
│   ├── changelog.go
│   ├── entry.go
│   ├── release.go
│   └── validate.go
├── gitlog/             # Git log parsing for LLM workflows
│   ├── commit.go
│   ├── conventional.go
│   ├── category.go
│   └── parser.go
├── renderer/           # Deterministic Markdown renderer
│   ├── markdown.go
│   └── options.go
├── cmd/schangelog/     # CLI tool (Cobra-based)
│   ├── main.go
│   ├── root.go
│   ├── validate.go
│   ├── generate.go
│   ├── parse_commits.go
│   └── suggest_category.go
├── schema/             # JSON Schema definitions
│   └── changelog-v1.schema.json
├── docsrc/             # Documentation source (MkDocs)
│   ├── index.md
│   ├── specification/
│   ├── guides/
│   ├── prd/
│   └── releases/
├── docs/               # Generated documentation (GitHub Pages)
└── examples/           # Example changelogs
    ├── basic/
    ├── security/
    └── full/

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

License

MIT License - see LICENSE for details.