Blog / Digital products /
A release note process for a WordPress.org plugin
A WordPress plugin gets an update. The release note says only “bug fixes and improvements”.
Users can’t tell whether they need to do anything, whether the issue they reported was fixed or whether it touches their setup. Not exactly helpful.
A release note process turns product changes into clear information for the people who use, install and support the plugin. Keep it accurate, proportionate and easy to maintain from one release to the next. It’s the habit I’m trying to build with my own plugin on WordPress.org.
Decide what users need to know
Start with the actual change and who it affects. A security fix, a compatibility update, a new setting and an internal refactor each need different communication. Explain what users will see, not just what the code did. If the change is internal and needs no action, a brief note will do.
Say who is affected: all users, one configuration, a supported platform version or a beta group. Avoid vague phrases like “some users” when you can be more precise. And don’t overstate the impact if the issue was limited.
State whether users need to update, change a setting, migrate data or contact support. Be explicit about breaking changes and known issues. If no action is needed, say so only once the product owner has confirmed it.
Gather facts from the release
Use the merged changes, issue tracker, test record and product owner review as sources. Confirm issue identifiers and feature names before publishing. A commit message may show the developer’s intent, but not the user impact.
Separate fixed defects, new features, improvements and compatibility notes. Keep the language concrete: what the user can now do, what changed and where to find it. Skip internal jargon unless users need the term to finish a task.
Don’t claim a fix is universal if it covers one case. If a limitation remains, put it where the user will see it. And never invent a customer story or performance result to make an update sound bigger.
Use a consistent but flexible format
A release note can include the version or date, a summary, categories, who’s affected, actions required, known issues and links to documentation. Keep it scannable. The content should decide the length.
Keep one source of truth for the release text and adapt it for the WordPress.org listing, documentation, support replies or email. Check every channel shows the same facts and version.
Link to setup or migration instructions when the change requires a task. Verify links and screenshots against the released interface. Do not point users to draft documentation or an outdated page.
Review security and privacy details
Security notes may need a coordinated disclosure process. Follow the product’s policy and qualified guidance on timing, detail and affected versions. Don’t publish exploit instructions or unsupported assurances. Tell users how to get the fix through the official update route.
If a release changes data collection, permissions or external services, explain what changes and update the relevant privacy information. Verify the actual behaviour with the technical owner.
Publish and learn
Have a developer verify technical facts and an editor check clarity. A product owner should confirm the user impact and actions. For a small release, one person can cover multiple roles, but the responsibilities remain distinct.
After publishing, check the note in the actual directory or site. Monitor support questions for confusion and revise documentation when needed. Keep a release history so users can trace the changes between versions.
Make release notes part of the release workflow
The easiest time to write an accurate note is while the change is under review, not after release when everyone has moved on. Add a short user-impact field to the release checklist or pull request process. Ask: what will a user notice, who is affected and what action is needed? If the change is internal, note that too.
Do not expect developers to guess the best public phrasing. They can provide the technical facts; an editor or product owner can translate them into user language. Keep a link from each note to its issue or release record, but avoid making users follow internal links to understand the update.
For a WordPress.org plugin, check how the directory page will look and follow the documented conventions before each release. The readme, changelog, tested compatibility and stable tag should all agree with what shipped. I never claim compatibility with a version or environment I haven’t verified. Directory requirements change, so consult the current official documentation when unsure.
Handle uncertainty without hiding it
Sometimes you know a change fixes a class of issues but haven’t reproduced every reported configuration. Be precise about the scope you tested. If a known issue remains, describe the practical limitation and a support route, subject to your disclosure process. Avoid “fully fixed” unless the evidence supports it.
If a release is urgent, accuracy still matters. Use a concise note, identify the affected versions if confirmed and state the update path. Coordinate security details with the responsible maintainer rather than improvising public disclosure. A release note should help users protect or operate their site without exposing information that creates avoidable risk.
Improve from support signals
Review the questions that arrive after a release. Repeated confusion may point to a missing action, an unclear term or documentation that’s hard to find. Update the note or linked guide where appropriate, and keep the version history. Don’t quietly rewrite an old note so it claims the release contained a later change.
Related reading
- A useful onboarding path for a WordPress plugin
- The role of SEO in finding users for a small plugin
- WooCommerce and WordPress: plugin update planning
A consistent release note habit also helps future maintainers see why a change mattered. Keep a lightweight archive with version, date, summary and any migration steps. Before you publish the next one, can a reader tell whether the change concerns them and what to do?