← Development guidelines

Code · Architecture · UX

User changelog template

Download editable Markdown

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

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

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.

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.