Product Changelog

Product Changelog is an AI skill that automates the generation, formatting, and distribution of product changelogs from commit histories, release notes, and feature specifications. It covers changelog entry generation, semantic categorization, audience-appropriate formatting, multi-channel distribution, and versioned archive management that keep users informed about product evolution.

What Is This?

Overview

Product Changelog provides workflows for creating and maintaining user facing changelogs that communicate product updates clearly. It handles extracting changelog entries from Git commit messages and pull request descriptions, categorizing changes by type such as features, fixes, improvements, and deprecations, formatting entries for different audiences including developers and end users, distributing changelogs through multiple channels like websites, email, and in-app notifications, maintaining versioned changelog archives with proper semantic versioning, and generating release summaries from detailed change lists.

Who Should Use This

This skill serves product managers communicating updates to users and stakeholders, developer relations teams maintaining public API changelogs, engineering teams automating release note generation in CI/CD pipelines, and open source maintainers documenting changes for contributors and users.

Why Use It?

Problems It Solves

Writing changelogs manually after releases is tedious and often delayed or skipped entirely. Technical commit messages are incomprehensible to end users who need to understand what changed. Without categorization, important breaking changes get buried among minor improvements. Distributing updates across multiple channels requires reformatting the same content repeatedly.

Core Highlights

Automated extraction pulls change descriptions from version control metadata. Semantic categorization groups changes into user-meaningful sections. Audience adaptation reformats technical entries into user-friendly language. Multi-channel output generates format-specific versions for each distribution channel.

How to Use It?

Basic Usage

import subprocess
import re
from datetime import datetime

class ChangelogGenerator:
    def __init__(self, repo_path):
        self.repo = repo_path
        self.categories = {
            "feat": "New Features",
            "fix": "Bug Fixes",
            "perf": "Performance",
            "breaking": "Breaking Changes",
            "deprecation": "Deprecations"
        }

    def get_commits_since(self, tag):
        result = subprocess.run(
            ["git", "log", f"{tag}..HEAD",
             "--format=%s|%h|%an"],
            capture_output=True, text=True,
            cwd=self.repo
        )
        commits = []
        for line in result.stdout.strip().split("\n"):
            if "|" in line:
                msg, sha, author = line.split("|")
                commits.append({
                    "message": msg, "sha": sha,
                    "author": author
                })
        return commits

    def categorize(self, commits):
        grouped = {cat: [] for cat in self.categories}
        for commit in commits:
            match = re.match(r"(\w+)[:(]", commit["message"])
            prefix = match.group(1) if match else "other"
            if prefix in grouped:
                grouped[prefix].append(commit)
        return grouped

Real-World Examples

class ChangelogFormatter {
  constructor(version, date, changes) {
    this.version = version;
    this.date = date;
    this.changes = changes;
  }

  toMarkdown() {
    let md = `## ${this.version} (${this.date})\n\n`;
    const order = ["breaking", "feat", "fix", "perf"];
    for (const cat of order) {
      const items = this.changes[cat] || [];
      if (items.length === 0) continue;
      md += `### ${this.categoryLabel(cat)}\n\n`;
      for (const item of items) {
        md += `- ${item.description} (${item.sha})\n`;
      }
      md += "\n";
    }
    return md;
  }

  toUserFacing() {
    const highlights = [
      ...(this.changes.feat || []),
      ...(this.changes.breaking || []),
    ];
    return highlights
      .map((h) => `- ${h.userDescription || h.description}`)
      .join("\n");
  }

  categoryLabel(cat) {
    const labels = {
      breaking: "Breaking Changes",
      feat: "New Features",
      fix: "Bug Fixes",
      perf: "Performance",
    };
    return labels[cat] || cat;
  }
}

Advanced Tips

Always list breaking changes first and in bold to ensure users see them before updating. Maintain separate changelogs for API consumers and end users, as their information needs differ significantly. Include links to migration guides alongside breaking change entries to reduce support requests.

When to Use It?

Use Cases

Use Product Changelog when releasing new versions of a software product or API, when maintaining public release notes for open source projects, when building automated release pipelines that generate documentation, or when communicating product updates across multiple channels.

Related Topics

Conventional commit message standards, semantic versioning, release management automation, technical writing for developers, and customer communication strategies complement changelog workflows.

Important Notes

Requirements

A version control system with meaningful commit messages or pull request descriptions. A versioning scheme such as semantic versioning for organizing releases. Distribution channels identified and configured for changelog delivery.

Usage Recommendations

Do: write changelog entries from the user's perspective, explaining what changed for them rather than what code was modified. Highlight breaking changes prominently with clear migration instructions. Publish changelogs at the same time as releases so users can review changes before updating.

Don't: include internal refactoring or dependency updates in user-facing changelogs unless they affect behavior. Use technical jargon in changelogs intended for non-developer audiences. Skip changelog entries for minor releases, as gaps create distrust about what changed.

Limitations

Automated extraction depends on consistent commit message formatting that teams must adopt. User-facing language generation from technical descriptions requires human review for accuracy. Multi-channel distribution adds complexity that must be maintained alongside each distribution target.