Building Changelog Page

We built the Building Changelog Page skill because writing version history is the one chore every engineer dreads. You're a developer, not a copywriter. You shouldn't spend 45 minutes every release formatting bullets, arguing about whether a bug fix goes under "Fixed" or "Improvements," or manually constructing link references. We automated the structure, the validation, and the generation so you can focus on code. This is a Pro skill that installs a complete workflow: templates, scripts, validators, and references. It turns changelog maintenance from a manual tax into a byproduct of your git history.

The Changelog Tax and the "Git Dump" Trap

You've seen it. The CHANGELOG.md in the root directory is just a copy-paste of git log --oneline or a half-baked list of commits from the last sprint. It's a trap. ^[2] states the guiding principle clearly: "Changelogs are for humans, not machines." When you dump git logs, you're ignoring that principle. You're forcing your users, your support team, and your future self to parse technical commit hashes to figure out what changed. A raw git log is a list of actions; a changelog is a list of impacts. The difference matters.

The friction is real. You have to manually categorize every change. Is this a breaking change? Does it need a deprecation warning? If you're using automating-release-notes, you might be generating release notes for stakeholders, but that's a different audience than the technical changelog. Release notes sell; changelogs document. If you're mixing them or treating them as the same thing, you're creating noise. ^[2] also insists there should be an entry for every single version. The "git dump" approach often skips minor patches or merges them into a wall of text, violating that rule.

^[4] emphasizes that best practices include determining a versioning strategy and date each release. Without a script or a strict template, you're guessing. You end up with inconsistent date formats, missing version headers, and that dreaded "Unreleased" section that sits there for three months because nobody bothered to move it. You're also likely missing categorized change types. Without categories, your changelog is a flat list. With categories, you can scan for "Deprecations" or "Breaking Changes" in seconds. This isn't just about aesthetics; it's about information density. If you're looking for a changelog-pack because you realized your current setup is broken, you'll find that the pain points are identical: manual effort, inconsistent structure, and low user trust.

What a Broken Changelog Costs Your Release Cycle

Let's talk numbers. A standard release cycle might take 45 minutes of formatting and verification. That sounds small until you're shipping 12 times a year. That's 9 hours of lost engineering time per year, just on changelog hygiene. But the cost isn't just time; it's downstream incidents. A messy changelog leads to support tickets. "Did v2.4.1 break the API?" The support agent can't answer because the changelog is a wall of text. They have to ask engineering. Engineering has to dig through commits. That's a 30-minute back-and-forth for a question the changelog should have answered instantly.

^[7] notes that the standard file location is the root directory; if your changelog is buried in /docs or formatted poorly, users won't find it, and the trust erodes. A changelog in the wrong place is a changelog that doesn't exist. ^[8] calls keeping a changelog a best practice developers should follow. Ignoring it isn't just lazy; it's a risk. You lose the audit trail of why things changed. You lose the ability to quickly rollback decisions because you can't see the scope of a commit. When you skip the structure, you pay the tax in support overhead and developer context-switching.

Consider the CI/CD pipeline. If your changelog is generated manually, it's easy to skip. You merge the PR, forget the changelog, and ship. The validator in this skill changes that. You can add scripts/generate-changelog.sh and validators/changelog-validator.sh to your release pipeline. If the changelog structure fails validation, the pipeline fails. You can't merge a release with a broken changelog. This enforces discipline without requiring a manager to micromanage. The script creates backups (CHANGELOG.md.backup.${version}), so you never lose history during generation. You get safety and consistency.

The 3 AM Release Panic: A Hypothetical Illustration

Imagine a platform team shipping a patch to fix a race condition in their auth service. The changelog entry is a single line: "Fixed auth race condition." The next morning, a customer reports an intermittent 401 error on a specific endpoint. The support lead pings the on-call engineer. The engineer checks the changelog and sees "Fixed auth race condition." That's not enough. The engineer has to open the PR, read the diff, check the commit message, and verify if the fix touched the endpoint the customer uses.

If the team had used a structured format like Common Changelog, which is a stricter subset of Keep a Changelog ^[1], the entry would have included the scope, the breaking change flag, and a link to the PR. The engineer would know instantly: "Scope: auth-service. No breaking change. Link to PR #492." The resolution time drops from 20 minutes to 30 seconds. This is the difference between a changelog that documents and a changelog that enables.

^[3] suggests using six standard categories to group changes: Added, Changed, Deprecated, Removed, Fixed, and Security. Without categories, your changelog is a flat list. With categories, you can scan for "Deprecations" or "Breaking Changes" in seconds. This isn't just about aesthetics; it's about information density. ^[3] also highlights implementing effective change logs by starting with a consistent structure. Our skill provides that structure out of the box. The templates/keepachangelog.md template adheres strictly to the Keep a Changelog specification, including the [Unreleased] section, version headers, date formatting, and categorized change types. You don't have to design the format; you just fill it in via conventional commits.

What Changes Once You Lock the Workflow

Once you install this skill, the changelog stops being a chore and becomes a byproduct of your git history. You adopt conventional commits. You run the generation script. The validator runs. scripts/generate-changelog.sh parses your git log using conventional-changelog-cli. It respects the conventionalcommits preset. You pass a version argument, and it outputs a structured CHANGELOG.md with proper date formatting, categorized sections, and link definitions. The script handles the transition from [Unreleased] to the new version, moving entries into the correct categories and updating the link references automatically.

^[6] highlights the importance of conventions for assigning numbers and formatting. Our skill enforces this. The validators/changelog-validator.sh checks the output. It verifies required sections, checks link definitions, and exits non-zero if the structure fails. You can't merge a release with a broken changelog. The validator ensures that every version has a header, every entry has a link reference, and the file structure matches the spec. This is programmatic quality assurance for your documentation.

Even for complex projects like open-source kernels, where versioning can get hairy, a consistent structure helps ^[5]. ^[5] discusses the challenges of version history in kernel projects; the same principles apply to any software. You get a clean, predictable file that users trust. You also get references to the specs. references/keep-a-changelog-spec.md and references/conventional-commits-spec.md are embedded. If a new hire asks, "Why is this a BREAKING CHANGE?", the answer is in the reference file, not in a Slack thread. The skill also includes references/version-utils-python.md, which provides canonical examples for RPM package version parsing, comparison, and integration into cross-platform version checks. If your project uses Python or RPM, you have a ready reference for version utilities without hunting for documentation.

The templates/conventional-changelog-config.js is a real configuration file for conventional-changelog-cli. You don't write regex; you configure the preset. This means you get robust parsing of commit messages, scopes, and breaking changes without maintaining custom parsing logic. The skill is a complete package: orchestrator, templates, config, scripts, validators, references, and examples. examples/worked-example.md shows you exactly what the output looks like for a realistic software project. You can compare your output against the example and spot issues instantly.

What's in the Building Changelog Page Skill

Here's the manifest. This is a multi-file deliverable designed for immediate integration. Every file serves a purpose in the workflow.

• skill.md — Orchestrator guide that defines the changelog workflow, references all package files, and provides step-by-step instructions for generating, validating, and maintaining a structured CHANGELOG.md using conventional commits and Keep a Changelog standards.
• templates/keepachangelog.md — Production-grade CHANGELOG.md template adhering strictly to the Keep a Changelog specification, including [Unreleased] section, version headers, date formatting, and categorized change types.
• templates/conventional-changelog-config.js — Real configuration file for conventional-changelog-cli using the conventionalcommits preset, enabling automated parsing of git history and generation of structured changelog entries.
• scripts/generate-changelog.sh — Executable bash script that automates changelog generation, handles version arguments, creates backups, and integrates with conventional-changelog-cli for seamless updates.
• validators/changelog-validator.sh — Programmatic validator that checks CHANGELOG.md structure, verifies required sections, validates link definitions, and exits non-zero on structural or formatting failures.
• references/keep-a-changelog-spec.md — Canonical reference embedding the full Keep a Changelog specification, including format rules, versioning guidelines, category definitions, and link reference standards.
• references/conventional-commits-spec.md — Canonical reference embedding the Conventional Commits specification, detailing header/body/footer structure, commit types, scopes, breaking changes, and issue reference patterns.
• examples/worked-example.md — Fully realized CHANGELOG.md example demonstrating proper formatting, categorized entries, link references, and version history for a realistic software project.
• references/version-utils-python.md — Reference documentation for the version_utils Python library, providing canonical examples for RPM package version parsing, comparison, and integration into cross-platform version checks.

Stop Guessing. Start Shipping.

You're an engineer. Your job is to build software, not format markdown. We built this skill so you don't have to. Upgrade to Pro to install the Building Changelog Page skill. Generate, validate, and ship structured changelogs that your users actually read. Stop wasting time on manual formatting. Let the scripts and validators do the work. Install the skill, integrate the script into your pipeline, and ship with confidence.