wjones/pgsql-jellyfin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
35923c59e06b4b77c47360d8debfaf436c957e75
pgsql-jellyfin/.github/upgrades/scenarios/new-dotnet-version_02bc64/plan.md
T
wjones 3b161b4731 Add .NET 11.0 upgrade plan, assessment, and risk docs 
Added a detailed .NET 11.0 (PREVIEW) upgrade plan (plan.md) outlining a bottom-up migration strategy, dependency analysis, risk management, testing, and success criteria for the Jellyfin solution. Introduced assessment.md, assessment.json, and assessment.csv with comprehensive compatibility analysis for all 41 projects, confirming no blocking issues. Added Risk Management Strategies.md detailing mitigation and rollback procedures. Also included scenario.json describing the upgrade scenario and selected strategy. No existing files were changed.
2026-03-05 21:29:18 -05:00

88 KiB
Raw Blame History

.NET 11.0 (PREVIEW) Upgrade Plan

Table of Contents

  1. Executive Summary
  2. Migration Strategy
  3. Detailed Dependency Analysis
  4. Project-by-Project Plans
  5. Risk Management
  6. Testing & Validation Strategy
  7. Complexity & Effort Assessment
  8. Source Control Strategy
  9. 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: 
      <TargetFramework>net11.0</TargetFramework>
    • 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: 
      <TargetFramework>net11.0</TargetFramework>

  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: 
      <TargetFramework>net11.0</TargetFramework>

  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 <TargetFramework>net11.0</TargetFramework>
    • 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: <TargetFramework>net11.0</TargetFramework>
  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: <TargetFramework>net11.0</TargetFramework>
  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: <TargetFramework>net11.0</TargetFramework>
  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: <TargetFramework>net11.0</TargetFramework>
  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: <TargetFramework>net11.0</TargetFramework>
  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: <TargetFramework>net11.0</TargetFramework>
  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: <TargetFramework>net11.0</TargetFramework>
  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: <TargetFramework>net11.0</TargetFramework>
    • 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: <TargetFramework>net11.0</TargetFramework>
    • 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 <TargetFramework>net11.0</TargetFramework>
  • 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 <TargetFramework>net11.0</TargetFramework>
  • 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)

Reference in New Issue View Git Blame Copy Permalink