Versioning and Branch Governance
Versioning and Branch Governance
Purpose
Versioning is a recovery and traceability system, not ceremony.
The exact implementation may be Git, snapshots, numbered releases, dated artifacts, controlled archives, or another project-appropriate mechanism.
Git Baseline
Use:
- main/stable branch for validated work
- feature or change branches for meaningful isolated work
- commits for coherent recoverable states
- tags/releases for important milestones
Avoid:
- giant unreviewable commits
- meaningless commit spam
- forceful history rewriting without necessity
- deleting branches that contain the only recoverable state
- merging unvalidated structural changes
Branch Decision Rule
Create an isolated branch or checkpoint when a change can materially alter:
- architecture
- public interfaces
- data formats
- major dependencies
- many files
- deployment or build behavior
- persistent project structure
Do not create a branch for every trivial typo fix.
Pre-change Checklist
Before a risky change:
- inspect current status
- confirm current branch/state
- ensure unrelated user work is not accidentally included
- establish recovery point
- define validation criteria
- perform change
- inspect diff/status
- validate
- merge or retain branch as appropriate
Non-Code Projects
Use semantic equivalents:
v0.1,v0.2,v1.0- dated releases
- approved/review states
- snapshots
- controlled archive directories
- changelog or decision records
Do not use filenames like final-final-2 as a substitute for lifecycle
management.
Rollback Principle
A rollback path must answer:
- what state is known-good?
- how do we return to it?
- what work would be lost?
- what evidence confirms the rollback is complete?
When the answer is unclear, the change is not safely governed yet.