L06 Changelog

title: "Writing Changelogs for Open Source Projects" weight: 6 description: "Learn to write changelogs for open source: Keep a Changelog format, versioning, breaking changes, deprecations, and communicating effectively with users about what changed between releases." date: 2026-06-28 lastmod: 2026-06-28 tags: [technical-writing, open-source] }

Changelogs communicate what changed between releases, helping users understand new features, bug fixes, breaking changes, and deprecations so they can decide whether to upgrade.

In this lesson, you will learn how to write changelogs following the Keep a Changelog format, including versioning, categorizing changes, and communicating effectively.

What You'll Learn

You will learn changelog format, versioning, categorization of changes, and communication best practices.

Why It Matters

Users need to know what changed before upgrading. A good changelog answers: should I upgrade and what do I need to change?

def changelog_entry(version, date, changes):
    """Generate a changelog entry following Keep a Changelog format."""
    entry = f"## [{version}] - {date}\n\n"
    for category, items in changes.items():
        if items:
            entry += f"### {category}\n\n"
            for item in items:
                entry += f"- {item}\n"
            entry += "\n"
    return entry

Teacher Mindset

Think of a changelog as a release letter to your users. You are telling them what you built, fixed, and changed. Be honest about breaking changes. Users appreciate transparency.

Common Mistakes

1. Changelog Is Just a Git Log

A git log dump is not a changelog. Summarize changes in human-readable format.

2. No Breaking Changes Section

Breaking changes must be prominent. Users need to know what will break.

3. Inconsistent Formatting

Each release should follow the same format. Consistency helps readers scan quickly.

Practice Questions

1. What sections should a changelog include? Added, Changed, Deprecated, Removed, Fixed, and Security. Omit empty sections.

2. Where should breaking changes be listed? Prominently, often at the top of the changelog entry.

3. Challenge: Write a changelog entry for a hypothetical release with 3 new features and 1 breaking change.

FAQ

Mini Project

Start or improve a changelog for an open source project. Convert an existing git-log-style changelog to the Keep a Changelog format.

What's Next

Governance Docs in the next lesson.