Tutorial: Maintain Your Project Changelog

In this tutorial, you’ll learn how to create and maintain a CHANGELOG.md file following industry best practices, ensuring your users and contributors always know what’s changed in your project.

What you’ll learn: How to document changes effectively using the Keep a Changelog standard.

Prerequisites:

• A Git repository
• Basic understanding of semantic versioning
• Familiarity with conventional commits

Why Keep a Changelog?

The Problem

Without a changelog:

• Users don’t know what changed between versions
• Contributors waste time figuring out what’s new
• Bug reports reference unknown changes
• Migration guides are impossible to write
• Release notes must be created manually every time

The Solution

A well-maintained changelog provides:

• Clear communication of what changed
• Version history at a glance
• Migration guidance for breaking changes
• Automated release notes generation
• Better user experience and trust

Part 1: Understand the Standard

The Keep a Changelog Format

The Keep a Changelog standard defines six types of changes:

Part 2: Create Your First CHANGELOG

Step 1: Create the File

In your repository root, create CHANGELOG.md:

Step 2: Commit the Initial Changelog

Part 3: Add Changes Throughout Development

Step 3: Document a New Feature

You’re adding user authentication. Update the [Unreleased] section:

Commit with the proper trailer:

Step 4: Document a Bug Fix

You fixed a memory leak. Add to [Unreleased]:

Step 5: Document a Breaking Change

You’re changing the API response format. This is a Changed entry and needs clear migration notes:

Part 4: Create a Release

Step 6: Move Unreleased to a Version

You’re ready to release version 1.0.0. Move [Unreleased] content to a new version section:

Step 7: Commit and Tag the Release

Part 5: Real-World Examples

Example 1: Patch Release (Bug Fixes Only)

Version 1.0.1 - only bug fixes:

Example 2: Minor Release (New Features)

Version 1.1.0 - new features, no breaking changes:

Example 3: Major Release (Breaking Changes)

Version 2.0.0 - breaking changes:

Part 6: Automate with GitLab CI

Step 8: Auto-Generate from Git Commits

Create .gitlab-ci.yml to generate changelog from commit messages:

Step 9: Use GitLab’s Built-in Changelog

GitLab can generate changelogs from commits. Add to .gitlab-ci.yml:

Part 7: Best Practices

Writing Good Changelog Entries

✅ Good Examples

❌ Bad Examples

Be Specific and User-Focused

Include Context and Impact

Reference Issues and Pull Requests

Quick Reference

Changelog Template

Decision Matrix: Which Section?

Troubleshooting

Problem: Forgot to update changelog before release

Solution:

Problem: Too many commits, hard to track

Solution: Use GitLab’s changelog API:

Problem: Team not following changelog trailers

Solution: Enforce with a Git hook. Create .git/hooks/commit-msg:

Next Steps

Now that you can maintain a changelog:

1. Automate generation - Use conventional-changelog or GitLab’s API
2. Create release notes - Extract changelog sections for releases
3. Document migrations - Add upgrade guides for breaking changes
4. Integrate with CI/CD - Auto-generate changelogs on release
5. Train your team - Ensure everyone updates the changelog
6. Review regularly - Keep the changelog accurate and helpful

Additional Resources

• Keep a Changelog
• Semantic Versioning
• Conventional Commits
• How to Git Commit (EBRAINS guide)
• Keep a CHANGELOG reference (original)

Summary

You’ve successfully learned:

• Why changelogs matter for your users
• The Keep a Changelog standard and format
• How to create a CHANGELOG.md file
• When to use each change type
• How to document features, fixes, and breaking changes
• How to manage versions and releases

Your changelog is now a valuable communication tool that keeps everyone informed!