5. Shape Versioning Roadmap
Forge 0.9.0 includes:
- shape notes
- template refinement
- shape lint
- dry-run repair
- applied repair
- repair history
Shape versioning itself is still considered a roadmap feature rather than a finalized system.
Right now, Forge focuses on helping Shapes evolve safely and visibly instead of trying to automate complex template migrations silently.
Why Shape Versioning Matters
Templates naturally evolve over time.
Examples:
- new sections added
- old sections retired
- workflows reorganized
- recurring headings renamed
- operational structure refined
Without version tracking, older notes gradually drift away from newer structures.
Shape versioning helps make those transitions intentional instead of accidental.
Current Recommended Pattern
Until first-class versioning lands, the recommended approach is lightweight and explicit.
Include a version field inside shape notes or templates:
shape_version: "1.0"
Then track structural changes using a visible changelog section.
Example:
# Changelog
## 1.1
- Added `## Review Notes`
- Kept `## Sources` unchanged
## 1.0
- Initial project structure
This keeps structural evolution understandable for humans instead of hiding it behind opaque migration logic.
Recommended Migration Workflow
When changing a Shape:
- Update the shape note
- Refine the template
- Run Shape Lint on a small folder scope
- Run Shape Repair dry run
- Review proposed repairs carefully
- Apply repair to a limited scope
- Expand scope gradually after validation
Small controlled migrations are usually safer than full-vault structural rewrites.
Why Gradual Migration Matters
Large structural changes can affect:
- Dataview dashboards
- Bases
- exports
- AI workflows
- linked operational systems
- downstream automation
Gradual rollout helps catch:
- broken assumptions
- unexpected heading drift
- workflow mismatches
- template edge cases
before they spread across the entire vault.
Shapes as Evolving Systems
A useful Shape is not a frozen contract forever.
Good Shapes evolve alongside real workflows.
Overly rigid templates often become abandoned because people stop wanting to use them.
The goal is:
- stable structure
- predictable organization
- sustainable evolution
not perfection.
Relationship to Shape Repair
Shape Repair works best when template changes are incremental.
Small changes are easier to:
- preview
- validate
- repair safely
- roll back if needed
This is why Forge emphasizes:
- dry runs
- repair previews
- backups
- reviewable operations
instead of aggressive automatic restructuring.
Future Direction
Future versions of Forge may eventually support:
- explicit shape version tracking
- note-to-template version matching
- migration-aware repair workflows
- template lineage
- shape upgrade plans
- staged structural migrations
For now, the recommended approach is to keep Shape evolution:
- deliberate
- reviewable
- gradual
- visible inside the vault
Recommended Philosophy
Treat Shapes like long-lived operational templates.
Small stable structures usually age better than giant deeply nested template systems.
When in doubt:
- simplify
- evolve gradually
- validate often
- repair carefully
Your future self will probably appreciate fewer template dragons.
