Versioning & Release Policy
Document: 38-versioning-release-policy.md
Version: 1.0.0
Purpose
This document defines the versioning and release standards used across all Rundown projects.
Versioning provides a structured method for identifying application changes over time. Release management ensures that updates are planned, documented, tested, and deployed in a predictable and traceable manner.
A consistent release policy improves reliability, simplifies maintenance, and supports long-term software evolution.
Release Philosophy
Every release is a recorded engineering decision.
Production releases should be:
-
Planned
-
Documented
-
Tested
-
Traceable
-
Reproducible
A release represents a verified improvement to the application rather than simply a deployment of new code.
Versioning Standard
Rundown standardizes on Semantic Versioning (SemVer).
Version format:
MAJOR.MINOR.PATCH
Example:
1.4.2
Version Definitions
MAJOR
Increment when introducing:
-
Breaking changes
-
Significant architectural changes
-
Major redesigns
-
Incompatible API changes
Example:
1.8.4 → 2.0.0
MINOR
Increment when introducing:
-
New features
-
New functionality
-
Backward-compatible improvements
-
New integrations
Example:
1.4.2 → 1.5.0
PATCH
Increment when introducing:
-
Bug fixes
-
Security fixes
-
Performance improvements
-
Minor refinements
Example:
1.4.2 → 1.4.3
Release Types
Typical release categories include:
Feature Release
Introduces new capabilities.
Maintenance Release
Improves stability, dependencies, and security.
Hotfix
Addresses urgent production issues.
Hotfixes should remain narrowly focused and receive post-release review.
Release Workflow
Every release follows the same workflow.
Development
↓
Quality Assurance
↓
Version Assignment
↓
Release Notes
↓
Production Deployment
↓
Verification
↓
Monitoring
Each release should complete successfully before the next begins.
Release Notes
Every release should include:
-
Version number
-
Release date
-
Summary
-
New features
-
Bug fixes
-
Breaking changes
-
Upgrade considerations (when applicable)
Release notes provide a historical record of application evolution.
Git Tagging
Every production release should be tagged in Git.
Example:
v1.4.2
Git tags should correspond directly with deployed application versions.
Changelog
Every project should maintain a changelog.
The changelog should summarize:
-
Releases
-
Features
-
Improvements
-
Fixes
-
Breaking changes
The changelog complements detailed release notes.
Rollback
Every release should support rollback through the deployment strategy defined in:
27-deployment-workflow.md
Rollback procedures should be verified before production deployment.
Communication
Clients should be informed of significant releases when appropriate.
Communication may include:
-
New functionality
-
Maintenance activities
-
Scheduled downtime (if any)
-
Security improvements
-
Operational impact
Communication should focus on user value rather than implementation details.
Engineering Decision
Semantic Versioning Standard
Status: Accepted
Decision
All Rundown applications follow Semantic Versioning for production releases.
Reasoning
Semantic Versioning:
-
Improves predictability.
-
Simplifies maintenance.
-
Supports long-term evolution.
-
Makes releases easier to understand.
-
Aligns with established industry practices.
Release Checklist
Before releasing a new version, verify:
-
QA completed.
-
Version assigned.
-
Release notes written.
-
Changelog updated.
-
Git tag created.
-
Deployment approved.
-
Production verified.
-
Monitoring reviewed.
Summary
Versioning and release management provide the operational discipline required to evolve software safely and predictably.
By treating every release as a documented engineering decision, Rundown maintains clear software history, improves operational reliability, and enables confident long-term maintenance.
Related Documents
Related ADRs
- ADR-003: Documentation Information Architecture