List view
Major version 1.0.0 release with breaking changes
No due date•0/8 issues closed## v2.0.0 - Flexible Versioning System **Status:** 📋 Planning **Theme:** Revolutionary versioning flexibility with metadata-rich migrations --- ## 🎯 Vision Transform MSR from timestamp-only versioning to a **flexible, strategy-based versioning system** that supports: - Multiple versioning strategies (timestamp, semver, custom patterns) - Rich metadata embedded in migration files - Version information in filenames OR file content - Configurable performance modes with caching - Foundation for advanced tooling and CI/CD integration **This is a major architectural evolution** - v2.0.0 reflects breaking changes and new capabilities. --- ## 🌟 Core Innovation **Version information can live in TWO places:** 1. **Filename-based** (traditional, fast): ``` V202501220400_create_users.ts v1.2.3_add_auth.sql ``` 2. **Content-based** (flexible, metadata-rich): ```typescript // TypeScript export default class implements IRunnableScript { protected version = '1.3.4'; metadata = { author: '[email protected]', tags: ['users', 'auth'], ticket: 'JIRA-1234' }; } ``` ```sql -- SQL -- VERSION=v1.2.3 -- [email protected] -- TAGS=schema,performance CREATE TABLE ... ``` --- ## 📦 Three-Phase Delivery ### **Phase 1: Metadata Foundation** (#TBD) **Goal:** Add rich metadata support while keeping current timestamp approach **Deliverables:** - `IMigrationMetadata` interface with structured core + custom fields - Metadata extraction from TypeScript/SQL/YAML files - Metadata available in hooks, execution summaries, IMigrationInfo - Documentation and conventions **Value:** 80% of metadata benefits, 25% of complexity **Estimated Effort:** 2-3 weeks --- ### **Phase 2: Filename Pattern Flexibility** (#TBD) **Goal:** Support multiple versioning strategies via filenames **Deliverables:** - `IVersioningStrategy` interface and registry - Built-in strategies: Timestamp, Semver, Custom patterns - Strategy configuration with auto-detection - Enhanced validation for each strategy - Migration guide for switching strategies **Value:** Release-based migrations, custom naming conventions **Estimated Effort:** 3-4 weeks --- ### **Phase 3: Content-Based Versioning** (#TBD) **Goal:** Extract version from file content with configurable performance **Deliverables:** - TypeScript AST parser for `protected version` property - SQL comment parser for `-- VERSION=` markers - YAML/JSON field parsers - Configurable modes: Fast (filename) vs Rich (content) - Optional disk caching for parsed data - Complete flexibility achieved **Value:** Ultimate flexibility, foundation for generator tooling **Estimated Effort:** 3-4 weeks --- ## 🎨 Design Principles ### ✅ Decided 1. **Breaking changes acceptable** - v2.0.0 allows clean design 2. **One strategy per project** - Simpler mental model (no mixed formats) 3. **Hybrid discovery** - Config default + auto-detect + file override 4. **Schema evolution** - Keep `version` separate + add `metadata` column 5. **Configurable performance** - Fast mode vs Rich mode with caching 6. **Hybrid metadata** - Structured core fields + custom extension point ### 🎯 Priorities (User-Ranked) 1. **Rich metadata** - CI/CD, observability (HIGHEST) 2. **Release-based versioning** - Semver support 3. **Custom patterns** - Naming flexibility 4. **Multi-team merging** - Conflict resolution (LOWEST) --- ## 💡 Strategic Value ### Why This Matters **Current limitation:** MSR forces timestamp-based versioning - Works well for continuous development - Doesn't match release-based workflows - Limited metadata for CI/CD integration - No flexibility for custom patterns **After v2.0.0:** MSR becomes the **most flexible migration tool** - ✅ Timestamp OR Semver OR Custom patterns - ✅ Rich metadata for observability - ✅ Foundation for advanced tooling - ✅ Generator (#83) builds on this architecture ### Competitive Differentiation - **Flyway:** Fixed numeric versioning - **Liquibase:** XML/YAML only, rigid structure - **Rails Migrations:** Timestamps only - **Alembic:** Limited flexibility - **MSR v2.0.0:** User-choice driven, strategy-based ✨ --- ## 🏗️ Architecture Overview ```typescript // Core interfaces interface IVersioningStrategy { name: string; extractVersion(file: string): string | Promise<string>; extractMetadata(file: string): IMigrationMetadata | Promise<IMigrationMetadata>; compareVersions(v1: string, v2: string): number; validate(version: string): boolean; } interface IMigrationMetadata { // Structured core (typed) author?: string; tags?: string[]; ticket?: string; description?: string; dependencies?: string[]; rollbackPolicy?: RollbackStrategy; // Free-form extension custom?: Record<string, any>; } // Configuration config.versioning = { strategy: 'timestamp' | 'semver' | 'content-based' | IVersioningStrategy, mode: 'fast' | 'rich', cache: true, autoDetect: true }; ``` --- ## 📊 Success Criteria v2.0.0 is successful if: 1. ✅ Users can choose versioning strategy (timestamp, semver, custom) 2. ✅ Metadata is accessible in hooks and execution summaries 3. ✅ Performance modes meet expectations (fast ≤50ms, rich ≤500ms for 500 files) 4. ✅ Schema version table stores version + metadata 5. ✅ Documentation includes migration guide from v0.x/v1.x 6. ✅ All 3 phases delivered and tested 7. ✅ 100% test coverage maintained 8. ✅ Foundation ready for generator package (#83) --- ## 🚫 Out of Scope Explicitly NOT included in v2.0.0: - ❌ Mixed strategy per project (future: transition support) - ❌ Automatic strategy migration tooling (manual for v2.0.0) - ❌ Multi-team conflict resolution (Phase 4?) - ❌ Migration generator (#83) - separate package - ❌ Visual migration timeline/dashboard - ❌ Dependency graph execution These may come in future versions based on feedback. --- ## 🔗 Related Work ### Dependencies - None - this is foundational work ### Unlocks - **#83** - Migration Generator (builds on versioning + metadata) - **Future:** Migration analytics dashboard - **Future:** CI/CD template integrations - **Future:** Dependency graph execution --- ## 📈 Estimated Timeline - **Phase 1 (Metadata):** 2-3 weeks - **Phase 2 (Filename patterns):** 3-4 weeks - **Phase 3 (Content-based):** 3-4 weeks - **Testing & Documentation:** 2 weeks - **Beta period:** 2-3 weeks **Total:** ~12-16 weeks from start to stable release --- ## 🎯 Release Approach 1. **Planning:** Define detailed specs for each phase 2. **Phase 1:** Metadata foundation (can ship independently) 3. **Phase 2:** Filename patterns (builds on Phase 1) 4. **Phase 3:** Content-based (completes vision) 5. **Beta:** v2.0.0-beta.x releases for community testing 6. **GA:** v2.0.0 stable release --- **Target:** Q2 2025 **Breaking Changes:** Yes - v2.0.0 allows clean architecture
No due date•0/6 issues closed## Backlog - Future Improvements **Status:** 📦 Parked This milestone contains ideas and improvements that are postponed indefinitely. These issues are valid but not prioritized for any specific release. ### Purpose - Keep good ideas documented without cluttering active milestones - Track community requests that may be revisited later - Maintain a list of "someday/maybe" improvements ### How Issues Get Here - Low priority features - Nice-to-have improvements - Community suggestions not yet prioritized - Experimental ideas requiring more research ### Moving Out of Backlog Issues can be moved to active milestones when: - Community demand increases - Resources become available - Dependencies are resolved - Strategic alignment changes --- **Note:** Issues in Backlog have no target date and may never be implemented.
No due date•0/12 issues closed