Release Notes v0.1.0

Release Date: January 3, 2026

Overview

This is the initial release of 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 following the Keep a Changelog format.

Installation

CLI Tool

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

Library

go get github.com/grokify/structured-changelog@v0.1.0

Features

JSON IR Schema (v1.0)

The JSON Intermediate Representation is the canonical source of truth. Key features:

• Keep a Changelog categories: added, changed, deprecated, removed, fixed, security
• Semantic Versioning: Version validation with full semver regex
• Unreleased section: Track work-in-progress changes
• Yanked releases: Mark retracted versions

Example CHANGELOG.json:

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

Security Metadata

Track vulnerability information with optional security fields:

Field	Description	Example
cve	CVE identifier	CVE-2026-12345
ghsa	GitHub Security Advisory	GHSA-abcd-efgh-ijkl
severity	Severity level	critical, high, medium, low
cvss_score	CVSS score (0-10)	8.5
cvss_vector	CVSS vector string	CVSS:3.1/AV:N/AC:L/...
cwe	CWE identifier	CWE-89

Example:

{
  "description": "Fix SQL injection vulnerability",
  "cve": "CVE-2026-12345",
  "ghsa": "GHSA-abcd-efgh-ijkl",
  "severity": "high",
  "cvss_score": 8.5
}

SBOM Metadata

Track component and dependency changes:

Field	Description	Example
component	Component name	golang.org/x/crypto
component_version	Version	0.18.0
license	SPDX identifier	MIT, Apache-2.0

CLI Tool (schangelog)

Cobra-based CLI with subcommands:

Validate a changelog:

schangelog validate CHANGELOG.json

Output:

✓ CHANGELOG.json is valid

Summary:
  Project: my-project
  IR Version: 1.0
  Releases: 5
  Latest: 2.1.0 (2026-01-03)

Generate Markdown:

# To stdout
schangelog generate CHANGELOG.json

# To file
schangelog generate CHANGELOG.json -o CHANGELOG.md

# Minimal (no metadata)
schangelog generate CHANGELOG.json --minimal

# Full (include commits)
schangelog generate CHANGELOG.json --full

Version info:

schangelog version

Go Library

Load and validate:

import "github.com/grokify/structured-changelog/changelog"

cl, err := changelog.LoadFile("CHANGELOG.json")
if err != nil {
    log.Fatal(err)
}

result := cl.Validate()
if !result.Valid {
    for _, e := range result.Errors {
        log.Printf("Error: %s", e.Error())
    }
}

Render to Markdown:

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

md := renderer.RenderMarkdown(cl)

// Or with options
opts := renderer.FullOptions()
md := renderer.RenderMarkdownWithOptions(cl, opts)

Build programmatically:

cl := changelog.New("my-project")

release := changelog.NewRelease("1.0.0", "2026-01-03")
release.AddAdded(changelog.NewEntry("New feature").WithPR("42"))
release.AddFixed(changelog.NewEntry("Bug fix").WithIssue("100"))

cl.AddRelease(release)

Deterministic Rendering

The renderer guarantees identical output for identical input:

• Fixed category order (Added → Changed → Deprecated → Removed → Fixed → Security)
• Preserved entry order within categories
• Consistent whitespace and formatting
• No timestamp-based variations

Validation

Comprehensive validation with detailed error messages:

• Required fields (ir_version, project, version, date, description)
• Semantic version format
• Date format (YYYY-MM-DD)
• CVE format (CVE-YYYY-NNNNN)
• GHSA format (GHSA-xxxx-xxxx-xxxx)
• Severity values (critical, high, medium, low, informational)
• CVSS score range (0-10)
• Duplicate version detection

Rendering Options

Option	Default	Minimal	Full
IncludeReferences	✓	✗	✓
IncludeCommits	✗	✗	✓
IncludeSecurityMetadata	✓	✗	✓
MarkBreakingChanges	✓	✗	✓
IncludeCompareLinks	✓	✗	✓

Project Structure

structured-changelog/
├── changelog/          # IR types + validation
├── renderer/           # Markdown generation
├── cmd/schangelog/          # CLI tool
├── schema/             # JSON Schema
├── docs/               # Specification
└── examples/           # Example changelogs

Documentation

• docs/spec.md - Full IR specification
• docs/security.md - Security metadata guide
• docs/sbom.md - SBOM metadata guide

Examples

Three example changelogs are included:

• examples/basic/ - Simple changelog with common entries
• examples/security/ - Changelog with CVE/GHSA metadata
• examples/full/ - Complex changelog based on real-world usage

Dependencies

• github.com/spf13/cobra v1.10.2 - CLI framework

Known Limitations

• No init command yet (planned for v0.2.0)
• No add command for adding entries (planned for v0.2.0)
• Compare links not yet generated in output

What's Next

Planned for future releases:

• schangelog init - Create empty CHANGELOG.json
• schangelog add --type=fixed "Description" - Add entry to unreleased
• schangelog release 1.2.0 - Promote unreleased to new version
• Compare link generation
• GitHub Actions integration
• MkDocs/Hugo theme support