# Technical version journal template

Template edition: 3.2.0
Revised: 2026-10-25

Guideline content by [Lucas Vitti](https://lucas.mat.br), licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). See [scope and attribution](LICENSE.md).

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](change-plan-template.html) and [current design guide](project-design-template.html) 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](user-changelog-template.html), normally in `docs/CHANGELOG-USERS.md`. Include both records in the documentation index.

## Release identity and state

- **Project and version:** [version, preceding version, and date].
- **Adopted guidelines:** [edition used for this change].
- **Source or artifact identity:** [source commit and build/release manifest or artifact hash; use an artifact identity if no commit exists].
- **State:** [planned, implemented, verified, released, deployed; describe actual state and any partial outcome].
- **User changelog:** [entry reference and intended audience; same version identity and consistent dates and actual availability].
- **Plan and decisions:** [approved plan revision and consequential decision IDs].
- **Approval:** [approver, date, reference, approved scope, and explicit deployment authorization if granted].

## 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.

- **New capabilities:** [what a user or maintainer can now do, why it was added, and the related acceptance evidence].
- **Corrections:** [previous failure, trigger or affected case, corrected behavior, and regression evidence].
- **Improvements:** [readability, architecture, UX, performance, or operations improvement; concrete before/after effect, with measurements for performance claims].
- **Other changes and removals:** [changed defaults, deprecations, removed behavior, and who is affected].
- **Documentation:** [plan, current architecture/UX records, setup, examples, or decisions updated].
- **Internal parameters:** [register IDs, previous and new values with exact units/scope, why a limit/default/policy changed, plain-language user effect, approval, interacting constraints, relevant boundary checks, and whether the new effective value is deployed; state no parameter changes when applicable].

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

- **Contracts and data:** [API, persisted data, configuration, dependency, permission, or UX changes; explicitly state no migration when that is verified].
- **Adoption work:** [migration instructions, new requirements, rollout conditions, and relevant user actions].
- **Known limitations:** [unresolved findings, baseline issues, scoped exceptions, and follow-up references].

## Verification evidence

- **Environment and revision:** [what was actually checked, with safe fixtures].
- **Checks and results:** [commands or test cases, pass/fail, boundary and size review, and relevant UX behavior].
- **Not run or not applicable:** [specific limitation and reason; do not imply full coverage].
- **Evidence references:** [report paths or artifacts tied to this version].

## Deployment and recovery

- **Target and authorization:** [release destination and evidence that deployment is authorized; pending if not granted].
- **Outcome and time:** [not deployed, successful, failed, partial, or rolled back; actual date/time and artifact identity].
- **Verification:** [observed version, relevant smoke checks, or content hashes; an upload alone is not success].
- **Recovery:** [linked rollback/runbook, previous release identity, and data-recovery constraints where applicable].

## 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.
