Changelog

[afharvey]

There should be a change log.

Written by humans for humans.

However, the formatting and style is important. It needs to be coherent and easily grok'd.

There maybe a consideration for AI comprehension also but humans are first.

Best In Class K8s Component Changelog.md

[afharvey]

Best In Class K8s Component Changelog

Created at 2026-02-04 15:07:46 UTC

@ 2026-02-04 15:07:47 UTC

I'm working on a "best in class" k8s component which is open source.

Do some research and help me consider how to make the best possible change log.

Thinking

The user is working on an open-source Kubernetes component and wants to create a "best in class" changelog. Let me synthesize the research information to provide comprehensive guidance.

Key points from the research:

1. Keep a Changelog format is widely recommended
2. Write for humans, not machines
3. Don't automate from commits - curate it
4. Group changes by category (Added, Changed, Fixed, etc.)
5. Link to issues/PRs for more context
6. Understand your audience
7. Use consistent format
8. Don't mention internal refactors that users don't care about

For a Kubernetes component specifically, I should also consider:

• Kubernetes version compatibility
• API deprecations/removals (following k8s patterns)
• Breaking changes need clear communication

Let me provide a comprehensive answer with best practices for creating an excellent changelog.

Creating a Best-in-Class Changelog for Your K8s Component

For an open-source Kubernetes component, a well-crafted changelog is essential for building trust, managing user expectations, and encouraging adoption ¹. Here's how to make yours stand out:

Follow the Keep a Changelog Format

The Keep a Changelog format is the widely recommended standard ²¹. It's human-readable, structured, and tool-friendly. The core principle: changelogs must be written by humans and for humans ³.

Standard Categories

Group your changes under these headers for easy scanning ²:

Category	Use For
Added	New features
Changed	Changes to existing functionality
Deprecated	Features marked for future removal
Removed	Features removed in this release
Fixed	Bug fixes
Security	Vulnerability patches

Key Best Practices

1. Curate, don't automate — Don't auto-generate from commit messages. This dilutes the changelog with internal refactors and noise that users don't care about ⁴.

2. Link to issues and PRs — For open-source projects, linking to relevant GitHub issues, pull requests, or commits gives readers easy access to detailed context ⁵.

3. Know your audience — K8s operators care about:

   • Breaking changes and migration paths
   • Kubernetes version compatibility ⁶
   • API deprecations (follow the Kubernetes deprecation policy pattern) ⁷
   • Helm chart changes (if applicable)

4. Highlight breaking changes prominently — Use a ⚠️ BREAKING prefix or dedicated section. K8s users especially need to know about API removals or flag changes ⁷⁸.

5. Include version compatibility — State which Kubernetes versions your component supports in each release.

Example Structure

# 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.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

## [1.5.0] - 2026-02-01

### Added
- Support for Kubernetes 1.29 ([#234](link))
- New `--enable-metrics` flag for Prometheus integration ([#228](link))

### Changed
- ⚠️ **BREAKING:** Minimum supported Kubernetes version is now 1.27
- Improved reconciliation performance by 40% ([#230](link))

### Deprecated
- The `v1alpha1` API will be removed in v2.0.0; migrate to `v1beta1`

### Fixed
- Fixed memory leak in controller when handling large ConfigMaps ([#225](link))

### Security
- Updated Go to 1.22.1 to address CVE-2024-XXXXX

## [1.4.2] - 2026-01-15
...

Additional Recommendations for K8s Projects

• Maintain an Unreleased section for upcoming changes
• Use Semantic Versioning — critical for operators managing upgrades
• Consider a dedicated upgrade guide for major versions with breaking changes
• Publish your changelog — tools like Openchangelog can turn your CHANGELOG.md into a browsable website ²

A thoughtfully maintained changelog signals project maturity and makes your component much easier to adopt and upgrade confidently.

References:

@ 2026-02-04 15:09:18 UTC

I agree with changelogs by humans for humans.

However I like the idea that the formatting is perfect. this makes it readable and coherent.

Second, I think it's important AI tools could comprehend the changelog

Thinking

The user wants two things:

1. Perfect, consistent formatting for human readability
2. AI/machine comprehensibility

This is a great insight - the changelog should serve both humans AND machines/AI tools. Let me synthesize the research to address both needs.

Key findings from the research:

1. structured-changelog (citation 14, 20, 21, 26) - This is exactly what they need! It uses JSON as the source of truth and generates deterministic Markdown. It also has TOON format for token reduction when working with AI.
2. mdformat (citation 4) - CommonMark compliant formatter for consistent styling
3. flowmark (citation 5) - Markdown formatter designed for "better LLM workflows"
4. changelog-cli (citation 6) - YAML schema that generates markdown
5. Common Changelog (citation 24) - Stricter subset of Keep a Changelog

The structured-changelog project seems perfect for their use case - it maintains JSON as source of truth (machine-readable) while generating clean markdown (human-readable).

I should outline:

1. The dual-format approach (JSON source of truth + Markdown output)
2. Tools for consistent formatting
3. How to make it AI-friendly

Dual-Purpose Changelogs: Human-Readable & Machine-Parseable

You've identified a key insight: the best changelogs serve both humans and AI tools. Here's how to achieve perfect formatting while maintaining machine comprehensibility.

The Structured Approach: JSON as Source of Truth

Structured Changelog is designed exactly for this use case. It provides a machine-readable JSON Intermediate Representation (IR) as the source of truth, with deterministic Markdown generation for human readability ²⁴.

Key Features

Capability	Benefit
JSON schema	Machine/AI parsing without regex hacks
Deterministic ordering	Consistent output every time
Security metadata	CVE, GHSA, CVSS, CWE, SARIF fields
SBOM fields	Component, version, license tracking
TOON format	~8x token reduction for AI workflows 4

This approach solves the long-standing issue raised in the Keep a Changelog community: rather than trying to parse Markdown, store it in a real data format and generate the human-readable version ¹.

Recommended Architecture

changelog.json (source of truth)
       │
       ├──► CHANGELOG.md (human-readable, generated)
       │
       └──► API/AI consumption (direct JSON access)

Example JSON Structure

{
  "releases": [
    {
      "version": "1.5.0",
      "date": "2026-02-01",
      "changes": {
        "added": [
          {
            "description": "Support for Kubernetes 1.29",
            "pr": 234,
            "breaking": false
          }
        ],
        "security": [
          {
            "description": "Updated Go to 1.22.1",
            "cve": "CVE-2024-XXXXX",
            "severity": "high"
          }
        ]
      },
      "kubernetes_compatibility": {
        "min": "1.27",
        "max": "1.29"
      }
    }
  ]
}

Formatting Tools for Consistency

For ensuring the generated Markdown is always perfectly formatted:

Tool	Purpose
mdformat	CommonMark-compliant opinionated formatter 8
Flowmark	Designed specifically for better LLM workflows and clean git diffs 3
Towncrier	Fragment-based changelog generation with consistent Keep a Changelog output 5

Making It AI-Friendly

Beyond structured data, consider these practices for AI consumption:

1. Serve Markdown directly — When AI agents request your docs with Accept: text/markdown, respond with Markdown instead of HTML. This means fewer tokens and easier parsing ⁷.

2. Use consistent semantic patterns — AI models parse patterns well:

   • ### Added vs ## New Features — stick to one convention
   • ⚠️ BREAKING: prefix consistently for breaking changes
   • ISO 8601 dates (2026-02-01) for unambiguous parsing

3. Include machine-friendly metadata — In your repo, provide:

   • changelog.json for direct consumption
   • JSON Schema file for validation
   • Clear versioning following SemVer

4. Consider a /changelog.json endpoint — If your project has a website or API, expose the structured data directly for tools and AI agents.

Practical Workflow

# 1. Edit source of truth
vim changelog.json

# 2. Validate against schema
structured-changelog validate

# 3. Generate formatted markdown
structured-changelog generate > CHANGELOG.md

# 4. Format for consistency (optional extra pass)
mdformat CHANGELOG.md

This gives you human-curated content (you write the descriptions), perfect formatting (deterministic generation), and AI comprehensibility (structured JSON source).

References:

---

Generated by Kagi Assistant

Footnotes

1. Enhance Project Docs: CHANGELOG & CONTRIBUTING Guides ↩ ↩² ↩³

2. Turn your GitHub Changelog into a dedicated Website ↩ ↩² ↩³ ↩⁴

3. Write changelogs for humans. A style guide. ↩ ↩²

4. What are some good practices for writing changelogs ... ↩ ↩² ↩³

5. Everything you need to know about CHANGELOG.md ↩ ↩²

6. Upgrading Kubernetes Versions: Best Practices and ... ↩

7. Kubernetes Removals and Deprecations In 1.24 | Kubernetes ↩ ↩² ↩³

8. Kubernetes Removals and Major Changes In v1.27 | Kubernetes ↩ ↩²

[jonatanblue]

Half of this is done in #69 (setting up CHANGELOG.md, making it mandatory to update before release), but the machine-readable part is still outstanding. Maybe something we handle later?

[afharvey]

Half of this is done in #69 (setting up CHANGELOG.md, making it mandatory to update before release), but the machine-readable part is still outstanding. Maybe something we handle later?

#77 yeah 🤖 later