← Development guidelines

Code · Architecture · UX

Technical version journal 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 the full technical narrative for every version in the project's dedicated documentation folder, normally docs/releases/<version>.md, with an index of versions. Start the entry while planning and reconcile it with the delivered result. Include fixes, refactors, and documentation-only releases. Link the approved change plan and current design guide rather than duplicating their contracts. A commit list or version number alone does not explain a release. Pair this record with a separate user entry using the user changelog template, normally in docs/CHANGELOG-USERS.md. Include both records in the documentation index.

Release identity and state

What this version delivers

Write a short account of the reason for the version and its practical effect. Describe actual work using the categories that apply; omit empty categories rather than inventing changes.

Keep planned items visibly pending until implemented and verified. Describe deployment separately; implementation or verification alone does not establish user availability. Explain scope changes and their approval instead of silently expanding the original story. Keep secrets, personal data, and exploitable private details out of any public copy.

Compatibility and adoption

Verification evidence

Deployment and recovery

Reconcile the user changelog

Confirm every user claim is supported by the delivered behavior and verification recorded here. Explain changed capabilities, navigation, controls, removals, fixes, limits, and required actions in the product's language, with actual labels and destinations. For an internal-only release, keep its user entry and state "No user-visible changes in this version." Match version, dates, affected audience, and rollout status. Keep technical evidence private when appropriate; do not expose private links in public user notes.

Later corrections

Preserve the published narratives in both histories. Append dated corrections with their reason, evidence, and follow-up version when appropriate. Do not erase the original outcome or rewrite a planned feature as if it had been available in an earlier release.

Illustrative entry

Version 1.4.1 corrects duplicate client creation when a user retries after a timeout. Previously, a retry could create a second record; now the same request returns the original result. The change preserves the response fields and requires no data migration. The regression and authorization checks passed against disposable data at the recorded source revision. Implementation is complete; deployment is pending authorization for the staging target. This example is fictional and does not establish any project's verification or approval.