How to Keep a Changelog: Format, Best Practices, and Examples Written for Humans

To keep a changelog, record every notable change to your product in reverse-chronological order, grouped by release and sorted into six categories: Added, Changed, Deprecated, Removed, Fixed, and Security. This is the keepachangelog.com standard that thousands of software teams follow. Update the changelog with every release, write each entry for humans rather than machines, and publish it where users can actually find it.

A changelog is more than a dry log of updates, bug fixes, and feature additions. It is a roadmap that walks users through your product's evolution.

The best changelogs are built for one goal: engagement. If you want users to care about enhancements and fixes, the changelog has to be actionable, comprehensive, and readable, without clutter. This guide covers why a changelog matters, the standard format, versioning, automation, seven best practices, and examples from Discord, Slack, Minecraft, and Canva.

Why Is Keeping a Changelog Important?

A changelog is a chronological record of every notable change made to a project. It lets stakeholders and customers follow the timeline of a product: what was added, what was changed, and what was removed. The role of the changelog has evolved. Dedicated software now handles the publishing, and users are far more interested in how the product they rely on is being refined.

A public changelog also lets users track which feature requests have shipped. That builds excitement about new work and shows customers that their voices are heard and their needs are met.

Which Changes Are Significant Enough To Include in a Changelog?

When a product changes, users want to know how and why. If a change affects the user experience in any way, it belongs in your changelog. That holds whether the effect is positive or negative. It usually covers:

• Improvements
• Bug fixes
• Security updates
• New features

Purely internal work, such as refactoring that does not alter behavior or updating internal tooling, can stay out of the user-facing changelog. It may still belong in an internal or developer changelog. Beyond that, base the changelog on what your users find helpful or interesting, and use a changelog tool to make it easy to reach.

How To Keep a Changelog With a Comprehensive Changelog Tool

The easiest way to keep a changelog is to use a tool such as AnnounceKit that handles publishing, notifications, and feedback in one place. It makes the process efficient and keeps the changelog productive rather than a chore.

If your marketing site runs on WordPress, start with our comparison of the best changelog tools that integrate with WordPress. If you already keep a changelog elsewhere and want to switch tools, the changelog migration guide shows how to move your history without losing anything.

AnnounceKit's changelog tool supports transparent communication and a better overall user experience. It helps you keep a changelog by providing:

• Post scheduling
• In-app notification widgets
• Rich media content
• Push notifications
• User feedback and reactions
• User segmentation
• Customized design
• Privacy options
• Multiple languages
• User tracking

How To Write an Effective Changelog Post

Once you have picked a tool, start shaping the posts. A changelog post usually contains these components:

• Category: Create different categories for different kinds of content.
• Date: Include the date of the announcement.
• Header: Write a header that names the product and the scope of the post.
• Overview: A brief description of what the post covers that emphasizes the change.
• Feedback: Let visitors leave a reaction or a text response on each post.
• Segmentation: Target updates by demographics, location, language, URL, and past behavior on your site.

A good changelog post is more than generic information tacked onto a date. Because a changelog can build real interest in your product's development, each post should be straightforward but also:

• Informative
• Organized
• Engaging
• Clear
• Hype-generating
• Aligned with your brand identity and personality

At the entry level, start with the correct category (Added, Changed, Fixed, and so on), use active voice and plain language, and explain what changed and why it matters to the user. Keep each entry to one or two sentences and link to documentation or tutorials where they help. If a change needs a long explanation, link to a dedicated blog post or help article rather than embedding a wall of text in the changelog itself.

7 Best Practices for Keeping a Changelog

#1: Include a Call to Action

Always invite an immediate response. A call to action (CTA) is a crucial element of a changelog because it moves readers into your sales funnel.

The tone and elements of your changelog can remind customers why they enjoyed your product in the first place. Good CTAs in a changelog include:

• Explore this new feature
• Learn more about this bug fix
• Try out the new software integration

Changelog CTAs should be:

• Worded in clear language
• Visually striking
• Placed strategically
• Action-oriented

#2: Set Up a Release Schedule

Pick a weekly or monthly cadence and stick to it. Update the changelog every time you release, with no exceptions. Teams on continuous delivery may post weekly or even daily, while traditional release cycles may post monthly or quarterly. If a week or month passes with nothing to publish, ask why progress slowed and where things went wrong.

You can also plan releases around notable industry dates. SaaS entertainment products like SoundCloud or Spotify might publish changelogs in April or May to prepare for June and July, which experts say is the best time to release new music. Digital learning products might make announcements during the summer. The point is to time updates so they attract the most interest in your product.

#3: Remember That Changelogs Are for Humans

Changelogs are for people, not machines. They need to be readable by someone with only a basic understanding of your product. There is no point in making things hard for your customers.

Complexity impresses other software developers, not the average user trying to find out whether the bug they hit was patched. Difficult entries also discourage people from following your updates in the future.

#4: Include Visual Components

A good image with a hook is like wrapping a gift: people always want to know what is inside.

GIFs, images, screenshots, and even videos make a changelog appealing. They also make a change easier to understand, especially for people unfamiliar with your product.

Larian Studios' changelog for Baldur's Gate 3 is a great example of striking visual components.

The turn-based game won the 2024 Game of the Year Award. It kept drawing attention through an entertaining, appealing changelog until the studio declared the game 100% complete in April. Video snippets, memes, and branded aesthetics run through everything Larian presents and writes in its announcements.

#5: Make Your Changelog Accessible

A changelog should be easy to reach from your site navigation and from inside your product. A technical changelog is usually hidden away from normal users. Your user-facing changelog should be the opposite: central and easy to find. Publish it through a dedicated page, an in-app widget, or both, so users always know where to look.

AnnounceKit lets clients and customers open your changelog directly, make feature requests, and stay up to date on new releases. With AnnounceKit widgets on your website, customers never have to leave the main page to get the full scoop.

#6: Provide Links to Relevant Sources

Have you ever read an article with a really interesting statistic, but the writer never linked the source? You went down a rabbit hole to find and verify it, and by the time you did, you were no longer interested in the rest of the article.

That is how users feel when you do not link the resources behind your changes. A changelog should be a comprehensive announcement that connects the dots and answers questions, not one that leaves users to hunt down answers on their own.

Linking relevant data and resources can significantly affect product or feature adoption. A link to the next step helps users activate and use what you shipped. Blog posts, tutorials, recorded webinars, and similar resources all help users understand the impact of the changes in your changelog.

#7: Keep Your Changelog Consistent and Easy To Read

Consistency builds familiarity. A consistent format improves readability and establishes a distinct style your audience can recognize. The goal is a medium for updates that users can adapt to, creating a cohesive and user-friendly experience.

Keep your changelog versioning consistent as well. Then focus on making entries concise and readable with bullet lists. Unless you are writing a novel, most readers will not wade through paragraph after paragraph. Breaking main points and key changes into bullets makes the changelog easy to skim.

4 Examples of Businesses That Follow Changelog Best Practices

Here are four changelogs that attract public interest and strengthen their products and brands by improving the user experience. For mobile-specific inspiration, see our roundup of the best app release notes.

Example #1: Discord

Discord is a communication app widely used in the gaming industry. Users connect over shared interests through voice calls, video calls, and online messaging. The company has a large audience, with a value of $15 billion and over 200 million active users a month.

The most impressive thing about how Discord keeps its changelog is the casual, relaxed tone unique to the platform's brand. Entries read like playful prose full of pop culture references and memes. Discord's changelog keeps users updated and eager for the next announcement, and it has become central to the company's brand identity.

Example #2: Slack

Have you ever wondered what a changelog would look like if that cool coworker announced software updates over a simple email? That is how Slack presents its changelog.

Slack's changelog embodies its purpose as a SaaS company. It is a $26.51 billion corporation used to connect work groups and coordinate project communication, so an informational but conversational tone makes sense. The changelog mirrors how information is presented in Slack channels and threads. Every update is straightforward and distilled into an easy-to-read snippet, so users never miss a beat when a new integration or feature rolls out.

Example #3: Minecraft

As one of the most popular, best-selling video games of all time, Minecraft remains a staple for gamers young and old. Its changelog is a vital part of that long-term success.

A good changelog generates hype and holds consumer interest. If people enjoy a product, they wait with bated breath for announcements and new rollouts, creating a cycle of anticipation.

Minecraft knows how to keep a changelog that does exactly that. From brand-produced YouTube videos to visually creative feature announcements, Minecraft's changelog is an indispensable tool for spreading the game. It keeps fans in love with a game released 14 years ago.

Example #4: Canva

Canva's changelog is well organized, detailed, and full of links to tutorials and further information. It is an excellent example of the golden rule of changelogs: keep it simple and make it clear.

When users want to learn a new Canva feature or extension mentioned in the changelog, they do not have to figure it out alone or search YouTube. They click one of the linked resources and quickly learn how it works. Canva also uses links to separate backend details that interest developers from what the average user, who works in the app for work or creative projects, actually needs.

What NOT To Do When Keeping a Changelog

#1: Don't Include Every Little Detail

Do not write about everything you do. Detailed technical issues are only interesting when they produce performance gains or improve the user experience. Your changelog can touch on technical details, but it should focus on how changes benefit users.

Avoid raw commit message dumps and changes with no user-visible impact. Also avoid vague entries like "various bug fixes." Be specific about what was fixed and why it matters. A changelog that is too granular or too vague is equally unhelpful to its readers.

#2: Don't Hide From Your Customers

Encourage customers to interact with your changelog and your team. The more interactive the changelog, the more users will engage.

The old definition of a changelog no longer fits. It is not just a place for technical notes. It should be a central, dynamic part of your user communication system, and a powerful way for your team to engage users and collect direct feedback.

#3: Don't Forget To Update Deprecations

Certain features become obsolete or get replaced as a project progresses. To keep trust and a positive user experience, make sure your changelog clearly communicates every deprecation and removal.

Address reported user concerns directly. Tell users exactly why a feature was removed, and keep them informed about new features that improve the experience.

#4: Don't Separate Related Changes

Group related changes together. This makes your changelog more readable and organized. It should flow, not jump from a related subject to an unrelated topic. Whether the changes are bug fixes, new features, or improvements, presenting them together lets users see each update quickly without getting lost in a sea of information.

#5: Don't Make Your Changelog Difficult To Access

Do not design your changelog only as a separate page that users must remember to visit. Always include a sidebar or widget on your landing page that leads to that page. AnnounceKit lets you do both, which draws more users to your standalone changelog.

What Is a Changelog?

A changelog is a structured, chronological record of all notable changes made to a project, product, or codebase. It is written for humans, including developers, product managers, and end users, so they can understand what changed, why it changed, and how it affects them. A well-written changelog answers the question every user has when they open an app and notice something different: what happened?

Unlike internal commit logs or technical release notes, a public-facing changelog is curated communication. It filters out noise and surfaces only the changes that matter to the reader. The best changelogs follow a consistent format, use clear language, and are organized by date or version so readers can navigate them effortlessly. Understanding what a changelog is and why it matters is the first step toward keeping one that actually serves your users.

What Is the Difference Between a Changelog and Release Notes?

Changelogs are closely related to, but distinct from, release notes. A changelog is a running, cumulative record of all changes, kept in a single document that grows over time. Release notes are usually a standalone document tied to a specific version or release event, and they tend to be more formal and comprehensive.

In practice the terms are often used interchangeably. The difference is that a changelog is the more user-friendly, always-accessible record your customers can consult at any time, while release notes are version-specific and may be archived once the release is superseded.

Keep a Changelog Format: What the Official Standard Looks Like

The most widely adopted changelog standard comes from keepachangelog.com. It defines a practical format that thousands of open-source projects and SaaS products follow. Understanding it helps you keep a changelog that is both machine-readable and genuinely useful to humans. For a ready-made starting point, our changelog template and examples follow this same structure.

The standard file is a Markdown document named CHANGELOG.md, organized by version number with the newest release first. Each release entry sorts changes into six standardized categories:

• Added: New features or capabilities introduced in this release.
• Changed: Modifications to existing functionality, including behavior changes and updates.
• Deprecated: Features that still work but are being phased out and will be removed in a future release.
• Removed: Features or functionality that have been permanently removed.
• Fixed: Bug fixes and corrections to broken behavior.
• Security: Patches addressing vulnerabilities or security risks.

Not every release will include entries in all six categories, and that is fine. Use only the categories that apply. The key is consistency: using the same structure every time lets users scan quickly and find what matters to them.

Here is what a typical CHANGELOG.md entry looks like in practice:

## [2.4.0] - 2026-03-15

### Added
- New in-app notification widget with custom positioning options
- Support for webhook triggers on changelog publish events

### Changed
- Improved loading speed of the widget by 40% on mobile devices

### Fixed
- Fixed a bug where scheduled posts would not publish on the correct timezone

### Security
- Updated dependencies to address a known XSS vulnerability in the rendering engine

Even if your changelog lives on a web page rather than a Markdown file, following this categorical structure gives readers a predictable, scannable experience. Tools like AnnounceKit let you apply these categories visually, using labels and tags, so your users get the clarity of the standard format without needing any technical knowledge to navigate it. Readers see the same six groups on every post, which keeps a web changelog as scannable as the Markdown file.

How Versioning Connects to Your Changelog

Versioning is the system you use to number each release of your product, and it is tightly linked to how you keep a changelog. Without a clear versioning strategy, your entries have no anchor. Readers cannot tell whether a change is a minor tweak or a breaking update.

Decide how to version your product before you start keeping a changelog, and you will avoid significant confusion later. Tie every entry to a version number so readers can match what they see in the product to what they read in the log.

The most widely used convention is Semantic Versioning (SemVer), which uses a three-part number: MAJOR.MINOR.PATCH. A MAJOR increment signals a breaking change, something that may require users to update their workflow or code. A MINOR increment introduces new features in a backward-compatible way. A PATCH increment covers bug fixes and small improvements that do not change the product's interface or behavior.

Moving from version 2.3.1 to 2.4.0 tells users that new features were added without breaking anything they already relied on. For a deeper dive into numbering strategies, see our guide to changelog versioning.

Other approaches include date-based versioning (for example, 2026.03.15), which is common for products that release on a regular calendar schedule, and codename versioning, used by products like Android or Ubuntu that attach memorable names to major releases for marketing purposes. Whichever system you choose, apply it consistently in every changelog entry. A version number should tell users the scope and nature of a change before they read a single line of the entry itself.

How To Automate Changelog Generation

Updating a changelog by hand is sustainable while your team is small and releases are infrequent. As your product scales, the manual process becomes a bottleneck. Releases pile up, entries get skipped, and the changelog drifts out of sync with reality.

Automation removes that friction and keeps the changelog accurate without constant manual intervention. (We cover the customer-facing side of this in how to automate release notes.)

For developer-facing changelogs, tools like semantic-release, standard-version, and Conventional Commits can parse your Git commit history and generate a structured CHANGELOG.md with each release. They work best when your team adopts a consistent commit message format, for example prefixing commits with feat:, fix:, or chore:, so the automation can sort changes into the six standard groups. CI/CD pipelines (GitHub Actions, GitLab CI, CircleCI) can trigger these scripts automatically on each merge to your main branch.

For user-facing, marketing-friendly changelogs, tools like AnnounceKit connect to your development workflow through the API, Zapier, and webhook triggers. You can set up a workflow where merging a release branch automatically drafts a changelog post in AnnounceKit, ready for a product manager to review and publish with one click. Our guide to automating AnnounceKit with ViaSocket walks through more workflows like this, and the changelog automation page covers the full setup.

This hybrid approach, automated drafting with human-curated publishing, gives you the speed of automation while preserving the editorial quality that makes a changelog genuinely useful to end users. Fully automating a user-facing changelog risks publishing entries that are technically accurate but poorly written or tone-deaf to the audience.

AnnounceKit: Changelog Software for Seamless Product Updates

Changelogs may have started as technical documents, but there is no reason to overcomplicate them when you can simplify and streamline the process. AnnounceKit makes it easy for anyone to keep a changelog.

Changelogs are a fantastic marketing tool, and you should not skip them because they take time to create and manage. With AnnounceKit, they do not. Keeping a changelog with a no-code tool makes the process sweat-free. See how Sleeknote made AnnounceKit part of its process, learn more about our changelog software, or request a free demo today.