A published template is a production dependency
When an application generates invoices, contracts or reports, the template becomes part of customer-facing behavior. Editing it in place is equivalent to changing a production dependency without version history.
Version control answers three questions: what changed, who reviewed it and how can the team return to a stable state?
A minimal lifecycle
You rarely need ten statuses. Four cover most workflows:
- Draft: editable and not used for production generation.
- In review: frozen while people verify the change.
- Published: eligible for real document jobs.
- Archived: retained for history but no longer edited.
The essential rule is that a published version cannot be silently rewritten.
What belongs in a version?
Version everything that determines the output: structure, styles, expected fields, stable language, referenced assets, sample data and the change note. If a font or logo can change independently, retain its exact reference as well.
A number is not enough. The version must remain linked to the generated document or job so an incident can be explained weeks later.
Review and changelog
Describe impact, not only activity. “Moved a block” says little. “Prevents the customer address from flowing onto page two” gives reviewers a testable reason.
Review several payloads: normal, minimal and extreme. Regulated documents also require the appropriate legal or domain reviewer; tooling does not replace that responsibility.
Restore without rewriting history
A rollback should not delete the defective version. Create a new version from the last stable state and retain a link to its source. The timeline then records the change, incident, decision and restoration.
This also avoids changing evidence associated with documents that have already been produced.
Named environments
As the system matures, aliases such as dev, staging and prod can promote a version without changing client code. An alias points at an immutable version; promotion changes the pointer, not the template.
This becomes valuable when several applications consume one document model.
Governance checklist
- Published versions are immutable.
- Every generation retains a version identifier.
- Changelogs describe expected impact.
- Review uses several data fixtures.
- Restore creates a traceable new event.
- Publication permission is restricted.
- Old versions follow a defined retention policy.
Frequently asked questions
Should templates use semantic versioning?
Not necessarily. Major, minor and patch labels become useful when data schemas are compared automatically. Before that, sequential versions and disciplined changelogs already create substantial value.
Can an old version be deleted?
Avoid deleting a version used by real documents. Archive it and apply a retention policy consistent with your obligations.