A change log is the public record of what changed in your WordPress plugin or theme between releases. It tells users what was added, fixed, removed, improved, or secured. For developers, it is part release note, part support shield, and part trust signal. If your update breaks a layout, fixes a fatal error, or changes a setting name, the change log is where users should learn that before they click Update.
TLDR: A good change log helps users decide whether to update now, wait, or test first. For example, if version 2.4.1 says “Fixed checkout button conflict with WooCommerce 8.6,” a store owner can update with more confidence. In one common support case, clearer release notes can cut repeated “what changed?” tickets by 20% to 30% after a busy release. Keep entries short, grouped, dated, and written for humans.
What a change log actually does
A change log answers one simple question: “What happened in this release?” That sounds small. It is not. WordPress users often manage live stores, membership sites, client sites, newsrooms, and booking systems. They need to know whether an update is harmless, urgent, or risky.
For plugin and theme developers, the change log also protects your time. Without it, users guess. Then they open tickets. Then you repeat the same answer for three days. It drives me crazy that many products still ship updates with “minor fixes” as the only note. Minor to whom? The developer? The site owner whose checkout just crashed?
A useful change log gives enough detail to reduce confusion without turning into a full engineering diary.
Change log vs commit history
A change log is not your Git log copied into a text file. Commit messages are written for developers, often during messy work. A change log is written for users, site builders, agencies, and support teams.
Compare these two entries:
- Bad: Refactor widget init and fix issue.
- Better: Fixed a bug where the Featured Posts widget could disappear after saving theme options.
The second entry explains the user-facing result. It gives context. It also helps support agents search old releases when a user reports the same symptom months later.
What to include in a WordPress change log
Most WordPress plugin and theme change logs should include a version number, release date, and grouped entries. Use categories so readers can scan fast.
- Added: New features, settings, blocks, widgets, templates, integrations, or hooks.
- Changed: Modified behavior, renamed labels, adjusted defaults, or updated UI flows.
- Fixed: Bugs, compatibility issues, display problems, PHP notices, and broken workflows.
- Security: Vulnerability fixes, hardening work, permission checks, escaping, nonce checks, or sanitization updates.
- Removed: Deleted features, old APIs, deprecated files, or dropped third party support.
- Deprecated: Features that still work but will be removed later.
If the release affects compatibility, say so clearly. For example: “Requires WordPress 6.4 or higher” or “Tested with WooCommerce 8.8.” If you changed PHP support, put that near the top. Nobody enjoys finding out after a white screen.
A practical format you can reuse
Here is a clean structure for a plugin or theme release:
== 2.3.0 - 2026-08-24 ==
Added:
- Added a new layout option for the pricing table block.
- Added filter hook acme_pricing_table_output.
Changed:
- Improved loading speed for front end CSS on pages without plugin blocks.
Fixed:
- Fixed a fatal error when saving settings on PHP 8.3.
- Fixed an issue where translated button text was not displayed.
Security:
- Improved escaping for custom title fields in the admin screen.This format works because it is boring in the best way. Users can scan it. Developers can maintain it. Support teams can link to it.
Where WordPress developers should put the change log
If your plugin is on WordPress.org, the standard place is the readme.txt file under the == Changelog == section. Keep the most recent release at the top. WordPress.org reads this file and displays the change log on the plugin page.
For themes, place release notes in your theme documentation, product page, repository releases, and support portal. If you sell a premium theme or plugin, include the change log in the customer account area and update modal. Users should not need to dig through GitHub tags just to learn what changed.
Good places to publish your change log include:
- WordPress.org readme: Best for public plugins.
- GitHub releases: Useful for developers and contributors.
- Product documentation: Best for customers and agencies.
- Admin update screen: Useful at the exact moment of decision.
- Email release notes: Helpful for major updates and security fixes.
How detailed should each entry be?
Use enough detail to prevent confusion. Do not bury users in internal trivia. A good entry names the affected feature and the visible result.
- Too vague: Improved performance.
- Better: Reduced product archive query time by 35% on stores with more than 5,000 products.
- Too vague: Fixed security issue.
- Better: Fixed a permissions issue affecting users with Contributor roles. Update recommended.
Security notes need care. Be honest, but avoid giving attackers a recipe before users can update. If a vulnerability is already public, include the CVE or advisory link if available. If not, describe the impact in plain terms and urge users to update.
Use semantic versioning, but do not worship it
Many WordPress developers use semantic versioning: major.minor.patch. A version like 3.2.1 usually means:
- 3: Major release. May include breaking changes.
- 2: Minor release. Adds features without expected breakage.
- 1: Patch release. Fixes bugs or security issues.
This is useful, but users still need words. A jump from 2.9.9 to 3.0.0 should explain what changed, what could break, and how to prepare. If migration is needed, link to a guide. Expect to waste time on support if you ship a major update with a three-word note.
Write for different readers
Your change log has more than one audience. Site owners want risk level. Developers want hooks, template changes, and compatibility notes. Agencies want to know whether they should test client sites before updating. Support teams want searchable details.
Use plain language first. Add developer details after that.
Example:
Changed:
- Updated the checkout notice layout to improve mobile spacing.
- Developer note: The template file checkout notice.php was updated. Override copies should be reviewed.This serves both readers. The user understands the visible change. The developer gets the technical warning.
Common change log mistakes
- Writing “various fixes” every release: This helps nobody.
- Skipping dates: Dates matter when users compare bug reports and updates.
- Hiding breaking changes: Put them at the top. Use bold text if needed.
- Mixing unreleased work with released work: Keep a separate “Unreleased” section if you need one.
- Using developer slang: “Fixed race condition in async hydration” may be true, but add the user impact.
- Forgetting translations: If strings changed, translators and multilingual site owners need to know.
A simple workflow for maintaining one
Do not wait until release day. That is how change logs become vague. Add entries while you work. Keep an Unreleased section in your repository. Before shipping, edit it for clarity and move it under the new version number.
A solid release workflow looks like this:
- Add a short change log note with each pull request or ticket.
- Group entries under Added, Changed, Fixed, Security, and Removed.
- Check whether any change affects minimum WordPress, PHP, or WooCommerce versions.
- Mark breaking changes clearly.
- Rewrite technical notes into user-facing language.
- Publish the same release notes everywhere users expect them.
Final checklist for your next release
- Does the change log say what changed, not just that something changed?
- Is the newest version at the top?
- Are security and breaking changes easy to spot?
- Are version numbers and dates included?
- Could a non-developer understand the main impact?
- Would your support team be able to link to it with confidence?
A change log is not busywork. It is a small habit that makes updates safer, support lighter, and your product more credible. Treat it like part of the release, not an afterthought scribbled five minutes before upload.
