Code · Architecture · UX
User changelog template
Template edition: 3.2.0
Revised: 2026-10-25
Guideline content by Lucas Vitti, licensed under CC BY 4.0. See scope and attribution.
Keep a separate, newest-first user history in the project's documentation folder, normally docs/CHANGELOG-USERS.md, linked from its index. Pair every version with the full technical version journal. Use the same version identity and consistent dates and availability. Write in the product's language for people using it, with actual interface labels. This template does not require adding an in-app page, popup, or notification.
Entry identity and availability
- Version and date: [same version as the technical journal; distinguish preparation, release, and deployment dates if they differ].
- Availability: [planned, local preview, available to specified users/environment, partial rollout, or withdrawn; say what is actually available and when].
- Who is affected: [relevant users, role, device, or workspace restrictions; omit if it applies to everyone].
Write a short explanation of what people can do differently and why it matters. Use only the categories that apply; omit empty headings and placeholders. Keep one entry for internal-only versions with "No user-visible changes in this version." A shorter entry is better than an invented benefit.
What changed for users
- New capabilities: [what the person can now do and where to begin, using real page and button names].
- Moved or renamed: [old label/location, new label/location, and how to reach the function now].
- Removed: [what is gone, who is affected, replacement if one exists, or explicitly no replacement; any required action].
- Fixed: [the problem someone experienced and the corrected behavior].
- Limits, access, and other changes: [user-visible limits with clear units, permission changes, changed defaults, or security actions users need to understand].
- What you need to do: [specific steps and any deadline; otherwise say no action is needed when that helps the reader].
- Known limitations: [remaining issues or rollout restrictions that affect the reader's next action].
Explain a changed upload allowance as a per-file limit rather than an internal constant. Say where a moved button went. Say if a removed page's function is still available elsewhere. Do not substitute "various improvements" for these facts or claim speed/reliability benefits without supporting evidence. Keep module names, commits, internal paths, test logs, and private operational details in the technical journal. An accessible technical-detail link is optional; never expose a private reference in a public copy.
Reconcile and preserve
Before completing a version, compare the user entry with the technical journal and verified behavior. Confirm the version, dates, affected audience, and availability agree; keep future changes visibly pending. Include features, fixes, refactors, and documentation-only versions. Preserve earlier entries. Append dated corrections with a reason instead of erasing history or presenting a planned feature as previously available. Existing projects can document the history's starting version and known gaps without inventing past events.
Illustrative entry: navigation and a fix
The following entry is fictional. It assumes the described behavior has been verified and made available; it does not describe an actual project release.
Version: 1.4.1. Date: [actual release date]. Availability: Available to all workspace users.
- Registering clients: On Clients, select New client to open the registration form. The list now occupies the main page. After saving, you return to the list.
- Prices moved: Open a client and select Prices on their details page. The button has moved from the client list.
- Pending items page removed: Open Queue and choose Pending to find the same items.
- Duplicate clients fixed: Retrying after a slow save no longer creates a duplicate client.
- What you need to do: Update any saved shortcut to the old Pending items page. Existing client records remain available.
Illustrative entry: internal-only version
The following entry is fictional and assumes behavior-preservation checks support the statement.
Version: 1.4.2. Date: [actual release date]. Availability: Available to all workspace users.
No user-visible changes in this version. No action is needed.