Changelog Maintenance Workflow

A real changelog, auto-generated, SemVer-accurate, customer-readable — not a graveyard of 'bug fixes and improvements'.

Updated 2026-04-18
Tycoon solution

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

  1. Classify 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.

  2. Draft 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.

  3. Batch 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.

  4. SemVer 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.

  5. Sync 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?'.

  6. Update 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.

  7. Notify 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

  • hire/ai-cto
  • hire/ai-head-of-content

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
FAQ

Frequently asked questions

Clear answers about wallet credit, usage, subscriptions, and how Tycoon charges for work.

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

Market capability

Browse outcome-specific Agents and Teams

Choose only the focused capability your current outcome needs.

Market capability

Content Marketing Team — blog + newsletter + SEO + design

Weekly blog + biweekly newsletter + SEO-optimized publishing + supporting graphics, planned on one calendar with a monthly performance report

Workflow

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.

Workflow

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.

Workflow

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.

Workflow

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.

Stop managing agents. Just describe outcomes.

Tycoon Agent manages all your agents. Set her up in 30 seconds, free.

Free to start · No credit card required · Set up in 30 seconds