diff --git a/.github/upgrades/scenarios/new-dotnet-version_02bc64/plan.md b/.github/upgrades/scenarios/new-dotnet-version_02bc64/plan.md deleted file mode 100644 index 91dee68f..00000000 --- a/.github/upgrades/scenarios/new-dotnet-version_02bc64/plan.md +++ /dev/null @@ -1,2716 +0,0 @@ -# .NET 11.0 (PREVIEW) Upgrade Plan - -## Table of Contents -1. [Executive Summary](#executive-summary) -2. [Migration Strategy](#migration-strategy) -3. [Detailed Dependency Analysis](#detailed-dependency-analysis) -4. [Project-by-Project Plans](#project-by-project-plans) -5. [Risk Management](#risk-management) -6. [Testing & Validation Strategy](#testing--validation-strategy) -7. [Complexity & Effort Assessment](#complexity--effort-assessment) -8. [Source Control Strategy](#source-control-strategy) -9. [Success Criteria](#success-criteria) - ---- - -## Executive Summary - -### Scenario Overview -This plan details the upgrade of the Jellyfin media server solution from .NET 9.0 to **.NET 11.0 (PREVIEW)**, encompassing 41 projects (40 application projects plus 1 analyzer project targeting netstandard2.0). - -### Scope -- **Projects to Upgrade**: 40 projects (main codebase) -- **Projects Unchanged**: 1 project (Jellyfin.CodeAnalysis - netstandard2.0 analyzer) -- **Total Lines of Code**: Estimated 200,000+ LOC across solution -- **Project Types**: ASP.NET Core web applications, class libraries, test projects -- **Current Framework**: .NET 9.0 -- **Target Framework**: .NET 11.0 (PREVIEW) - -### Discovered Metrics -- **Total Projects**: 41 -- **Dependency Depth**: 12 levels (from leaf to top-level test projects) -- **Circular Dependencies**: None detected -- **Critical Path Length**: 12 project levels -- **NuGet Packages**: 80 total packages -- **Package Compatibility**: ✅ **100% compatible** - All packages already support .NET 11.0 -- **Security Vulnerabilities**: None detected in current packages -- **Breaking Changes**: No mandatory breaking changes identified by assessment -- **Risk Indicators**: - - Large, complex solution with deep dependency chains - - Preview framework (not production-ready) - - Heavy use of Entity Framework Core and ASP.NET Core - - Database providers (PostgreSQL, SQLite) require careful testing - -### Complexity Classification: **Complex** - -**Justification:** -- **42 projects** exceeds medium threshold (>15 projects) -- **12-level dependency depth** exceeds complexity threshold (>4 levels) -- **No high-risk issues** detected (0 mandatory issues) -- **No security vulnerabilities** in current packages -- **Complex technology stack**: EF Core, ASP.NET Core, multiple database providers, media processing -- **Preview framework target**: .NET 11.0 is not yet released (preview stability concerns) - -Despite the absence of breaking changes or compatibility issues, the solution's **size, depth, and preview framework target** classify this as a **Complex** upgrade requiring careful, phased execution. - -### Selected Strategy: Bottom-Up (Dependency-First) Approach - -**Rationale:** -- **Large solution** (41 projects) benefits from incremental validation -- **Deep dependency tree** (12 levels) requires stable foundation before building upward -- **Preview framework** introduces unknown risks best addressed incrementally -- **Database providers** in mid-levels need thorough testing before application tier -- **Test projects** at multiple levels enable validation after each tier -- **Zero breaking changes** identified, but preview framework may introduce runtime issues -- **Risk-averse approach** appropriate for production media server moving to preview framework - -### Critical Considerations -1. **Preview Framework**: .NET 11.0 is not production-ready; expect potential instability -2. **Package Ecosystem**: While packages report compatibility, preview framework behavior may differ -3. **Database Providers**: PostgreSQL and SQLite providers need extensive testing with .NET 11.0 -4. **Media Processing**: SkiaSharp and media encoding libraries require validation -5. **Performance**: Monitor for performance regressions in preview builds -6. **Breaking Changes**: May emerge during testing despite clean analysis - -### Expected Remaining Iterations -Based on complexity classification and solution structure: -- **Phase 1**: Complete (Discovery & Classification) -- **Phase 2**: 3 iterations (Foundation planning) -- **Phase 3**: 8-10 iterations (Tier-by-tier detailed planning) -- **Total**: ~11-13 iterations to complete plan - -## Migration Strategy - -### Approach Selection: Bottom-Up (Dependency-First) - -**Decision: Incremental tier-by-tier migration** starting from leaf nodes (Tier 2) progressing to top-level application (Tier 11) and tests (Tiers 12-13). - -### Rationale for Bottom-Up Strategy - -#### Why Bottom-Up is Optimal for This Solution - -1. **Large Solution Scale** - - 41 projects exceed threshold for coordinated migration (>15 projects) - - Incremental approach reduces risk of simultaneous failures - - Enables validation at each tier before proceeding - -2. **Deep Dependency Hierarchy** - - 12 levels of dependencies require stable foundation - - Bottom-up ensures each project builds on already-upgraded, tested tier - - No multi-targeting complexity (all projects move to .NET 11.0) - -3. **Preview Framework Target** - - .NET 11.0 is PREVIEW (not production-ready) - - Unknown risks best addressed incrementally - - Early tiers expose framework issues before touching applications - - Allows retreat/adjustment if preview proves unstable - -4. **Clear Dependency Structure** - - DAG (no circular dependencies) enables clean bottom-up flow - - Well-defined tiers with explicit between-tier dependencies - - Each tier can be independently validated - -5. **Critical Database Layer** - - Database providers (Tier 6) require extensive testing - - Must be stable before business logic (Tier 8+) - - Early validation prevents cascading failures - -6. **Test Projects Throughout** - - Test projects in Tiers 3, 5, 7, 9, 12, 13 enable continuous validation - - Each tier completion includes test execution - - Fail-fast at lowest affected tier - -### Alternative Approaches Considered - -#### ❌ All-At-Once Migration -**Rejected because:** -- 41 projects too large for coordinated update -- Preview framework introduces unknown risks -- Single-shot approach would complicate debugging -- Complex solution requires staged validation - -#### ❌ Top-Down (Application-First) -**Rejected because:** -- Would require multi-targeting all dependencies -- Increased complexity managing two framework versions -- Testing top tiers before infrastructure ready is risky -- Database providers must be stable before applications use them - -### Bottom-Up Execution Principles - -#### Strict Tier Ordering -1. ✅ **Must complete Tier N before starting Tier N+1** -2. ✅ **Tier completion = all projects built, tested, validated** -3. ✅ **No tier skipping** - even if tempting to fast-track -4. ✅ **Rollback at tier level** - if tier fails, revert entire tier - -#### Within-Tier Execution -- **Projects within same tier can be upgraded in parallel** (no inter-dependencies) -- **Batch project file updates** for entire tier (single operation) -- **Batch package updates** for entire tier (single operation) -- **Test tier as a whole** before proceeding -- **Tier 8** (12 projects) is largest; can parallelize to speed up - -#### Tier Completion Criteria -Each tier must meet criteria before proceeding: - -1. **Build Success** - - All projects in tier build without errors - - All projects in tier build without warnings (target: zero warnings) - -2. **Package Restoration** - - All NuGet packages restore successfully - - No package dependency conflicts - -3. **Test Execution** - - All test projects in tier pass (if tier contains tests) - - Tests for lower tiers still pass (regression check) - -4. **Code Quality** - - No new compiler errors introduced - - Code analysis passes (StyleCop, analyzers) - -5. **Validation Review** - - Manual review of any unexpected changes - - Verification of preview framework behavior - -### Dependency-Based Ordering Details - -#### Foundation First (Tiers 2-4) -- **Tier 2**: Core infrastructure (Database.Implementations, Extensions, Keyframes) -- **Tier 3**: Data models (Jellyfin.Data) -- **Tier 4**: Shared models (MediaBrowser.Model) - -**Rationale**: These are referenced by all higher tiers. Must be rock-solid. - -#### Infrastructure & Providers (Tiers 5-7) -- **Tier 5**: Common utilities (MediaBrowser.Common) -- **Tier 6**: Database providers (PostgreSQL, SQLite), Naming -- **Tier 7**: Controller abstractions - -**Rationale**: Database providers are critical infrastructure requiring extensive testing before business logic. - -#### Business Logic (Tiers 8-10) -- **Tier 8**: Business logic, media processing, networking (12 projects) -- **Tier 9**: API layer and business tests (8 projects) -- **Tier 10**: Server implementations (2 projects) - -**Rationale**: Business logic depends on stable infrastructure; can parallelize within Tier 8. - -#### Applications & Tests (Tiers 11-13) -- **Tier 11**: Main application (Jellyfin.Server) -- **Tier 12**: Integration tests -- **Tier 13**: Final implementation tests - -**Rationale**: Applications last; integration tests validate entire stack. - -### Parallel vs. Sequential Execution - -#### Sequential (Between Tiers) -- **All tiers execute sequentially** - Tier N+1 waits for Tier N completion -- **No exceptions** - even for small tiers -- **Validation between tiers** - ensures stability before proceeding - -#### Parallel (Within Tier) -Projects within same tier can execute in parallel: - -- **Tier 2** (3 projects): Can parallelize -- **Tier 3** (2 projects): Can parallelize -- **Tier 5** (3 projects): Can parallelize -- **Tier 6** (3 projects): Can parallelize -- **Tier 7** (2 projects): Can parallelize -- **Tier 8** (12 projects): **High parallelism potential** - largest tier -- **Tier 9** (8 projects): Can parallelize (all tests) -- **Tier 10** (2 projects): Can parallelize -- **Tier 12** (2 projects): Can parallelize - -**Parallelization Guidelines:** -- Update project files for all tier projects simultaneously -- Run builds in parallel (if resources allow) -- Aggregate results before proceeding to tests -- Test tier as a cohesive unit (not per-project) - -### Phase Definitions - -The migration consists of **13 phases** (one per tier): - -#### Phase 1: Core Infrastructure (Tier 2) -- **Projects**: 3 -- **Focus**: Database implementations, extensions, keyframe encoding -- **Validation**: Unit tests in Tier 3 - -#### Phase 2: Data Layer (Tier 3) -- **Projects**: 2 -- **Focus**: Data models, first test validation -- **Validation**: Jellyfin.MediaEncoding.Keyframes.Tests - -#### Phase 3: Model Layer (Tier 4) -- **Projects**: 1 -- **Focus**: Central model definitions -- **Validation**: Model tests in Tier 5 - -#### Phase 4: Common Utilities (Tier 5) -- **Projects**: 3 -- **Focus**: Common utilities, model validation tests -- **Validation**: Jellyfin.Extensions.Tests, Jellyfin.Model.Tests - -#### Phase 5: Database Providers (Tier 6) -- **Projects**: 3 -- **Focus**: PostgreSQL, SQLite providers; naming -- **Validation**: Extensive database integration tests (manual + automated) - -#### Phase 6: Controller Layer (Tier 7) -- **Projects**: 2 -- **Focus**: Controller abstractions, naming tests -- **Validation**: Jellyfin.Naming.Tests - -#### Phase 7: Business Logic (Tier 8) -- **Projects**: 12 (largest phase) -- **Focus**: Photos, drawing, networking, media encoding, providers, server infrastructure -- **Validation**: Controller tests + business logic validation - -#### Phase 8: API & Tests (Tier 9) -- **Projects**: 8 -- **Focus**: Jellyfin.Api and comprehensive test suite for Tier 8 -- **Validation**: All Tier 9 tests pass - -#### Phase 9: Server Implementation (Tier 10) -- **Projects**: 2 -- **Focus**: Emby.Server.Implementations, Jellyfin.Api.Tests -- **Validation**: API tests pass - -#### Phase 10: Main Application (Tier 11) -- **Projects**: 1 -- **Focus**: Jellyfin.Server (main entry point) -- **Validation**: Application starts and responds - -#### Phase 11: Integration Tests (Tier 12) -- **Projects**: 2 -- **Focus**: End-to-end integration tests -- **Validation**: All integration tests pass - -#### Phase 12: Final Validation (Tier 13) -- **Projects**: 1 -- **Focus**: Jellyfin.Server.Implementations.Tests -- **Validation**: Complete solution test suite passes - -#### Phase 13: Solution Validation -- **Projects**: All 40 upgraded projects -- **Focus**: Full solution build, all tests, smoke testing -- **Validation**: Comprehensive validation before completion - -### Risk Mitigation for Bottom-Up Strategy - -#### Early Failure Detection -- Tier 2-4 failures detected before touching 90% of solution -- Database provider issues (Tier 6) caught before business logic -- Test projects throughout enable continuous validation - -#### Preview Framework Risks -- Tier 2 upgrade exposes .NET 11.0 preview issues earliest -- Can assess framework stability before committing all projects -- Option to pause/revert if preview proves problematic - -#### Incremental Learning -- Early tiers teach team about .NET 11.0 behavior -- Lessons learned applied to later tiers -- Compilation/runtime patterns identified early - -#### Staged Deployment -- Can deploy lower tiers to staging environment incrementally -- Early performance/compatibility testing -- Risk distributed across multiple phases vs. single big-bang - -### Rollback Strategy - -#### Tier-Level Rollback -- If Tier N fails validation: - 1. Revert all Tier N project file changes - 2. Restore Tier N packages to .NET 9.0 versions - 3. Validate Tiers 1-(N-1) still stable - 4. Analyze failure, adjust plan - 5. Retry Tier N - -#### Solution-Level Rollback -- If preview framework proves unstable: - 1. Git revert to upgrade branch start - 2. Document .NET 11.0 PREVIEW issues - 3. Consider alternative target (.NET 10.0 LTS) - -### Success Criteria Per Phase - -Each phase must achieve: -1. ✅ All projects build without errors -2. ✅ All projects build without warnings -3. ✅ All test projects pass (100% pass rate) -4. ✅ No package dependency conflicts -5. ✅ Code analysis passes -6. ✅ Manual validation complete (for critical tiers) -7. ✅ Performance acceptable (for application tiers) - -Only when all criteria met, proceed to next phase. - -## Detailed Dependency Analysis - -### Dependency Graph Structure - -The Jellyfin solution exhibits a **12-level dependency hierarchy** with clear separation between infrastructure, domain, and application layers. The graph follows a bottom-up structure ideal for tier-based migration. - -``` -Tier 1 (Level 0): Foundation - Analyzer - └─ Jellyfin.CodeAnalysis (netstandard2.0) - NO UPGRADE - -Tier 2 (Level 1): Core Infrastructure - ├─ Jellyfin.Database.Implementations - ├─ Jellyfin.Extensions - └─ Jellyfin.MediaEncoding.Keyframes - -Tier 3 (Level 2): Data & Encoding - ├─ Jellyfin.Data - └─ Jellyfin.MediaEncoding.Keyframes.Tests - -Tier 4 (Level 3): Model Layer - └─ MediaBrowser.Model - -Tier 5 (Level 4): Model Tests & Common Layer - ├─ Jellyfin.Extensions.Tests - ├─ Jellyfin.Model.Tests - └─ MediaBrowser.Common - -Tier 6 (Level 5): Domain & Database Providers - ├─ Emby.Naming - ├─ Jellyfin.Database.Providers.Postgres - └─ Jellyfin.Database.Providers.Sqlite - -Tier 7 (Level 6): Controller & Naming Tests - ├─ Jellyfin.Naming.Tests - └─ MediaBrowser.Controller - -Tier 8 (Level 7): Business Logic & Drawing - ├─ Emby.Photos - ├─ Jellyfin.Controller.Tests - ├─ Jellyfin.Drawing - ├─ Jellyfin.Drawing.Skia - ├─ Jellyfin.LiveTv - ├─ Jellyfin.MediaEncoding.Hls - ├─ Jellyfin.Networking - ├─ Jellyfin.Server.Implementations - ├─ MediaBrowser.LocalMetadata - ├─ MediaBrowser.MediaEncoding - ├─ MediaBrowser.Providers - └─ MediaBrowser.XbmcMetadata - -Tier 9 (Level 8): API & Business Tests - ├─ Jellyfin.Api - ├─ Jellyfin.Common.Tests - ├─ Jellyfin.LiveTv.Tests - ├─ Jellyfin.MediaEncoding.Hls.Tests - ├─ Jellyfin.MediaEncoding.Tests - ├─ Jellyfin.Networking.Tests - ├─ Jellyfin.Providers.Tests - └─ Jellyfin.XbmcMetadata.Tests - -Tier 10 (Level 9): Server Implementation - ├─ Emby.Server.Implementations - └─ Jellyfin.Api.Tests - -Tier 11 (Level 10): Main Application - └─ Jellyfin.Server - -Tier 12 (Level 11): Integration Tests - ├─ Jellyfin.Server.Integration.Tests - └─ Jellyfin.Server.Tests - -Tier 13 (Level 12): Final Test Layer - └─ Jellyfin.Server.Implementations.Tests -``` - -### Tier Grouping Strategy - -Based on the Bottom-Up Strategy and dependency analysis, projects are grouped into **13 tiers** for migration: - -#### Tier 1: Foundation Analyzer (NO MIGRATION) -- **Jellyfin.CodeAnalysis** (netstandard2.0) -- **Dependencies**: None -- **Used By**: All projects (build-time analyzer) -- **Rationale**: Remains on netstandard2.0 for broad compatibility - -#### Tier 2: Core Infrastructure (3 projects) -- **Jellyfin.Database.Implementations** -- **Jellyfin.Extensions** -- **Jellyfin.MediaEncoding.Keyframes** -- **Dependencies**: Only Jellyfin.CodeAnalysis (unchanged) -- **Rationale**: Leaf nodes with no internal dependencies; database and extension infrastructure - -#### Tier 3: Data Layer (2 projects) -- **Jellyfin.Data** -- **Jellyfin.MediaEncoding.Keyframes.Tests** -- **Dependencies**: Tier 2 projects only -- **Rationale**: Data models and first test validation point - -#### Tier 4: Model Layer (1 project) -- **MediaBrowser.Model** -- **Dependencies**: Tier 2 (Extensions) + Tier 3 (Data) -- **Rationale**: Central model definitions used throughout solution - -#### Tier 5: Common Layer (3 projects) -- **Jellyfin.Extensions.Tests** -- **Jellyfin.Model.Tests** -- **MediaBrowser.Common** -- **Dependencies**: Tiers 2-4 -- **Rationale**: Common utilities and model validation tests - -#### Tier 6: Naming & Database Providers (3 projects) -- **Emby.Naming** -- **Jellyfin.Database.Providers.Postgres** -- **Jellyfin.Database.Providers.Sqlite** -- **Dependencies**: Tiers 2-5 -- **Rationale**: Critical database providers requiring extensive testing - -#### Tier 7: Controller Layer (2 projects) -- **Jellyfin.Naming.Tests** -- **MediaBrowser.Controller** -- **Dependencies**: Tiers 2-6 -- **Rationale**: Controller abstractions; naming validation - -#### Tier 8: Business Logic (12 projects) -- **Emby.Photos** -- **Jellyfin.Controller.Tests** -- **Jellyfin.Drawing** -- **Jellyfin.Drawing.Skia** -- **Jellyfin.LiveTv** -- **Jellyfin.MediaEncoding.Hls** -- **Jellyfin.Networking** -- **Jellyfin.Server.Implementations** -- **MediaBrowser.LocalMetadata** -- **MediaBrowser.MediaEncoding** -- **MediaBrowser.Providers** -- **MediaBrowser.XbmcMetadata** -- **Dependencies**: Tiers 2-7 -- **Rationale**: Largest tier; business logic, media processing, networking; can parallelize within tier - -#### Tier 9: API & Tests (8 projects) -- **Jellyfin.Api** -- **Jellyfin.Common.Tests** -- **Jellyfin.LiveTv.Tests** -- **Jellyfin.MediaEncoding.Hls.Tests** -- **Jellyfin.MediaEncoding.Tests** -- **Jellyfin.Networking.Tests** -- **Jellyfin.Providers.Tests** -- **Jellyfin.XbmcMetadata.Tests** -- **Dependencies**: Tiers 2-8 -- **Rationale**: API layer and comprehensive test coverage for Tier 8 - -#### Tier 10: Server Implementation (2 projects) -- **Emby.Server.Implementations** -- **Jellyfin.Api.Tests** -- **Dependencies**: Tiers 2-9 -- **Rationale**: Main server implementation and API validation - -#### Tier 11: Main Application (1 project) -- **Jellyfin.Server** -- **Dependencies**: Tiers 2-10 -- **Rationale**: Entry point application; depends on all business logic - -#### Tier 12: Integration Tests (2 projects) -- **Jellyfin.Server.Integration.Tests** -- **Jellyfin.Server.Tests** -- **Dependencies**: Tier 11 (Jellyfin.Server) -- **Rationale**: End-to-end application validation - -#### Tier 13: Final Test Validation (1 project) -- **Jellyfin.Server.Implementations.Tests** -- **Dependencies**: Tier 12 (Integration.Tests) -- **Rationale**: Final validation of server implementations with integration context - -### Critical Path Analysis - -**Longest Dependency Chain:** -``` -Jellyfin.CodeAnalysis (Level 0) - → Jellyfin.Database.Implementations (Level 1) - → Jellyfin.Data (Level 2) - → MediaBrowser.Model (Level 3) - → MediaBrowser.Common (Level 4) - → Emby.Naming (Level 5) - → MediaBrowser.Controller (Level 6) - → Jellyfin.Server.Implementations (Level 7) - → Emby.Server.Implementations (Level 9) - → Jellyfin.Server (Level 10) - → Jellyfin.Server.Integration.Tests (Level 11) - → Jellyfin.Server.Implementations.Tests (Level 12) -``` - -**Length**: 13 projects (12 upgrade steps, excluding CodeAnalysis) - -**Implications:** -- Any failure in early tiers blocks all downstream projects -- Database layer (Tiers 2-6) is critical foundation -- Server implementation consolidates most dependencies (Tier 10) -- Test projects enable validation at each tier - -### Circular Dependencies - -**Status**: ✅ **None detected** - -The dependency graph is a **Directed Acyclic Graph (DAG)**, enabling clean bottom-up migration. - -### Key Dependency Relationships - -#### High-Fan-Out Projects (Used by Many) -1. **MediaBrowser.Model** (Level 3): Used by 21 projects - - Central model definitions - - Must be stable before progressing -2. **MediaBrowser.Controller** (Level 6): Used by 12 projects - - Core controller abstractions - - Critical stabilization point -3. **MediaBrowser.Common** (Level 4): Used by 10 projects - - Common utilities - - Early tier with wide impact - -#### High-Fan-In Projects (Depend on Many) -1. **Jellyfin.Server** (Level 10): Depends on 9 direct projects - - Main application entry point - - Consolidates all functionality -2. **Emby.Server.Implementations** (Level 9): Depends on 14 direct projects - - Server implementation layer - - Complex integration point -3. **Jellyfin.Server.Implementations** (Level 7): Depends on 6 direct projects - - Server infrastructure - - Database and core implementation - -### Between-Tier Dependencies - -Each tier depends **only** on lower tiers (strict bottom-up): - -- **Tier 2** → Tier 1 (CodeAnalysis only) -- **Tier 3** → Tiers 1-2 -- **Tier 4** → Tiers 1-3 -- **Tier 5** → Tiers 1-4 -- **Tier 6** → Tiers 1-5 -- **Tier 7** → Tiers 1-6 -- **Tier 8** → Tiers 1-7 -- **Tier 9** → Tiers 1-8 -- **Tier 10** → Tiers 1-9 -- **Tier 11** → Tiers 1-10 -- **Tier 12** → Tiers 1-11 -- **Tier 13** → Tiers 1-12 - -**No cross-tier or reverse dependencies** ensure clean migration flow. - -## Project-by-Project Plans - -### Overview - -This section provides detailed migration plans for each project, organized by tier. Each project includes: -- Current and target state -- Migration steps -- Package updates -- Expected breaking changes -- Code modifications -- Testing strategy -- Validation checklist - ---- - -### Tier 1: Foundation Analyzer (NO MIGRATION) - -#### Jellyfin.CodeAnalysis -**Current State**: netstandard2.0 (Roslyn analyzer) -**Target State**: netstandard2.0 (UNCHANGED) -**Migration**: None required - remains on netstandard2.0 for broad compatibility - ---- - -### Tier 2: Core Infrastructure - -#### Overview -**Projects**: 3 -**Complexity**: Medium -**Risk**: High (first preview framework exposure) -**Effort**: Medium - -This tier establishes the foundation infrastructure: database implementations, extension utilities, and media encoding keyframe support. As the first tier to migrate, it serves as the **early warning system** for .NET 11.0 preview issues. - ---- - -#### Jellyfin.Database.Implementations - -**Current State**: -- **Framework**: .NET 9.0 -- **Type**: Class Library -- **Dependencies**: Jellyfin.CodeAnalysis (unchanged) -- **Used By**: 6 projects (Data layer, database providers, server implementations) -- **Packages**: Microsoft.EntityFrameworkCore 11.0.0-preview.1 (already upgraded) -- **Risk Level**: High (foundation for all data access) - -**Target State**: -- **Framework**: .NET 11.0 -- **Type**: Class Library -- **Dependencies**: No changes -- **Package Changes**: None required (already on .NET 11.0-compatible versions) - -**Migration Steps**: - -1. **Prerequisites** - - ✅ Jellyfin.CodeAnalysis remains unchanged (netstandard2.0) - - ✅ .NET 11.0 SDK installed and verified - - ✅ Backup current solution state - -2. **Framework Update** - - Update `Jellyfin.Database.Implementations.csproj`: - ```xml - net11.0 - ``` - - No other project file changes needed - -3. **Package Updates** - - **All packages already compatible** - no updates required: - - Microsoft.EntityFrameworkCore: 11.0.0-preview.1 ✅ - - Microsoft.EntityFrameworkCore.Relational: 11.0.0-preview.1 ✅ - - Microsoft.EntityFrameworkCore.Design: 11.0.0-preview.1 ✅ - -4. **Expected Breaking Changes** - - ✅ **None identified** by assessment - - ⚠️ **Monitor for**: EF Core 11.0 preview query translation changes - - ⚠️ **Monitor for**: Database provider behavior changes - -5. **Code Modifications** - - **Expected**: None required - - **Potential**: - - EF Core API changes (preview-specific) - - Query translation adjustments - - Migration compatibility - -6. **Testing Strategy** - - **Build Validation**: - - Project builds without errors ✅ - - Zero warnings target ✅ - - Code analysis passes ✅ - - - **Dependency Validation**: - - NuGet restore successful ✅ - - No package conflicts ✅ - - - **Functional Testing**: - - Database context initialization ✅ - - Basic CRUD operations (deferred to Tier 6 with providers) - - - **Performance Baseline**: - - Establish .NET 11.0 build performance metrics - - Compare against .NET 9.0 baseline - -7. **Validation Checklist** - - [ ] Project file updated to net11.0 - - [ ] Build succeeds without errors - - [ ] Build succeeds without warnings - - [ ] NuGet packages restore successfully - - [ ] No dependency conflicts - - [ ] Code analysis passes (StyleCop, IDisposableAnalyzers, etc.) - - [ ] Database context classes compile - - [ ] No compiler warnings about obsolete APIs - - [ ] EF Core design-time tools work (if applicable) - ---- - -#### Jellyfin.Extensions - -**Current State**: -- **Framework**: .NET 9.0 -- **Type**: Class Library -- **Dependencies**: Jellyfin.CodeAnalysis (unchanged) -- **Used By**: MediaBrowser.Model, Jellyfin.Extensions.Tests -- **Packages**: Minimal (mostly BCL) -- **Risk Level**: Low (simple utility library) - -**Target State**: -- **Framework**: .NET 11.0 -- **Type**: Class Library -- **Dependencies**: No changes -- **Package Changes**: None required - -**Migration Steps**: - -1. **Prerequisites** - - ✅ .NET 11.0 SDK available - - ✅ No external package dependencies to validate - -2. **Framework Update** - - Update `Jellyfin.Extensions.csproj`: - ```xml - net11.0 - ``` - -3. **Package Updates** - - **None required** - uses BCL only - -4. **Expected Breaking Changes** - - ✅ **None expected** - - Simple extension methods and utilities - - Minimal BCL surface area - -5. **Code Modifications** - - **Expected**: None - - **Potential**: None anticipated - -6. **Testing Strategy** - - **Build Validation**: - - Build without errors/warnings ✅ - - Code analysis passes ✅ - - - **Unit Testing**: - - Deferred to Tier 5 (Jellyfin.Extensions.Tests) - - - **API Compatibility**: - - Extension methods compile without changes ✅ - - No obsolete API usage ✅ - -7. **Validation Checklist** - - [ ] Project file updated to net11.0 - - [ ] Build succeeds without errors - - [ ] Build succeeds without warnings - - [ ] No package dependencies to update - - [ ] Extension methods compile cleanly - - [ ] Code analysis passes - - [ ] No breaking changes in BCL APIs used - ---- - -#### Jellyfin.MediaEncoding.Keyframes - -**Current State**: -- **Framework**: .NET 9.0 -- **Type**: Class Library -- **Dependencies**: Jellyfin.CodeAnalysis (unchanged) -- **Used By**: MediaBrowser.Controller, Jellyfin.MediaEncoding.Hls, test projects -- **Packages**: Minimal -- **Risk Level**: Low (specialized library) - -**Target State**: -- **Framework**: .NET 11.0 -- **Type**: Class Library -- **Dependencies**: No changes -- **Package Changes**: None required - -**Migration Steps**: - -1. **Prerequisites** - - ✅ .NET 11.0 SDK available - - ✅ Understanding of keyframe extraction functionality - -2. **Framework Update** - - Update `Jellyfin.MediaEncoding.Keyframes.csproj`: - ```xml - net11.0 - ``` - -3. **Package Updates** - - **None required** - minimal external dependencies - -4. **Expected Breaking Changes** - - ✅ **None expected** - - Specialized media encoding logic - - Limited BCL interaction - -5. **Code Modifications** - - **Expected**: None - - **Potential**: - - I/O API changes (if file operations change) - - Stream handling adjustments (unlikely) - -6. **Testing Strategy** - - **Build Validation**: - - Build without errors/warnings ✅ - - Code analysis passes ✅ - - - **Unit Testing**: - - Deferred to Tier 3 (Jellyfin.MediaEncoding.Keyframes.Tests) - - - **Functional Validation**: - - Keyframe extraction logic compiles ✅ - - FFmpeg integration interfaces unchanged ✅ - -7. **Validation Checklist** - - [ ] Project file updated to net11.0 - - [ ] Build succeeds without errors - - [ ] Build succeeds without warnings - - [ ] No external package updates needed - - [ ] Media encoding logic compiles cleanly - - [ ] Code analysis passes - - [ ] FFmpeg integration interfaces compatible - ---- - -### Tier 2: Batch Operations - -Since all 3 projects in Tier 2 have similar migration profiles, they can be **upgraded simultaneously**: - -#### Batch Update Process - -1. **Project File Updates** (Single operation) - - Update all 3 .csproj files to `net11.0` - - Commit: "Upgrade Tier 2 projects to .NET 11.0" - -2. **Build Validation** (Parallel) - - Build all 3 projects - - Check for errors/warnings - - Verify code analysis passes - -3. **Package Restoration** (Parallel) - - Restore NuGet packages for all projects - - Verify no conflicts - -4. **Integration Check** - - Build solution to ensure Tier 2 projects compile together - - Verify dependent projects (still on .NET 9.0) can still reference Tier 2 - ---- - -### Tier 2: Completion Criteria - -Before proceeding to Tier 3, **all** of the following must be met: - -1. ✅ **Build Success** - - All 3 projects build without errors - - All 3 projects build without warnings (zero-warning target) - -2. ✅ **Package Health** - - All packages restored successfully - - No package dependency conflicts - - EF Core design-time tools functional (Database.Implementations) - -3. ✅ **Code Quality** - - Code analysis passes (StyleCop, analyzers) - - No compiler warnings about obsolete APIs - - No new code analysis violations introduced - -4. ✅ **Preview Framework Assessment** - - .NET 11.0 SDK functional - - No blocking preview framework issues discovered - - Build performance acceptable - -5. ✅ **Documentation** - - Any issues encountered documented - - Workarounds noted (if applicable) - - Lessons learned recorded for later tiers - -**Decision Point**: If Tier 2 shows critical .NET 11.0 preview issues, **PAUSE** migration and assess viability. - ---- - -### Tier 2: Package Update Reference - -| Package | Current | Target | Notes | -|---------|---------|--------|-------| -| Microsoft.EntityFrameworkCore | 11.0.0-preview.1 | 11.0.0-preview.1 | Already compatible ✅ | -| Microsoft.EntityFrameworkCore.Relational | 11.0.0-preview.1 | 11.0.0-preview.1 | Already compatible ✅ | -| Microsoft.EntityFrameworkCore.Design | 11.0.0-preview.1 | 11.0.0-preview.1 | Already compatible ✅ | - -**All packages already at .NET 11.0-compatible versions - no package updates required for Tier 2.** - ---- - -### Tier 3: Data Layer - -#### Overview -**Projects**: 2 -**Complexity**: Low -**Risk**: Low -**Effort**: Low - -Data models and first test validation point. Straightforward migration with immediate test feedback. - ---- - -#### Jellyfin.Data - -**Current State**: .NET 9.0 Class Library -**Target State**: .NET 11.0 Class Library -**Dependencies**: Jellyfin.Database.Implementations (Tier 2), Jellyfin.CodeAnalysis -**Risk**: Low (data models) - -**Migration Steps**: -1. Update project file: `net11.0` -2. No package updates required (all compatible) -3. Build and validate data model classes compile cleanly - -**Expected Changes**: None - -**Validation**: -- [ ] Build succeeds without errors/warnings -- [ ] Data entity classes compile -- [ ] EF Core model configuration unchanged -- [ ] Used successfully by MediaBrowser.Model (Tier 4) - ---- - -#### Jellyfin.MediaEncoding.Keyframes.Tests - -**Current State**: .NET 9.0 Test Project (xUnit) -**Target State**: .NET 11.0 Test Project -**Dependencies**: Jellyfin.MediaEncoding.Keyframes (Tier 2), Jellyfin.CodeAnalysis -**Risk**: Low (test project) - -**Migration Steps**: -1. Update project file: `net11.0` -2. No package updates required: - - xUnit 2.9.3 ✅ - - xunit.runner.visualstudio 2.8.2 ✅ - - Microsoft.NET.Test.Sdk 18.0.1 ✅ -3. Run tests to validate Tier 2 (MediaEncoding.Keyframes) - -**Expected Changes**: None - -**Validation**: -- [ ] Build succeeds without errors/warnings -- [ ] All tests run successfully -- [ ] All tests pass (100% pass rate) -- [ ] Test runner compatible with .NET 11.0 -- [ ] Tier 2 keyframes functionality validated - -**Tier 3 Completion Criteria**: -1. Both projects build without errors/warnings -2. Jellyfin.MediaEncoding.Keyframes.Tests: 100% tests pass -3. No package conflicts -4. Tier 2 functionality validated through tests - ---- - -### Tier 4: Model Layer - -#### Overview -**Projects**: 1 -**Complexity**: Medium (high fan-out) -**Risk**: Medium -**Effort**: Low - -Central model definitions used by 21 projects throughout solution. Critical stability point. - ---- - -#### MediaBrowser.Model - -**Current State**: .NET 9.0 Class Library -**Target State**: .NET 11.0 Class Library -**Dependencies**: Jellyfin.Data (Tier 3), Jellyfin.Extensions (Tier 2), Jellyfin.CodeAnalysis -**Used By**: 21 projects (most of solution) -**Risk**: Medium (high fan-out = wide impact) - -**Migration Steps**: -1. Update project file: `net11.0` -2. No package updates required (compatible packages) -3. Build and validate model classes compile cleanly - -**Expected Changes**: None - -**Key Focus Areas**: -- DTO models for API serialization -- Query models for filtering/paging -- Configuration models -- Enum definitions - -**Validation**: -- [ ] Build succeeds without errors/warnings -- [ ] All model classes compile cleanly -- [ ] No JSON serialization API changes -- [ ] Enum definitions unchanged -- [ ] Configuration model binding compatible -- [ ] DTOs serialize/deserialize correctly (tested in Tier 5) - -**Special Considerations**: -- **High Fan-Out**: 21 projects depend on this -- **API Surface**: Models used in REST API contracts -- **Serialization**: JSON serialization must remain compatible - -**Tier 4 Completion Criteria**: -1. Project builds without errors/warnings -2. All model classes compile without changes -3. No breaking changes in public API surface -4. Ready for validation by Tier 5 tests - ---- - -### Tier 5: Common Utilities & Model Tests - -#### Overview -**Projects**: 3 -**Complexity**: Low -**Risk**: Low -**Effort**: Low - -Common utilities and validation tests for Tier 4 models. Provides test coverage for central models. - ---- - -#### MediaBrowser.Common - -**Current State**: .NET 9.0 Class Library -**Target State**: .NET 11.0 Class Library -**Dependencies**: MediaBrowser.Model (Tier 4), Jellyfin.CodeAnalysis -**Used By**: 10 projects -**Risk**: Low (utility library) - -**Migration Steps**: -1. Update project file: `net11.0` -2. Package updates - All compatible: - - Microsoft.Extensions.DependencyInjection: 11.0.0-preview.1 ✅ - - Microsoft.Extensions.Logging: 11.0.0-preview.1 ✅ - - Microsoft.Extensions.Http: 11.0.0-preview.1 ✅ -3. Build and validate common utilities - -**Expected Changes**: None - -**Validation**: -- [ ] Build succeeds without errors/warnings -- [ ] Dependency injection helpers compile -- [ ] Logging utilities compatible -- [ ] HTTP client utilities functional -- [ ] Configuration helpers unchanged - ---- - -#### Jellyfin.Extensions.Tests - -**Current State**: .NET 9.0 Test Project (xUnit) -**Target State**: .NET 11.0 Test Project -**Dependencies**: MediaBrowser.Model (Tier 4), Jellyfin.Extensions (Tier 2), Jellyfin.CodeAnalysis -**Risk**: Low (test project) - -**Migration Steps**: -1. Update project file: `net11.0` -2. No package updates required (test packages compatible) -3. Run tests to validate Tier 2 extensions - -**Expected Changes**: None - -**Validation**: -- [ ] Build succeeds -- [ ] All tests run -- [ ] All tests pass (100%) -- [ ] Tier 2 extensions validated - ---- - -#### Jellyfin.Model.Tests - -**Current State**: .NET 9.0 Test Project (xUnit) -**Target State**: .NET 11.0 Test Project -**Dependencies**: MediaBrowser.Model (Tier 4), Jellyfin.CodeAnalysis -**Risk**: Low (test project) - -**Migration Steps**: -1. Update project file: `net11.0` -2. No package updates required (test packages compatible) -3. Run tests to validate Tier 4 models - -**Expected Changes**: None - -**Validation**: -- [ ] Build succeeds -- [ ] All tests run -- [ ] All tests pass (100%) -- [ ] Tier 4 models validated (DTOs, serialization, configuration) - -**Tier 5 Completion Criteria**: -1. All 3 projects build without errors/warnings -2. Both test projects: 100% tests pass -3. Tier 2 extensions validated -4. Tier 4 models validated -5. Common utilities functional -6. No package conflicts - ---- - -### Tier 6: Database Providers & Naming ⚠️ CRITICAL TIER - -#### Overview -**Projects**: 3 -**Complexity**: High -**Risk**: CRITICAL -**Effort**: High - -**This is the most critical tier in the migration.** Database providers are the foundation for all data access throughout Jellyfin. Both PostgreSQL and SQLite EF Core providers are preview versions for .NET 11.0, requiring extensive validation. - -**🛑 GO/NO-GO DECISION POINT**: If Tier 6 fails validation, the entire migration may need to pause or revert. - ---- - -#### Emby.Naming - -**Current State**: .NET 9.0 Class Library -**Target State**: .NET 11.0 Class Library -**Dependencies**: MediaBrowser.Model (Tier 4), MediaBrowser.Common (Tier 5), Jellyfin.CodeAnalysis -**Used By**: MediaBrowser.Controller (Tier 7), Emby.Server.Implementations, Jellyfin.Naming.Tests (Tier 7) -**Risk**: Low (naming logic) - -**Migration Steps**: -1. Update project file: `net11.0` -2. No package updates required -3. Build and validate naming logic - -**Expected Changes**: None - -**Validation**: -- [ ] Build succeeds without errors/warnings -- [ ] Naming pattern logic compiles -- [ ] File/folder naming utilities unchanged -- [ ] Validated by Jellyfin.Naming.Tests (Tier 7) - ---- - -#### Jellyfin.Database.Providers.Postgres ⚠️ CRITICAL - -**Current State**: .NET 9.0 Class Library -**Target State**: .NET 11.0 Class Library -**Dependencies**: MediaBrowser.Common (Tier 5), Jellyfin.Database.Implementations (Tier 2), Jellyfin.CodeAnalysis -**Used By**: Jellyfin.Server (Tier 11), Jellyfin.Server.Implementations (Tier 8) -**Risk**: **CRITICAL** (primary database provider for Jellyfin) - -**Package Status**: -- **Npgsql.EntityFrameworkCore.PostgreSQL**: 11.0.0-preview.1 ✅ (already upgraded) -- **Status**: Preview provider for preview framework - -**Migration Steps**: - -1. **Prerequisites** - - PostgreSQL database server available for testing - - Test database with representative Jellyfin schema - - Baseline performance metrics from .NET 9.0 - - Connection string configuration ready - -2. **Framework Update** - - Update project file: `net11.0` - - No package updates required (already on preview) - -3. **Expected Breaking Changes** - - ✅ **None identified** in assessment - - ⚠️ **Potential**: EF Core 11.0 query translation changes - - ⚠️ **Potential**: Npgsql provider-specific behavior changes - - ⚠️ **Potential**: Connection pooling behavior - - ⚠️ **Potential**: Transaction handling differences - -4. **Code Modifications** - - **Expected**: None - - **Potential**: - - DbContext configuration adjustments - - Connection string format changes - - Provider-specific query hints - - Migration compatibility fixes - -5. **Testing Strategy** (EXTENSIVE) - - **Build Validation**: - - [ ] Project builds without errors - - [ ] Project builds without warnings - - [ ] Code analysis passes - - [ ] DbContext registration compiles - - **Database Connection Tests**: - - [ ] Connection string parsing successful - - [ ] Database connection established - - [ ] Connection pooling functional - - [ ] SSL/TLS connections work (if applicable) - - [ ] Connection timeouts handled correctly - - **Migration Tests**: - - [ ] Existing migrations still valid - - [ ] Can apply migrations to empty database - - [ ] Can upgrade from previous schema version - - [ ] Migration history table accessible - - [ ] No schema drift detected - - **CRUD Operations**: - - [ ] INSERT operations successful - - [ ] SELECT queries return correct data - - [ ] UPDATE operations modify records - - [ ] DELETE operations remove records - - [ ] Bulk operations functional - - [ ] Concurrent operations safe - - **Query Translation**: - - [ ] LINQ queries translate to SQL correctly - - [ ] Complex queries (joins, aggregations) work - - [ ] Navigation properties load correctly - - [ ] Explicit loading functional - - [ ] Eager loading (Include) functional - - [ ] Lazy loading compatible (if enabled) - - **Transaction Tests**: - - [ ] Explicit transactions work - - [ ] Rollback functional - - [ ] Nested transactions (if used) - - [ ] Distributed transactions (if used) - - [ ] Transaction isolation levels correct - - **Performance Tests**: - - [ ] Query performance comparable to .NET 9.0 baseline - - [ ] Insert/update performance acceptable - - [ ] Bulk operation performance - - [ ] Connection pool performance - - [ ] No memory leaks detected - - [ ] No excessive allocations - - **Concurrency Tests**: - - [ ] Concurrent reads safe - - [ ] Concurrent writes safe - - [ ] Optimistic concurrency functional - - [ ] Pessimistic locking works (if used) - - [ ] Deadlock handling correct - - **Edge Cases**: - - [ ] NULL value handling - - [ ] Large result sets - - [ ] Long-running queries - - [ ] Connection drops handled - - [ ] Database restart recovery - -6. **Validation Checklist** - - [ ] All connection tests pass - - [ ] All migration tests pass - - [ ] All CRUD tests pass - - [ ] All query translation tests pass - - [ ] All transaction tests pass - - [ ] Performance within acceptable range (<10% regression) - - [ ] Concurrency tests pass - - [ ] Edge case tests pass - - [ ] No critical issues detected - -7. **Performance Baseline Comparison** - - Document query performance vs. .NET 9.0 - - Compare connection pool behavior - - Measure memory usage - - Track any regressions - -**Contingency Plans**: -- **If connection issues**: Check Npgsql preview release notes; report bug upstream -- **If query translation fails**: Rewrite queries or wait for provider fix -- **If performance degrades >20%**: Profile and optimize or consider blocking issue -- **If critical bugs**: May need to pause migration until Npgsql fix available - ---- - -#### Jellyfin.Database.Providers.Sqlite ⚠️ CRITICAL - -**Current State**: .NET 9.0 Class Library -**Target State**: .NET 11.0 Class Library -**Dependencies**: MediaBrowser.Common (Tier 5), Jellyfin.Database.Implementations (Tier 2), Jellyfin.CodeAnalysis -**Used By**: Jellyfin.Server (Tier 11) -**Risk**: **CRITICAL** (alternative database provider for Jellyfin) - -**Package Status**: -- **Microsoft.EntityFrameworkCore.Sqlite**: 11.0.0-preview.1 ✅ (already upgraded) -- **Microsoft.Data.Sqlite**: 11.0.0-preview.1 ✅ (already upgraded) -- **Status**: Preview provider for preview framework - -**Migration Steps**: - -1. **Prerequisites** - - SQLite database file available for testing - - Test database with representative Jellyfin schema - - Baseline performance metrics from .NET 9.0 - - Write permissions verified - -2. **Framework Update** - - Update project file: `net11.0` - - No package updates required (already on preview) - -3. **Expected Breaking Changes** - - ✅ **None identified** in assessment - - ⚠️ **Potential**: EF Core 11.0 query translation changes - - ⚠️ **Potential**: SQLite provider-specific behavior changes - - ⚠️ **Potential**: File locking behavior - - ⚠️ **Potential**: WAL mode changes - -4. **Code Modifications** - - **Expected**: None - - **Potential**: - - DbContext configuration adjustments - - Connection string format changes - - Pragmas or SQLite-specific settings - - Migration compatibility fixes - -5. **Testing Strategy** (EXTENSIVE) - - **Build Validation**: - - [ ] Project builds without errors - - [ ] Project builds without warnings - - [ ] Code analysis passes - - [ ] DbContext registration compiles - - **Database File Tests**: - - [ ] Database file created successfully - - [ ] Database file opened correctly - - [ ] File locking works correctly - - [ ] WAL mode functional (if used) - - [ ] File permissions respected - - [ ] Backup/restore operations work - - **Migration Tests**: - - [ ] Existing migrations still valid - - [ ] Can apply migrations to empty database - - [ ] Can upgrade from previous schema version - - [ ] Migration history table accessible - - [ ] No schema drift detected - - **CRUD Operations**: - - [ ] INSERT operations successful - - [ ] SELECT queries return correct data - - [ ] UPDATE operations modify records - - [ ] DELETE operations remove records - - [ ] Bulk operations functional - - [ ] Concurrent operations safe - - **Query Translation**: - - [ ] LINQ queries translate to SQL correctly - - [ ] Complex queries (joins, aggregations) work - - [ ] Navigation properties load correctly - - [ ] Explicit loading functional - - [ ] Eager loading (Include) functional - - [ ] SQLite-specific SQL features work - - **Transaction Tests**: - - [ ] Explicit transactions work - - [ ] Rollback functional - - [ ] Nested transactions (if used) - - [ ] Transaction isolation correct - - **Performance Tests**: - - [ ] Query performance comparable to .NET 9.0 baseline - - [ ] Insert/update performance acceptable - - [ ] Bulk operation performance - - [ ] File I/O performance - - [ ] No memory leaks detected - - [ ] Database size remains reasonable - - **Concurrency Tests**: - - [ ] Concurrent reads safe - - [ ] Concurrent writes safe (within SQLite limits) - - [ ] File locking prevents corruption - - [ ] Busy timeout handling works - - **Edge Cases**: - - [ ] NULL value handling - - [ ] Large result sets - - [ ] Long-running queries - - [ ] Database corruption recovery (if applicable) - - [ ] Disk full scenarios handled - -6. **Validation Checklist** - - [ ] All file operation tests pass - - [ ] All migration tests pass - - [ ] All CRUD tests pass - - [ ] All query translation tests pass - - [ ] All transaction tests pass - - [ ] Performance within acceptable range (<10% regression) - - [ ] Concurrency tests pass - - [ ] Edge case tests pass - - [ ] No critical issues detected - -7. **Performance Baseline Comparison** - - Document query performance vs. .NET 9.0 - - Compare file I/O behavior - - Measure database file size - - Track any regressions - -**Contingency Plans**: -- **If file locking issues**: Check Microsoft.Data.Sqlite preview release notes -- **If query translation fails**: Rewrite queries or wait for provider fix -- **If performance degrades >20%**: Profile and optimize or consider blocking issue -- **If critical bugs**: May need to pause migration until EF Core Sqlite fix available - ---- - -### Tier 6: Integration Testing - -After all 3 projects migrate, perform **cross-provider validation**: - -#### Database Provider Integration Tests - -1. **Dual-Provider Tests** - - [ ] Can switch between PostgreSQL and SQLite configurations - - [ ] Same queries work on both providers - - [ ] Schema migrations compatible across providers - - [ ] Data integrity maintained across providers - -2. **Real-World Scenario Tests** - - [ ] User authentication/authorization queries - - [ ] Media library metadata queries - - [ ] Playback session tracking - - [ ] User preferences and settings - - [ ] Search and filtering operations - -3. **Load Testing** - - [ ] Concurrent user simulations - - [ ] Large library operations (10k+ items) - - [ ] Sustained query load - - [ ] Memory usage under load - -4. **Failure Recovery** - - [ ] Database connection drop recovery - - [ ] Transaction rollback on errors - - [ ] Database restart handling - - [ ] Corrupted data detection - ---- - -### Tier 6: Completion Criteria (STRICT) - -🛑 **This tier has the STRICTEST completion criteria.** Do not proceed to Tier 7 unless ALL criteria met: - -1. ✅ **Build Success** - - All 3 projects build without errors - - All 3 projects build without warnings - -2. ✅ **Database Connection** - - PostgreSQL provider connects successfully - - SQLite provider connects successfully - - Connection pooling functional for both - -3. ✅ **Migration Compatibility** - - All existing migrations apply successfully - - No schema drift detected - - Migration history intact - -4. ✅ **CRUD Operations** - - All CRUD tests pass (100%) for both providers - - Concurrency tests pass - - Transaction tests pass - -5. ✅ **Query Translation** - - LINQ queries translate correctly - - Complex queries work - - Navigation loading functional - -6. ✅ **Performance Acceptable** - - Query performance: <10% regression vs. .NET 9.0 - - Connection performance: Comparable to baseline - - Memory usage: No significant increase - - No memory leaks detected - -7. ✅ **Integration Tests** - - Dual-provider tests pass - - Real-world scenario tests pass - - Load tests pass (within acceptable limits) - - Failure recovery tests pass - -8. ✅ **Manual Validation** - - Senior engineer review of provider behavior - - Database administrator verification (for PostgreSQL) - - Sign-off on performance metrics - -9. ✅ **Documentation** - - All issues encountered documented - - Performance baselines recorded - - Known limitations documented - - Contingency plans ready - -**🛑 DECISION POINT**: If **any** critical issues detected in Tier 6, **PAUSE** migration: -- **Option A**: Report issues to Npgsql/EF Core teams; wait for fixes -- **Option B**: Implement workarounds (if feasible) -- **Option C**: Revert migration; target .NET 10.0 LTS instead -- **Option D**: Continue with documented risks (ONLY if non-critical) - -**Tier 6 is the primary risk gate. Proceed to Tier 7 only with high confidence in database provider stability.** - ---- - -### Tier 7: Controller Layer - -#### Overview -**Projects**: 2 (Jellyfin.Naming.Tests, MediaBrowser.Controller) -**Complexity**: Medium -**Risk**: Medium -**Effort**: Medium - -Controller abstractions and naming validation. MediaBrowser.Controller has high fan-out (12 projects depend on it). - -#### Quick Migration Profile - -**Both Projects**: -- Update to `net11.0` -- No package updates required (all compatible) -- Build and run tests - -**MediaBrowser.Controller**: -- **Risk**: Medium (high fan-out) -- **Dependencies**: Tiers 2-6 -- **Used By**: 12 projects (business logic tier) -- **Focus**: Controller abstractions, interfaces for repositories/services -- **Validation**: Jellyfin.Controller.Tests (Tier 8) - -**Jellyfin.Naming.Tests**: -- **Risk**: Low (test project) -- **Validates**: Emby.Naming (Tier 6) -- **Expected**: 100% tests pass - -**Tier 7 Completion Criteria**: -1. Both projects build without errors/warnings -2. Jellyfin.Naming.Tests: 100% pass rate -3. MediaBrowser.Controller public API unchanged -4. Ready for Tier 8 business logic - ---- - -### Tier 8: Business Logic ⚡ LARGEST TIER - -#### Overview -**Projects**: 12 (largest tier) -**Complexity**: High -**Risk**: High -**Effort**: High - -This tier contains most of Jellyfin's business logic: media processing, networking, providers, drawing, and server infrastructure. **High parallelization potential** within tier. - -#### Project Grouping for Parallel Execution - -**Group A: Media Processing (3 projects)** -- Emby.Photos -- MediaBrowser.MediaEncoding -- Jellyfin.MediaEncoding.Hls - -**Group B: Drawing & Graphics (2 projects)** -- Jellyfin.Drawing -- Jellyfin.Drawing.Skia - -**Group C: Business Services (4 projects)** -- Jellyfin.LiveTv -- Jellyfin.Networking -- MediaBrowser.Providers -- MediaBrowser.XbmcMetadata - -**Group D: Metadata & Server Infrastructure (3 projects)** -- MediaBrowser.LocalMetadata -- Jellyfin.Server.Implementations -- Jellyfin.Controller.Tests - ---- - -#### Group A: Media Processing - -##### Emby.Photos -- **Risk**: Medium (image processing) -- **Dependencies**: MediaBrowser.Model, MediaBrowser.Controller -- **Focus**: Photo library management -- **Validation**: Build + integration tests - -##### MediaBrowser.MediaEncoding -- **Risk**: High (FFmpeg integration) -- **Packages**: No updates needed -- **Focus**: Video/audio transcoding, FFmpeg process management -- **Key Tests**: - - [ ] FFmpeg process spawning works - - [ ] Stream handling functional - - [ ] Transcoding profiles correct - - [ ] Process cleanup on abort - -##### Jellyfin.MediaEncoding.Hls -- **Risk**: Medium (HLS streaming) -- **Dependencies**: MediaBrowser.Controller, Jellyfin.MediaEncoding.Keyframes -- **Focus**: HLS playlist generation, segmentation -- **Key Tests**: - - [ ] Manifest generation correct - - [ ] Segment timing accurate - - [ ] Playlist updates work - ---- - -#### Group B: Drawing & Graphics - -##### Jellyfin.Drawing -- **Risk**: Medium (graphics operations) -- **Dependencies**: MediaBrowser.Model, MediaBrowser.Common, MediaBrowser.Controller -- **Focus**: Image operations, thumbnail generation -- **Key Tests**: - - [ ] Image loading/saving works - - [ ] Thumbnail generation functional - - [ ] Image format conversions - -##### Jellyfin.Drawing.Skia -- **Risk**: High (native library interop) -- **Packages**: - - SkiaSharp 3.116.1 ✅ - - SkiaSharp.HarfBuzz 3.116.1 ✅ - - SkiaSharp.NativeAssets.Linux 3.116.1 ✅ - - HarfBuzzSharp.NativeAssets.Linux 8.3.1.1 ✅ -- **Focus**: SkiaSharp-based image processing -- **Critical Tests**: - - [ ] SkiaSharp native libraries load - - [ ] Image processing operations work - - [ ] Font rendering functional - - [ ] Cross-platform compatibility (Linux primary) - - [ ] No memory leaks in native interop -- **Contingency**: If SkiaSharp issues, check for .NET 11.0-specific native library versions - ---- - -#### Group C: Business Services - -##### Jellyfin.LiveTv -- **Risk**: Medium (Live TV functionality) -- **Dependencies**: MediaBrowser.Model, MediaBrowser.Common, MediaBrowser.Controller -- **Focus**: Live TV guide, recording management -- **Tests**: Jellyfin.LiveTv.Tests (Tier 9) - -##### Jellyfin.Networking -- **Risk**: Medium (network operations) -- **Dependencies**: MediaBrowser.Common, MediaBrowser.Controller -- **Focus**: Network discovery, DLNA, SSDP -- **Key Tests**: - - [ ] Network interface detection - - [ ] DLNA device discovery - - [ ] Socket operations - - [ ] UDP/TCP communication -- **Tests**: Jellyfin.Networking.Tests (Tier 9) - -##### MediaBrowser.Providers -- **Risk**: Medium (metadata providers) -- **Dependencies**: MediaBrowser.Model, MediaBrowser.Controller -- **Focus**: Metadata fetching from external sources (TMDb, MusicBrainz, etc.) -- **Packages**: - - TMDbLib 2.3.0 ✅ - - MetaBrainz.MusicBrainz 8.0.1 ✅ -- **Tests**: Jellyfin.Providers.Tests (Tier 9) - -##### MediaBrowser.XbmcMetadata -- **Risk**: Low (metadata parsing) -- **Dependencies**: MediaBrowser.Model, MediaBrowser.Controller -- **Focus**: NFO file parsing/writing -- **Tests**: Jellyfin.XbmcMetadata.Tests (Tier 9) - ---- - -#### Group D: Metadata & Server Infrastructure - -##### MediaBrowser.LocalMetadata -- **Risk**: Low (local metadata) -- **Dependencies**: MediaBrowser.Model, MediaBrowser.Controller -- **Focus**: Local metadata file operations - -##### Jellyfin.Server.Implementations -- **Risk**: High (server infrastructure) -- **Dependencies**: 6 direct dependencies (Jellyfin.Database.Providers.Postgres, Jellyfin.Data, MediaBrowser.Model, MediaBrowser.Controller, Jellyfin.Database.Implementations) -- **Focus**: Server core implementations, dependency injection, configuration -- **Key Areas**: - - Database integration (uses Tier 6 providers) - - Configuration management - - Service registration - - Plugin infrastructure -- **Tests**: Jellyfin.Server.Implementations.Tests (Tier 13) - -##### Jellyfin.Controller.Tests -- **Risk**: Low (test project) -- **Validates**: MediaBrowser.Controller (Tier 7) -- **Expected**: 100% tests pass - ---- - -### Tier 8: Batch Migration Strategy - -Due to 12 projects, **use phased approach within tier**: - -#### Phase 8A: Update All Project Files (Single Commit) -- Update all 12 .csproj files to `net11.0` -- Commit: "Upgrade Tier 8 projects to .NET 11.0" - -#### Phase 8B: Build Validation (Parallel by Group) -- Build Group A (Media Processing) -- Build Group B (Drawing & Graphics) -- Build Group C (Business Services) -- Build Group D (Metadata & Infrastructure) -- Fix any compilation errors - -#### Phase 8C: Integration Testing -- Run Jellyfin.Controller.Tests (validates Tier 7) -- Integration test between groups -- Validate SkiaSharp native libraries (Group B) -- Validate FFmpeg integration (Group A) -- Validate networking operations (Group C) - ---- - -### Tier 8: Completion Criteria - -1. ✅ **Build Success** - - All 12 projects build without errors - - All 12 projects build without warnings - -2. ✅ **Package Health** - - All packages restored - - No conflicts - - SkiaSharp native libraries load successfully - -3. ✅ **Group Validation** - - **Group A**: FFmpeg operations functional; HLS generation works - - **Group B**: SkiaSharp operations successful; image processing works - - **Group C**: Network operations functional; metadata providers work - - **Group D**: Server infrastructure compiles; controller tests pass - -4. ✅ **Critical Tests** - - Jellyfin.Controller.Tests: 100% pass - - Native library interop validated (SkiaSharp) - - Process management validated (FFmpeg) - - Network operations validated - -5. ✅ **Performance** - - Image processing: Comparable to .NET 9.0 - - Transcoding: No significant regression - - Network operations: Acceptable latency - -**Tier 8 represents majority of application functionality. Thorough validation required before proceeding.** - ---- - -### Tier 9: API & Tests - -#### Overview -**Projects**: 8 (Jellyfin.Api + 7 test projects) -**Complexity**: Medium -**Risk**: Medium -**Effort**: Medium - -API layer and comprehensive test coverage for Tier 8 business logic. - -#### Projects - -**Jellyfin.Api** (ASP.NET Core API): -- **Risk**: High (REST API) -- **Dependencies**: Jellyfin.Networking, Jellyfin.MediaEncoding.Hls, MediaBrowser.MediaEncoding, MediaBrowser.Controller -- **Packages**: - - Microsoft.AspNetCore.Authorization: 11.0.0-preview.1 ✅ - - Swashbuckle.AspNetCore: 7.3.2 ✅ - - Swashbuckle.AspNetCore.ReDoc: 6.9.0 ✅ -- **Key Areas**: - - REST API controllers - - Authentication/authorization - - API versioning - - OpenAPI/Swagger -- **Tests**: Jellyfin.Api.Tests (Tier 10) - -**Test Projects** (7 projects): -- Jellyfin.Common.Tests -- Jellyfin.LiveTv.Tests -- Jellyfin.MediaEncoding.Hls.Tests -- Jellyfin.MediaEncoding.Tests -- Jellyfin.Networking.Tests -- Jellyfin.Providers.Tests -- Jellyfin.XbmcMetadata.Tests - -**Migration Strategy**: -1. Update all 8 project files to net11.0 -2. Build API project; fix any ASP.NET Core compatibility issues -3. Run all 7 test projects (validates Tier 8) - -**Tier 9 Completion Criteria**: -1. Jellyfin.Api builds without errors/warnings -2. API controllers compile; routing works -3. Authentication/authorization unchanged -4. Swagger/OpenAPI generation works -5. **All 7 test projects: 100% pass rate** -6. Tier 8 business logic validated through tests - ---- - -### Tier 10: Server Implementation - -#### Overview -**Projects**: 2 -**Complexity**: High -**Risk**: High -**Effort**: High - -Server implementations that integrate all lower tiers. - -#### Emby.Server.Implementations -- **Risk**: High (integration complexity) -- **Dependencies**: 14 direct dependencies (most of solution) -- **Focus**: Server implementation layer integrating all features -- **Migration**: Update to net11.0; validate integration -- **Tests**: Jellyfin.Server.Implementations.Tests (Tier 13) - -#### Jellyfin.Api.Tests -- **Risk**: Low (test project) -- **Validates**: Jellyfin.Api (Tier 9) -- **Expected**: 100% tests pass - -**Tier 10 Completion Criteria**: -1. Both projects build without errors/warnings -2. Jellyfin.Api.Tests: 100% pass -3. Server implementations compile and integrate all dependencies -4. No integration conflicts - ---- - -### Tier 11: Main Application - -#### Overview -**Projects**: 1 (Jellyfin.Server) -**Complexity**: High -**Risk**: High -**Effort**: Medium - -Main application entry point - consolidates all functionality. - -#### Jellyfin.Server -- **Risk**: High (application entry point) -- **Dependencies**: 9 direct dependencies -- **Type**: ASP.NET Core application -- **Packages**: - - Serilog.AspNetCore: 10.0.0 ✅ - - prometheus-net.AspNetCore: 8.2.1 ✅ - - Microsoft.AspNetCore.Mvc.Testing: 11.0.0-preview.1 ✅ -- **Key Areas**: - - Application startup (Program.cs, Startup.cs) - - ASP.NET Core hosting - - Middleware pipeline - - Dependency injection configuration - - Logging configuration (Serilog) - - Metrics (Prometheus) - -**Migration Steps**: -1. Update to net11.0 -2. Validate startup configuration -3. Test application starts -4. Validate middleware pipeline -5. Check dependency injection registration -6. Verify logging/metrics - -**Critical Tests**: -- [ ] Application starts successfully -- [ ] No startup exceptions -- [ ] All services registered correctly -- [ ] Middleware pipeline intact -- [ ] API responds to requests -- [ ] Health checks pass -- [ ] Metrics collected -- [ ] Logging functional - -**Tier 11 Completion Criteria**: -1. Project builds without errors/warnings -2. Application starts successfully -3. Basic HTTP requests work (200 OK) -4. Health checks pass -5. No startup errors in logs -6. Ready for integration testing - ---- - -### Tier 12: Integration Tests - -#### Overview -**Projects**: 2 -**Complexity**: Medium -**Risk**: Medium -**Effort**: Medium - -End-to-end integration testing of full application stack. - -#### Jellyfin.Server.Integration.Tests -- **Risk**: Medium (integration tests) -- **Dependencies**: Jellyfin.Server (Tier 11) -- **Focus**: End-to-end API testing, authentication flows, feature integration - -#### Jellyfin.Server.Tests -- **Risk**: Medium (application tests) -- **Dependencies**: Jellyfin.Server (Tier 11) -- **Focus**: Server startup, configuration, basic functionality - -**Migration**: Update both to net11.0; run full test suite - -**Tier 12 Completion Criteria**: -1. Both test projects build -2. Jellyfin.Server.Tests: 100% pass -3. Jellyfin.Server.Integration.Tests: 100% pass -4. All integration scenarios validated -5. Authentication/authorization flows work -6. API endpoints functional - ---- - -### Tier 13: Final Test Validation - -#### Overview -**Projects**: 1 -**Complexity**: Low -**Risk**: Low -**Effort**: Low - -Final validation of server implementations with integration context. - -#### Jellyfin.Server.Implementations.Tests -- **Risk**: Low (final test validation) -- **Dependencies**: Tier 12 (integration tests), Emby.Server.Implementations, Jellyfin.Server.Implementations -- **Focus**: Server implementation validation - -**Migration**: Update to net11.0; run tests - -**Tier 13 Completion Criteria**: -1. Project builds -2. 100% tests pass -3. All server implementations validated -4. No regressions detected - ---- - -## Testing & Validation Strategy - -### Multi-Level Testing Approach - -The migration employs testing at every tier to ensure stability before proceeding. - -#### Per-Tier Testing - -**Build-Time Validation** (Every Tier): -- Zero compilation errors -- Zero warnings (target) -- Code analysis passes -- Package restoration successful - -**Unit Testing** (Tiers with Test Projects): -- 100% test pass rate required -- No skipped tests -- No degraded performance -- Tests validate lower tiers - -**Integration Testing** (Critical Tiers): -- Tier 6: Database provider integration tests -- Tier 9: API integration tests -- Tier 12: Full application integration tests - -#### Phase-by-Phase Testing Requirements - -| Phase | Test Requirements | Success Criteria | -|-------|-------------------|------------------| -| **Phase 1** (Tier 2) | Build validation; no unit tests yet | Builds clean; preview framework functional | -| **Phase 2** (Tier 3) | Jellyfin.MediaEncoding.Keyframes.Tests | 100% pass; Tier 2 validated | -| **Phase 3** (Tier 4) | Build only; tested in Phase 4 | Builds clean | -| **Phase 4** (Tier 5) | Jellyfin.Extensions.Tests + Jellyfin.Model.Tests | 100% pass; Tiers 2 & 4 validated | -| **Phase 5** (Tier 6) | **CRITICAL: Extensive database tests** | All database integration tests pass | -| **Phase 6** (Tier 7) | Jellyfin.Naming.Tests | 100% pass; Tier 6 validated | -| **Phase 7** (Tier 8) | Jellyfin.Controller.Tests | 100% pass; Tier 7 validated | -| **Phase 8** (Tier 9) | 7 test projects | 100% pass all; Tier 8 validated | -| **Phase 9** (Tier 10) | Jellyfin.Api.Tests | 100% pass; API validated | -| **Phase 10** (Tier 11) | Manual smoke tests | Application starts; basic features work | -| **Phase 11** (Tier 12) | Integration + Server tests | 100% pass; full stack validated | -| **Phase 12** (Tier 13) | Jellyfin.Server.Implementations.Tests | 100% pass; server validated | -| **Phase 13** (All) | **Full solution validation** | All tests pass; smoke tests pass; performance acceptable | - -### Manual Testing Requirements - -#### Tier 11 Smoke Tests (Critical) -After Jellyfin.Server migrates, perform manual validation: - -1. **Application Startup** - - [ ] Server starts without errors - - [ ] No exceptions in startup logs - - [ ] Health checks respond - -2. **Basic Features** - - [ ] Web UI loads - - [ ] User authentication works - - [ ] Library browsing functional - - [ ] Media playback initiates - -3. **API Validation** - - [ ] REST API responds - - [ ] Authentication endpoints work - - [ ] Basic CRUD operations successful - -4. **Database Operations** - - [ ] Database queries work (PostgreSQL or SQLite) - - [ ] No connection errors - - [ ] CRUD operations persist - -### Performance Testing - -**Baseline Comparison Points**: -- Tier 6: Database query performance -- Tier 8: Image processing, transcoding performance -- Tier 11: Application startup time, API response time - -**Acceptable Performance**: -- Query performance: <10% regression -- Image/video processing: <15% regression -- Startup time: <20% regression -- Memory usage: <15% increase - -**Performance Degradation Response**: -- Document regression -- Profile with dotnet-trace/PerfView -- Report to .NET team if framework-related -- Consider optimization or pause if severe (>30% regression) - -### Comprehensive Validation (Phase 13) - -After Tier 13 complete, perform full solution validation: - -#### Build Validation -- [ ] Full solution builds without errors -- [ ] Full solution builds without warnings -- [ ] All projects target net11.0 (except CodeAnalysis) -- [ ] No package conflicts across solution - -#### Test Suite Validation -- [ ] All 15 test projects run successfully -- [ ] 100% test pass rate across solution -- [ ] No flaky tests -- [ ] Test execution time acceptable - -#### Smoke Testing -- [ ] Application starts and runs -- [ ] All major features functional: - - User authentication - - Library management - - Media playback - - Transcoding - - Live TV (if applicable) - - Metadata fetching - - Image processing - - Network discovery -- [ ] No critical errors in logs -- [ ] Health checks pass - -#### Performance Validation -- [ ] Startup time within acceptable range -- [ ] API response times acceptable -- [ ] Database query performance good -- [ ] Transcoding performance acceptable -- [ ] Memory usage reasonable -- [ ] No memory leaks detected - -#### Deployment Testing -- [ ] Application deploys successfully -- [ ] Runs on target platforms (Linux, Windows, Docker) -- [ ] Configuration migration works -- [ ] Database migrations successful -- [ ] Existing data accessible - -#### Rollback Validation -- [ ] Can revert to previous .NET version if needed -- [ ] Backup/restore procedures work -- [ ] Database rollback possible (if needed) - -## Risk Management - -### High-Level Risk Assessment - -The migration to .NET 11.0 (PREVIEW) presents **moderate to high risk** despite clean compatibility analysis: - -#### Risk Categories - -| Risk Level | Description | Count | Projects/Areas | -|------------|-------------|-------|----------------| -| **CRITICAL** | Preview framework; database providers | 2 | .NET 11.0 PREVIEW stability; PostgreSQL/SQLite EF providers | -| **HIGH** | Large complex projects; media processing | 5 | Jellyfin.Server, Emby.Server.Implementations, MediaBrowser.MediaEncoding, SkiaSharp, HLS encoding | -| **MEDIUM** | ASP.NET Core application; multiple dependencies | 8 | Jellyfin.Api, Jellyfin.Server.Implementations, MediaBrowser.Controller, networking, providers | -| **LOW** | Small libraries; test projects | 25 | Extensions, models, most test projects | - -### Critical Risks - -#### 1. Preview Framework Instability (.NET 11.0 PREVIEW) - -**Risk**: CRITICAL -**Impact**: Entire solution -**Probability**: HIGH - -**Description**: -.NET 11.0 is in preview - not production-ready. May exhibit: -- Runtime instability -- Unexpected breaking changes in preview builds -- Performance regressions -- Undocumented API changes -- Preview build tooling issues -- Missing or incomplete features - -**Mitigation**: -- ✅ Bottom-up approach exposes issues early (Tier 2 discovery) -- ✅ Extensive testing at each tier before proceeding -- ✅ Monitor .NET 11.0 preview release notes for known issues -- ✅ Maintain ability to rollback to .NET 9.0 or switch to .NET 10.0 LTS -- ✅ Test on target deployment environments early -- ✅ Consider pausing if critical preview bugs discovered - -**Contingency**: -- If critical preview issues: revert and target .NET 10.0 LTS instead -- If minor issues: document and work around, monitor for preview fixes -- If blocking issues in Tier 2-4: pause migration until preview stabilizes - -#### 2. Database Provider Compatibility (Tier 6) - -**Risk**: CRITICAL -**Impact**: All database operations (entire application) -**Probability**: MEDIUM - -**Description**: -Database providers are critical infrastructure: -- **Npgsql.EntityFrameworkCore.PostgreSQL 11.0.0-preview.1**: Preview provider for preview framework -- **Microsoft.EntityFrameworkCore.Sqlite 11.0.0-preview.1**: Preview EF Core provider -- Jellyfin.Database.Implementations integrates both providers -- Any provider issue breaks data access throughout application - -**Mitigation**: -- ✅ Tier 6 dedicated phase for database provider validation -- ✅ Extensive integration testing with real databases (PostgreSQL, SQLite) -- ✅ Test migration scenarios, CRUD operations, query performance -- ✅ Validate connection pooling, transaction behavior -- ✅ Performance benchmarking vs. .NET 9.0 baseline -- ✅ Test under load/concurrent operations - -**Contingency**: -- If provider issues: report to Npgsql/EF Core teams, monitor for fixes -- If blocking: consider staying on .NET 9.0 until stable provider releases -- If PostgreSQL issues only: validate SQLite as temporary fallback -- Database provider failures block entire migration at Tier 6 - -### High Risks - -#### 3. Media Processing Libraries (SkiaSharp, Tier 8) - -**Risk**: HIGH -**Impact**: Image processing, thumbnail generation, graphics -**Probability**: MEDIUM - -**Description**: -- SkiaSharp 3.116.1 used for image processing -- HarfBuzzSharp.NativeAssets.Linux for font rendering -- Native library interop may have .NET 11.0 issues -- Cross-platform compatibility concerns (Linux, Windows, macOS) - -**Mitigation**: -- ✅ Test image processing workflows in Tier 8 -- ✅ Validate thumbnail generation, image transcoding -- ✅ Test on target platforms (Linux primary for Jellyfin) -- ✅ Verify native library loading and interop -- ✅ Performance testing for image operations - -**Contingency**: -- If issues: check for SkiaSharp .NET 11.0 updates -- Report issues to SkiaSharp maintainers -- May need to wait for library updates - -#### 4. Main Server Application (Jellyfin.Server, Tier 11) - -**Risk**: HIGH -**Impact**: Application entry point, all features -**Probability**: LOW - -**Description**: -- Main application consolidates all functionality -- ASP.NET Core 11.0 preview hosting -- Startup configuration, middleware, dependency injection -- All features converge here - -**Mitigation**: -- ✅ Tiers 2-10 stable before reaching Tier 11 -- ✅ Comprehensive integration testing -- ✅ Manual smoke testing of key user scenarios -- ✅ Performance monitoring vs. baseline -- ✅ Error handling and logging verification - -**Contingency**: -- If startup issues: check ASP.NET Core 11.0 preview breaking changes -- Isolate failing features and test independently -- May need ASP.NET Core configuration adjustments - -#### 5. Entity Framework Core 11.0 Preview - -**Risk**: HIGH -**Impact**: All data access -**Probability**: MEDIUM - -**Description**: -- EF Core 11.0.0-preview.1 used throughout solution -- Query translation, migrations, change tracking -- Preview may have query translation issues or performance changes - -**Mitigation**: -- ✅ Validate existing database migrations still work -- ✅ Test query patterns used throughout application -- ✅ Monitor query performance -- ✅ Validate LINQ-to-SQL translation -- ✅ Test include/navigation loading - -**Contingency**: -- If query translation fails: rewrite queries or wait for EF Core fixes -- Performance issues: profile and optimize or report upstream -- Migration issues: may need manual SQL adjustments - -### Medium Risks - -#### 6. ASP.NET Core 11.0 API Compatibility (Tier 9) - -**Risk**: MEDIUM -**Impact**: REST API, authentication, authorization -**Probability**: MEDIUM - -**Description**: -- Jellyfin.Api uses ASP.NET Core 11.0 preview -- Authentication, authorization, middleware pipeline -- API controllers, routing, model binding - -**Mitigation**: -- ✅ API tests in Tier 9 validate endpoints -- ✅ Test authentication/authorization flows -- ✅ Validate OpenAPI/Swagger generation -- ✅ Test API versioning - -**Contingency**: -- If auth issues: review ASP.NET Core Identity changes -- If routing breaks: adjust route configurations -- API compatibility issues may require code changes - -#### 7. Media Encoding & Streaming (Tier 8-9) - -**Risk**: MEDIUM -**Impact**: Video transcoding, HLS streaming -**Probability**: LOW - -**Description**: -- MediaBrowser.MediaEncoding, Jellyfin.MediaEncoding.Hls -- Video/audio transcoding, HLS playlist generation -- FFmpeg integration (process spawning, stream handling) - -**Mitigation**: -- ✅ Test transcoding workflows -- ✅ Validate HLS manifest generation -- ✅ Test FFmpeg process management -- ✅ Performance validation for encoding - -**Contingency**: -- If process issues: check .NET 11.0 Process API changes -- If streaming breaks: validate HLS encoding pipeline -- May need FFmpeg command adjustments - -#### 8. Networking & Connectivity (Tier 8) - -**Risk**: MEDIUM -**Impact**: Network discovery, DLNA, remote access -**Probability**: LOW - -**Description**: -- Jellyfin.Networking for network operations -- DLNA, SSDP, network interface detection -- Socket operations, UDP/TCP communication - -**Mitigation**: -- ✅ Test network discovery scenarios -- ✅ Validate DLNA device detection -- ✅ Test under various network configurations -- ✅ Socket operation validation - -**Contingency**: -- If network issues: check .NET 11.0 networking changes -- May need Socket or HttpClient configuration adjustments -- DLNA issues may require protocol-level debugging - -### Low Risks - -#### 9. Test Projects - -**Risk**: LOW -**Impact**: Testing infrastructure only -**Probability**: LOW - -**Description**: -15 test projects throughout tiers; xUnit 2.9.3, Moq 4.18.4 - -**Mitigation**: -- ✅ Test framework compatibility pre-verified -- ✅ Test projects upgraded incrementally with their targets -- ✅ Validation at each tier - -**Contingency**: -- If test framework issues: update xUnit/Moq/AutoFixture -- Test failures indicate actual issues, not test framework problems - -#### 10. Small Utility Libraries - -**Risk**: LOW -**Impact**: Limited to specific features -**Probability**: VERY LOW - -**Description**: -- Extensions, utilities, models (Tiers 2-5) -- Simple, well-tested code -- Minimal external dependencies - -**Mitigation**: -- ✅ Unit tests cover functionality -- ✅ Early tiers - failures detected immediately -- ✅ Easy to isolate and fix - -**Contingency**: -- Minimal risk; standard debugging if issues arise - -### Risk Mitigation Matrix - -| Tier | Primary Risks | Mitigation Strategy | Fallback | -|------|---------------|---------------------|----------| -| **Tier 2** | Preview framework first exposure | Extensive testing; early warning system | Revert if critical issues | -| **Tier 3-5** | Model/data layer stability | Unit tests, validation | Isolated fixes | -| **Tier 6** | Database providers (CRITICAL) | Integration tests, performance testing | Block migration if fails | -| **Tier 7** | Controller abstractions | Naming tests, validation | Standard debugging | -| **Tier 8** | Media processing, networking | Functional testing, cross-platform validation | Feature-specific fixes | -| **Tier 9** | API, authentication | API tests, auth flow validation | ASP.NET Core config adjustments | -| **Tier 10-11** | Server implementation, main app | Integration tests, smoke testing | Startup configuration fixes | -| **Tier 12-13** | End-to-end validation | Full test suite, manual validation | Comprehensive debugging | - -### Rollback Triggers - -Rollback or pause migration if: - -1. ✅ **Tier 2-4 failures**: Preview framework shows critical instability -2. ✅ **Tier 6 failure**: Database providers unusable -3. ✅ **>20% test failures** in any tier -4. ✅ **Performance degradation** >30% in benchmarks -5. ✅ **Blocking preview bugs** with no workaround -6. ✅ **Security vulnerabilities** in preview framework -7. ✅ **Critical runtime errors** not present in .NET 9.0 - -### Risk Acceptance - -The following risks are **accepted**: - -- ✅ **Preview framework instability**: Required for .NET 11.0 evaluation -- ✅ **Minor breaking changes**: Expected in preview; can be addressed -- ✅ **Performance variations**: Preview builds may have unoptimized code -- ✅ **Incomplete preview features**: Can work around or wait for releases - -### Continuous Risk Monitoring - -Throughout migration: -- Monitor .NET 11.0 preview announcements and known issues -- Track package update releases for compatibility fixes -- Performance benchmark each tier vs. .NET 9.0 baseline -- Document all issues encountered for future reference -- Maintain communication with .NET/EF Core/package maintainer communities - -## Testing & Validation Strategy -[To be filled] - -## Complexity & Effort Assessment - -### Overall Complexity: **COMPLEX** - -Based on solution structure, technology stack, and preview framework target. - -### Per-Tier Complexity Assessment - -| Tier | Projects | Complexity | Dependencies | Risk | Effort | Rationale | -|------|----------|------------|--------------|------|--------|-----------| -| **Tier 1** | 1 | N/A | None | None | None | No migration (netstandard2.0) | -| **Tier 2** | 3 | **Medium** | CodeAnalysis only | High | Medium | First preview exposure; database/extension infrastructure | -| **Tier 3** | 2 | **Low** | Tier 2 | Low | Low | Data models + 1 test; straightforward | -| **Tier 4** | 1 | **Medium** | Tiers 2-3 | Medium | Low | Central models (high fan-out); single project | -| **Tier 5** | 3 | **Low** | Tiers 2-4 | Low | Low | Common utilities + 2 tests; minimal complexity | -| **Tier 6** | 3 | **High** | Tiers 2-5 | **Critical** | High | Database providers (PostgreSQL, SQLite); extensive testing required | -| **Tier 7** | 2 | **Medium** | Tiers 2-6 | Medium | Medium | Controller abstractions + 1 test; moderate complexity | -| **Tier 8** | 12 | **High** | Tiers 2-7 | High | High | Largest tier; media processing, networking, business logic; parallelizable | -| **Tier 9** | 8 | **Medium** | Tiers 2-8 | Medium | Medium | API + 7 test projects; validation-heavy | -| **Tier 10** | 2 | **High** | Tiers 2-9 | High | High | Server implementations; integration point for all features | -| **Tier 11** | 1 | **High** | Tiers 2-10 | High | Medium | Main application; entry point; consolidates all functionality | -| **Tier 12** | 2 | **Medium** | Tier 11 | Medium | Medium | Integration tests; end-to-end validation | -| **Tier 13** | 1 | **Low** | Tier 12 | Low | Low | Final test project; single project validation | - -### Tier-by-Tier Effort Breakdown - -#### Low Complexity Tiers (4 tiers, 7 projects) -**Tiers**: 3, 5, 13 -**Total Projects**: 7 -**Characteristics**: -- Small codebases or test-only projects -- Minimal dependencies or simple utilities -- Straightforward migration -- Low risk of issues - -**Estimated Effort**: Low per tier - ---- - -#### Medium Complexity Tiers (5 tiers, 10 projects) -**Tiers**: 2, 4, 7, 9, 12 -**Total Projects**: 10 -**Characteristics**: -- Infrastructure components (Tier 2) -- Central models with high fan-out (Tier 4) -- Controller abstractions (Tier 7) -- API + multiple tests (Tier 9) -- Integration testing (Tier 12) - -**Estimated Effort**: Medium per tier - ---- - -#### High Complexity Tiers (3 tiers, 15 projects) -**Tiers**: 6, 8, 10, 11 -**Total Projects**: 15 -**Characteristics**: -- **Tier 6**: Database providers (CRITICAL; extensive testing) -- **Tier 8**: Largest tier (12 projects); media processing, networking, business logic -- **Tier 10**: Server implementations (integration complexity) -- **Tier 11**: Main application (consolidation point) - -**Estimated Effort**: High per tier - -### Resource Requirements - -#### Skill Levels Needed - -1. **Senior .NET Engineers** (Required) - - Deep .NET framework knowledge - - Experience with preview frameworks - - EF Core expertise (for Tier 6) - - ASP.NET Core experience (for Tiers 9-11) - -2. **Database Engineers** (Tier 6) - - PostgreSQL administration - - SQLite expertise - - EF Core migrations and performance tuning - -3. **Media Processing Engineers** (Tier 8) - - FFmpeg integration knowledge - - Video encoding/transcoding experience - - HLS streaming protocols - -4. **QA/Testing Engineers** (All tiers) - - Test framework expertise (xUnit) - - Integration testing - - Performance testing - -#### Parallel Execution Capacity - -**Optimal Team Structure**: -- **Tier 2-5, 7**: 1-2 engineers (sequential or small parallel) -- **Tier 6**: 2-3 engineers (database providers need dedicated focus) -- **Tier 8**: 3-5 engineers (12 projects; high parallelism potential) -- **Tier 9-11**: 2-3 engineers (integration complexity) -- **Tier 12-13**: 1-2 engineers (testing focus) - -**Minimum Team**: 2 senior .NET engineers + 1 QA engineer -**Optimal Team**: 4-5 engineers (mix of specializations) + 2 QA engineers - -### Phase Complexity Summary - -| Phase | Tier(s) | Complexity | Effort | Duration Estimate | -|-------|---------|------------|--------|-------------------| -| **Phase 1** | Tier 2 | Medium | Medium | *Relative: Medium* | -| **Phase 2** | Tier 3 | Low | Low | *Relative: Low* | -| **Phase 3** | Tier 4 | Medium | Low | *Relative: Low* | -| **Phase 4** | Tier 5 | Low | Low | *Relative: Low* | -| **Phase 5** | Tier 6 | **High** | **High** | *Relative: High* | -| **Phase 6** | Tier 7 | Medium | Medium | *Relative: Medium* | -| **Phase 7** | Tier 8 | **High** | **High** | *Relative: High* | -| **Phase 8** | Tier 9 | Medium | Medium | *Relative: Medium* | -| **Phase 9** | Tier 10 | **High** | **High** | *Relative: High* | -| **Phase 10** | Tier 11 | High | Medium | *Relative: Medium* | -| **Phase 11** | Tier 12 | Medium | Medium | *Relative: Medium* | -| **Phase 12** | Tier 13 | Low | Low | *Relative: Low* | -| **Phase 13** | All | High | High | *Relative: High* | - -**Note**: Duration estimates are relative complexity ratings only. Actual time depends on team size, experience, issue discovery, and preview framework stability. - -### Complexity Factors by Tier - -#### Tier 2: Core Infrastructure (Medium) -- **Factors**: - - First exposure to .NET 11.0 preview - - Database implementation foundation - - Extension infrastructure -- **Challenges**: - - Unknown preview framework issues - - Critical foundation for all higher tiers -- **Mitigation**: Thorough testing; early warning system - -#### Tier 6: Database Providers (High) ⚠️ CRITICAL -- **Factors**: - - PostgreSQL EF Core provider (preview) - - SQLite EF Core provider (preview) - - Database operations throughout solution depend on this -- **Challenges**: - - Provider preview stability - - Query translation, migrations, performance - - Concurrent operations, connection pooling -- **Mitigation**: Extensive integration testing, performance benchmarking - -#### Tier 8: Business Logic (High) -- **Factors**: - - 12 projects (largest tier) - - Media processing (SkiaSharp, FFmpeg) - - Networking (DLNA, SSDP) - - Providers, metadata, encoding -- **Challenges**: - - Diverse functionality requiring different expertise - - Native library interop (SkiaSharp) - - Process management (FFmpeg) -- **Mitigation**: Parallelization; specialized testing per area - -#### Tier 10: Server Implementation (High) -- **Factors**: - - Emby.Server.Implementations (14 dependencies) - - Integration point for most features -- **Challenges**: - - Complex integration - - Many failure points from dependencies -- **Mitigation**: Tiers 2-9 stable; incremental testing - -#### Tier 11: Main Application (High) -- **Factors**: - - Application entry point - - ASP.NET Core 11.0 hosting - - Startup, middleware, DI configuration -- **Challenges**: - - All features converge here - - ASP.NET Core preview stability -- **Mitigation**: Comprehensive smoke testing; staging environment validation - -### Incremental Benefit Realization - -Benefits realized after each tier completion: - -| Tier Complete | Benefits Unlocked | -|---------------|-------------------| -| **Tier 2** | Foundation infrastructure on .NET 11.0; preview framework viability assessed | -| **Tier 3** | Data models available to higher tiers | -| **Tier 4** | Central models on .NET 11.0; broad compatibility established | -| **Tier 5** | Common utilities available; model validation complete | -| **Tier 6** | **Database providers validated** (critical milestone); data access stable | -| **Tier 7** | Controller abstractions ready; naming validated | -| **Tier 8** | **Business logic on .NET 11.0**; media processing, networking validated | -| **Tier 9** | **API layer operational**; comprehensive business logic tests pass | -| **Tier 10** | **Server implementations complete**; integration validated | -| **Tier 11** | **Main application functional**; end-to-end features available | -| **Tier 12** | **Integration testing complete**; confidence in full stack | -| **Tier 13** | **All tests pass**; solution fully validated | - -### Critical Milestones - -1. **Tier 2 Complete**: Preview framework viability confirmed -2. **Tier 6 Complete**: Database providers stable (go/no-go decision point) -3. **Tier 8 Complete**: Business logic operational -4. **Tier 11 Complete**: Application functional -5. **Tier 13 Complete**: Full solution validation - -### Effort Distribution - -- **Low Effort Tiers** (3, 5, 13): ~15% of total effort -- **Medium Effort Tiers** (2, 4, 7, 9, 12): ~35% of total effort -- **High Effort Tiers** (6, 8, 10, 11): ~50% of total effort - -**Highest effort areas**: -1. Tier 6 (Database providers) - CRITICAL -2. Tier 8 (Business logic) - Largest tier -3. Tier 10-11 (Server & application) - Integration complexity - -## Source Control Strategy - -### Branching Strategy - -**Primary Branch**: `upgrade-to-NET11` -**Source Branch**: `pgsql_testing_branch` -**Merge Target**: `pgsql_testing_branch` (after successful validation) - -#### Branch Management -- Upgrade branch created from `pgsql_testing_branch` -- All migration work on `upgrade-to-NET11` -- Tier-by-tier commits -- Protected milestones: Tags after Tier 6, Tier 11, Tier 13 - -### Commit Strategy - -**Format**: `Upgrade Tier [N] ([Name]) to .NET 11.0` - -**Per-Tier Commits** (Recommended): -- One commit per tier -- Atomic changes -- Includes test validation - -### Review and Merge - -**Single PR** after complete validation (recommended for preview framework) - -**PR Checklist**: -- [ ] All 13 tiers complete -- [ ] 100% test pass rate -- [ ] Full solution builds clean -- [ ] Performance acceptable -- [ ] Documentation updated - -**Review Requirements**: 2+ senior engineers - -### Rollback Plan - -**Triggers**: Critical preview bugs, database failures, severe performance degradation - -**Method**: Git revert to pre-migration state - ---- - -## Success Criteria - -### Technical Criteria - -**Build & Compilation**: -- ✅ 40 projects upgraded to .NET 11.0 -- ✅ Solution builds without errors/warnings -- ✅ No package conflicts - -**Testing**: -- ✅ All 15 test projects: 100% pass rate -- ✅ No flaky tests - -**Database Providers (CRITICAL)**: -- ✅ PostgreSQL & SQLite functional -- ✅ Migrations successful -- ✅ Performance: <10% regression - -**Application**: -- ✅ Jellyfin.Server starts -- ✅ All major features work -- ✅ API functional - -**Performance**: -- ✅ Startup: <20% regression -- ✅ Database queries: <10% regression -- ✅ API/processing: <15% regression -- ✅ Memory: <15% increase - -**Code Quality**: -- ✅ All analyzers pass -- ✅ No new warnings - -**Bottom-Up Strategy**: -- ✅ All 13 tiers completed in order -- ✅ Tier 6 extensively validated - -**Deployment**: -- ✅ Deploys to target platforms -- ✅ Rollback tested - -### Definition of Done - -Migration complete when: -- All technical criteria met -- All stakeholder approvals obtained -- PR merged -- Post-merge validation passed - ---- - -## Final Notes - -### .NET 11.0 Preview Warning - -Targeting **PREVIEW framework** - expect instability. Monitor closely; consider .NET 10.0 LTS if critical issues arise. - -### Post-Migration - -1. Monitor .NET 11.0 release progression -2. Update to stable package versions -3. Performance tuning -4. Report issues to .NET team - ---- - -**Plan Version**: 1.0 -**Target**: .NET 11.0 (PREVIEW) -**Strategy**: Bottom-Up (Dependency-First) -**Tiers**: 13 (Tier 1 unchanged, Tiers 2-13 migrated)