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

Relationship to Keep a Changelog

Keep a Changelog is the de-facto standard for human-readable changelogs. Structured Changelog builds on that foundation:

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

What Keep a Changelog defines:

• Section structure (## [Unreleased], ## [1.0.0] - YYYY-MM-DD)
• Categories (Added, Changed, Deprecated, Removed, Fixed, Security)
• Semantic versioning and date formatting

What Structured Changelog adds:

• JSON schema for machine parsing
• Deterministic ordering rules
• Security fields (CVE, GHSA, severity, CVSS, CWE, SARIF)
• SBOM fields (component, version, license)
• CLI and Go library for automation

The generated CHANGELOG.md conforms to Keep a Changelog 1.1.0 formatting conventions.

Installation

Homebrew (macOS/Linux)

brew tap grokify/tap
brew install structured-changelog

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

Go Install

go install github.com/grokify/structured-changelog/cmd/sclog@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:

sclog validate CHANGELOG.json

Generate Markdown:

# Output to stdout
sclog generate CHANGELOG.json

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

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

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

Show version:

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

sclog parse-commits --since=v0.3.0           # Structured git history (TOON)
sclog parse-commits --since=v0.3.0 --format=json  # JSON output
sclog parse-commits --since=v0.3.0 --changelog=CHANGELOG.json  # Mark external contributors
sclog suggest-category "feat: ..."           # Category suggestions
sclog 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)
sclog 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
sclog validate --min-tier core

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

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

# Generate: include everything up to extended
sclog 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/sclog/          # 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.