Changelog Maintenance Workflow
A real changelog, auto-generated, SemVer-accurate, customer-readable — not a graveyard of 'bug fixes and improvements'.
Your CHANGELOG.md is 80% stale. You haven't tagged a SemVer release in 4 months. Customers asking 'what's new in v2.4?' get redirected to the blog (which is also stale). Your API docs reference endpoints that were renamed. Internal engineers can't tell which features are in staging vs prod without running `git log`.
AI CTO owns your changelog + SemVer tagging as a continuous workflow. Every merge to main gets classified (patch/minor/major), auto-drafts a CHANGELOG entry in customer voice, runs `git tag` on appropriate version bumps, pushes release to GitHub Releases with notes, syncs to your public /changelog page, and updates the API docs header versions. Zero manual changelog editing.
How it runs
- 1Classify every merge
GitHub webhook fires on merge to main. AI CTO reads PR title, body, file diff, and Linear link to classify: MAJOR (breaking change), MINOR (new feature, backward-compatible), PATCH (bug fix or internal-only). Classifications surface in the PR comment for human override.
- 2Draft the changelog entry
Entry gets written in Keep-a-Changelog format: ### Added/Changed/Deprecated/Removed/Fixed/Security. Customer voice, not commit messages. 'Fixed typo in login page' becomes 'Fixed: form validation error on the sign-in page'. Internal changes (infra, tests, CI) skip this step.
- 3Batch into releases
Entries accumulate in [Unreleased] section. AI CTO suggests a release cadence based on volume and severity: daily if high-velocity SaaS, weekly if enterprise, monthly if stable platform. You set the rhythm once; it runs automatically.
- 4SemVer bump on release
On release cut, AI CTO bumps the version correctly: any MAJOR entry → major bump, any MINOR → minor bump, otherwise patch. Runs `git tag vX.Y.Z`, pushes tag, creates GitHub Release with the changelog section as the release notes body.
- 5Sync to public changelog page
Public-facing /changelog page (Mintlify, Hashnode, or custom) pulls from the CHANGELOG.md or GitHub Releases API on build. Each entry gets a permalink, RSS feed entry, and anchor-friendly heading. Search-indexed so customers can find 'when did you ship CSV export?'.
- 6Update API docs versions
For API products, the docs (Mintlify, ReadMe, Redocly) auto-update with the new version number, deprecation notices for any removed endpoints, and a version-picker so customers on older versions still see their docs. Prevents the 'docs are ahead of what's deployed' failure mode.
- 7Notify downstream consumers
For breaking changes specifically: email to customers using the deprecated feature (identified by API telemetry), Slack/Discord post, blog post if big enough. Changes that customers should act on get explicit notification; changes they don't care about stay quiet.
Who runs it
What you get
- ✓CHANGELOG.md stays current with zero manual editing
- ✓SemVer versioning accurate (no more major-bumps labeled as patches)
- ✓Customer-readable entries, not copy-pasted commit messages
- ✓GitHub Releases published consistently
- ✓Public /changelog page stays in sync
- ✓API docs reflect deployed reality, not yesterday's state
- ✓Breaking changes get proactive notification, not surprise tickets
Frequently asked questions
How does it know what's 'breaking' vs 'backward-compatible'?
AI CTO runs a diff-based classifier. For API changes: removed endpoint = breaking, required field added to request = breaking, optional field added to response = non-breaking. For SDK changes: removed public method = breaking, new method added = non-breaking. For behavior changes: a default value changing is treated as breaking unless marked otherwise. When uncertain, it flags the PR as 'needs human classification' rather than guessing. Most teams find 90%+ accuracy after 2 weeks of seeing the team's conventions.
We use trunk-based development with feature flags. Releases aren't tied to code merges. Does this still work?
Yes, and actually better than for release-tied teams. AI CTO distinguishes 'shipped code' (merged) from 'shipped feature' (flag enabled for general users). The changelog entry gets drafted at merge but doesn't go live until the flag is enabled for >50% of users (or your threshold). For feature-flag-heavy teams, the changelog ends up reflecting actual customer experience, not 'we put code behind a flag 3 months ago and nobody saw it'.
Our customers are developers who want the dev-jargon commit messages, not marketing copy. Do they have to take the rewritten version?
No. The pipeline generates two versions: customer.md (rewritten, in brand voice) and technical.md (with PR links, contributors, file changes). Your /changelog page renders the customer version by default with a 'Technical details' expand that shows the PR. Open-source projects often invert this — technical is default, with a simplified summary at the top. Both live in sync.
What happens when we ship a hotfix at 2am — does it wait for business hours?
Hotfixes run the full pipeline immediately but differently. Security-flagged PRs trigger an immediate release + announcement (status page, email to affected customers, Discord). Non-security hotfixes go out immediately but skip the marketing-side notifications (no blog post, no social). AI CTO distinguishes based on PR labels — you tag the PR hotfix or security, and the pipeline adapts. Over-communication of bug fixes is almost as bad as under-communication of features.
We have 12 microservices with separate versioning. Does it handle poly-repo?
Yes. Each repo has its own CHANGELOG.md, tags, and GitHub Releases. The public-facing /changelog aggregates across repos with service-level filtering ('show me only changes to the API service'). AI CTO understands which repo maps to which customer-visible surface and routes accordingly. For internal services (no customer surface), the workflow still runs for internal observability but doesn't publish externally.
Related resources
AI CTO | Hire Your AI CTO Today
Hire an AI CTO that owns product direction, code review, infra decisions, and ships features. Direct by chat. For founders who aren't engineers.
AI Head of Content | Hire Your AI Content Lead
Hire an AI Head of Content that owns long-form, newsletter, social, and video briefs. Direct by chat. Ships weekly, stays on voice.
Release Notes on Autopilot | Tycoon Workflows
Every ship turned into customer-readable release notes — in-app, email, changelog page, Twitter — without a writer in the loop.
API Docs Maintenance on Autopilot | Tycoon Workflows
OpenAPI spec auto-generated from code, docs pages synced on every deploy, code samples tested continuously — docs that never lie.
GitHub Issue Triage on Autopilot | Tycoon Workflows
Inbound issues labeled, prioritized, deduped, and routed — maintainer wakes up to a clean backlog, not 47 new issues.
Internal Weekly Digest on Autopilot | Tycoon Workflows
Every Friday, the whole team gets one digest: what shipped, what moved, who did what — without anyone writing it.
Run your one-person company.
Hire your AI team in 30 seconds. Start for free.
Free to start · No credit card required · Set up in 30 seconds