Always use the standard headers: Added, Changed, Deprecated, Removed, Fixed, Security.
Do not explain why you made the change (save that for the commit message or blog post). The CHANGELOG answers what changed.
The newest version goes at the top. When a user opens a CHANGELOG, they should see what changed yesterday, not what changed three years ago.
The importance of a good changelog – WordPress Developer Blog 18-Nov-2025 —
The Changelog: Why This Simple File is the Secret to Software Success
A changelog is a curated, chronologically ordered list of notable changes for each version of a project. While it may look like a simple text file, it serves as the vital communication bridge between developers and users. Whether you are managing an open-source library or a massive enterprise SaaS platform, a well-maintained changelog reduces friction, builds trust, and ensures that everyone—from the lead engineer to the end-user—understands how the software is evolving. The Core Purpose of a Changelog
The primary goal of a changelog is to make it easy for humans to understand exactly what has changed between two versions of a product. In the fast-paced world of software development, codebases are modified thousands of times. If a user wants to know why a feature they rely on suddenly looks different, or if a developer needs to know if a security vulnerability was patched, they shouldn't have to sift through thousands of lines of raw "commit messages" like fixed bug or updated CSS.
A changelog transforms technical activity into meaningful information. It answers three critical questions: What is new? What was fixed? What is going to break if I update? The Difference Between a Changelog and a Commit Log
A common mistake made by junior developers and automated systems is treating a Git commit log as a changelog. These are fundamentally different tools for different audiences. Commit Logs Audience: Developers working directly on the code.
Content: Every single change, including typos, refactors, and "work in progress" steps. Tone: Highly technical and granular. Changelogs
Audience: End-users, stakeholders, and developers who use the software as a dependency.
Content: Only notable changes that impact the user experience or implementation. Tone: Clear, concise, and focused on value or impact. Standard Categories in a Changelog
To keep a changelog readable, changes are typically grouped into standardized buckets. The most widely accepted categories include: Added: For new features that have been introduced.
Changed: For changes in existing functionality (e.g., UI updates).
Deprecated: For soon-to-be-removed features, giving users a heads-up to migrate.
Removed: For features that have been officially stripped from the project. Fixed: For any bug fixes.
Security: In case of vulnerabilities, this section highlights patches to encourage immediate updates. Best Practices for Writing Great Changelogs
Following the "Keep a Changelog" principles ensures your file remains useful over time. 1. Human-Readable Language
Avoid jargon where possible. Instead of saying "Optimized SQL query using indexed JOINs," say "Improved loading speed for the user dashboard." 2. Use Semantic Versioning (SemVer)
Most changelogs follow the Major.Minor.Patch format (e.g., 2.1.4). Major: Breaking changes. Minor: New features (backward compatible). Patch: Bug fixes (backward compatible). 3. The Newest Changes Go at the Top
Always use reverse chronological order. Users care most about what happened today, not what happened three years ago. 4. Link to Pull Requests or Issues
For those who want to dive deeper into the "why" behind a change, providing a link to the specific GitHub issue or Pull Request is incredibly helpful. 5. Be Honest About Breaking Changes CHANGELOG
If an update will break a user’s current setup, highlight this prominently. Use bold text or a dedicated "Breaking Changes" section at the very top of the version notes. Why Your Project Needs One Builds User Trust
When users see a consistent changelog, they know the project is active. It signals that the developers are listening to feedback and actively squashing bugs. Simplifies Support
A public changelog acts as a self-service support tool. Before a user opens a ticket saying "Feature X isn't working," they can check the changelog to see if a fix was recently released or if the feature was intentionally changed. Streamlines Internal Communication
In larger companies, marketing and sales teams use the changelog to understand what new "hooks" they have to sell to customers. It keeps the entire organization aligned on the product's trajectory. Conclusion
A changelog is more than just a list of updates; it is a historical record of a project’s growth and a testament to the developers' commitment to their users. By moving away from cryptic commit messages and toward clear, categorized, and human-centric notes, you turn a simple text file into one of your project’s most valuable assets. To help you get started with your own,
The Ultimate Guide to the "CHANGELOG" A changelog is a curated, chronologically ordered record of all notable changes made to a project, typically software. Unlike a raw commit history which is written for machines and developers, a changelog is designed for human readers—users, project managers, and contributors—to understand what has been updated, fixed, or added in each version. Why a Changelog Matters
User Transparency: It eliminates guesswork for users who rely on your software, clearly showing them what has changed and why they should update.
Team Alignment: It helps QA teams know what to test, project managers track progress, and developers reference past work quickly.
Reduced Support Burden: Providing clear documentation of fixes can reduce the volume of repetitive bug reports.
Trust and Reliability: Regular updates signaled through a changelog demonstrate that a project is actively maintained and evolving. Best Practices for Writing a Great Changelog
To make your changelog truly useful, follow these industry-standard guidelines often championed by resources like Keep a Changelog:
Chronological Order: Always place the most recent release at the top of the file.
Semantic Versioning: Use clear version numbers (e.g., v1.1.0) so readers immediately understand the scope of the changes.
Group Changes by Type: Categorize your updates to help users find what they care about most: Added for new features. Changed for changes in existing functionality. Deprecated for soon-to-be removed features. Removed for now-removed features. Fixed for any bug fixes. Security in case of vulnerabilities.
Include Dates: Every version entry should include its release date to provide a timeline of development.
Keep it Readable: Use simple, everyday language. Avoid jargon that only the core developers would understand. Automation vs. Manual Curation
While some developers use tools to automatically generate changelogs from Git commit messages, purely automated logs often contain noise that is irrelevant to end-users (like "fixed typo in README").
Manual: Higher quality and more user-focused, but time-consuming.
Automated: Efficient for high-velocity projects, but requires strictly formatted commit messages (like Conventional Commits) to be useful.
Hybrid: Many teams use GitHub's automated release notes to generate a draft and then manually polish it before publishing. Where to Host Your Changelog
Refining how updates to documentation articles are tracked ... - GitHub Always use the standard headers: Added , Changed
Title: The Patch Notes for a Broken Heart
Elara stared at the blinking cursor on her terminal. The world outside her apartment had ended three weeks ago. Or rather, her world had.
Leo had left. Not with a bang, but with a quiet, devastating .exit command.
For the first week, she couldn't function. She was a program stuck in an infinite loop. while (heartbroken) eat.sleep.cry();
On Day 10, desperate to feel anything other than grief, she opened her journal. On a whim, she titled the entry: CHANGELOG - User: Elara, v. 29.4.
She started writing.
CHANGELOG - User: Elara Version: 29.5 (Post-Leo Patch)
FIXED:
REMOVED:
ADDED:
KNOWN ISSUES:
She wrote entries every day. Day 12: Patched the "favorite ramen shop" crash. Day 15: Refactored "trust" module. Performance is shaky but online.
On Day 21, she smiled for the first time. It wasn't a big smile. It was more of a UI flicker.
CHANGELOG - Version 30.0
EMOTIONAL MILESTONE:
OPTIMIZATIONS:
DEPRECATION WARNING:
BETA FEATURE:
Six months later, she closed the final entry.
CHANGELOG - Version 32.2
STATUS: Stable. BUGS: Minor, manageable. NEW FEATURE: Happy. (It's still in beta, but daily usage is smoothing out the rough edges). Title: The Patch Notes for a Broken Heart
She smiled at the screen. She had done it. She had debugged her own ghost.
The changelog wasn't a list of fixes. It was a story. The story of how she rewrote her own source code, one broken line at a time, until she became a version of herself that could finally run again.
And the best new feature? She was open source now. Ready for the next developer to come along and add beautiful, terrifying new code.
If you take nothing else away from this article, remember this: If it didn't make the CHANGELOG, it didn't happen.
Your users are not mind readers. Your support team is not omnipotent. Your code is not self-documenting.
The CHANGELOG is the single source of truth for what has changed. It reduces friction, builds trust, and transforms your release process from a chaotic firefight into a professional, predictable rhythm.
Stop telling your users "We're always shipping." Start telling them exactly what you shipped, when you shipped it, and why they should care.
Write the CHANGELOG. Your future self—and your furious users—will thank you.
Liked this article? Subscribe to our own CHANGELOG to get notified when we update our best practices.
A good changelog is a curated, chronological list of notable changes made to a project
. It is written for humans—not machines—to help users and contributors understand the "why" behind software updates. 1. Guiding Principles Write for humans
: Avoid dumping raw git logs; use clear, plain language that people with zero context can understand. Keep it chronological : Place the latest version at the top. Use consistent dates YYYY-MM-DD format (e.g., 2026-04-10) for international clarity. Group by impact
: Categorize changes so readers can scan for what matters most to them (e.g., security fixes vs. new features). Hacker News 2. Standard Categorization Use these specific labels to group your updates: Keep a Changelog : For brand-new features. : For updates to existing functionality. Deprecated : For features that will be removed in future versions. : For features that have been officially deleted. : For any bug fixes. : For patches addressing vulnerabilities. Keep a Changelog 3. Recommended Format (Markdown) Maintaining your changelog in a CHANGELOG.md file allows for easy linking and readability. # Changelog
All notable changes to this project will be documented in this file. ## - 2026-04-10 New dashboard widget for real-time analytics. Multi-language support for French and Spanish. Resolved a crash when loading large datasets. ## - 2026-03-25 ### Security Patched critical vulnerability in user authentication. Use code with caution. Copied to clipboard 4. Automation Tools
If manual updates become tedious, you can automate parts of the process using these tools:
Ghost has a beautiful /changelog page. Each entry has a hero image, a video, and a detailed explanation. They treat their CHANGELOG as a product marketing page. Users look forward to reading the Ghost CHANGELOG.
Behavioral economics tells us that losses hurt twice as much as gains feel good (Loss Aversion). If you only announce new features (Added X!), users are happy. But if you announce a removal (Removed Y), users panic.
A CHANGELOG manages this by introducing the Deprecation section.
The CHANGELOG provides predictability. It turns a sudden betrayal into a scheduled event.
The vast majority of changelogs fall into the "Bad" category because they are written by developers, for developers, without consideration for the broader audience.