telerik-blazor-version-upgrade

name

telerik-blazor-version-upgrade

description

Guides Telerik UI for Blazor version upgrades, including breaking changes, rendering changes, framework compatibility, and safe upgrade planning. Use when a developer asks whether an upgrade is safe, what changed between releases, how to approach upgrading across multiple versions, or how to prepare before upgrading. This skill explains upgrade implications and planning—it does not modify projects or perform migrations. When deeper implementation assistance is needed, bridge to the Telerik MCP server. Do NOT use for first-time installation (route to telerik-blazor-getting-started) or licensing/setup questions unrelated to upgrading. Trigger on "Should I upgrade Telerik UI for Blazor?", "Upgrade Telerik Blazor", "Breaking changes", "Rendering changes", "Upgrade path", "Release history", "What changed in the latest release?", "Components broke after upgrade", "Upgrade from 6 to 8", "Old version support", "Supported versions".

Telerik UI for Blazor Version Upgrade Skill

Purpose

This skill teaches AI agents how to reason about Telerik UI for Blazor upgrades.

It helps developers understand:

• whether upgrading is worthwhile
• what risks are involved
• which breaking changes apply
• which rendering changes apply
• how to plan a safe upgrade
• when Telerik MCP tools can help with implementation

This skill does not execute migrations, modify projects, or replace the official upgrade documentation.

---

Reference Files

Read these files whenever version-specific information is required.

• references/breaking-changes-by-version.md
• references/rendering-changes-by-version.md
• references/framework-compatibility.md
• references/response-templates.md

---

Scope

This skill covers:

• Telerik UI for Blazor versioning
• upgrade planning
• breaking changes
• rendering changes
• .NET compatibility
• supported version policy
• common upgrade pitfalls
• upgrade readiness
• MCP bridge

This skill does NOT cover:

• first-time installation (route to telerik-blazor-getting-started)
• licensing questions or licensing errors (route to telerik-blazor-licensing)
• project creation
• code migration
• detailed component usage

---

Telerik UI for Blazor Versioning Model

versioning:
    package_versioning:
        All Telerik UI for Blazor packages are released together and should use the same version.
    semantic_versioning:
        major:
            May introduce breaking changes and rendering changes.
        minor:
            Adds new functionality while maintaining backward compatibility.
        patch:
            Bug fixes only.
    framework_compatibility:
        Always verify supported .NET and Blazor versions before upgrading.
    recommendation:
        Keep all Telerik UI for Blazor packages    

---

Upgrade Decision Framework

Agents should never recommend "always upgrade."

Instead they should reason through the following questions.

upgrade_decision:
    determine_current_version
    determine_target_version
    identify_reason:
        examples:
            - new feature
            - bug fix
            - .NET upgrade
            - support policy
            - maintenance
    determine_upgrade_distance:
        - patch
        - minor
        - one major
        - multiple major
    verify_environment:
        - .NET SDK version
        - Blazor hosting model
        - supported framework
    identify_customizations:
        - custom CSS
        - templates
        - JavaScript interop
        - component customization
    recommend:
        
        
        
        
        

---

Decision Tree

decision_tree:
    user_asks_should_i_upgrade:
        gather_context:
            - current Telerik UI for Blazor version
            - target Telerik UI for Blazor version
            - current .NET version
            - Blazor hosting model
            - upgrade motivation
        consult:
            - framework-compatibility.md
            - release-summary.md
            - breaking-changes-by-version.md
            - rendering-changes-by-version.md
        evaluate:
            - upgrade distance
            - framework compatibility
            - breaking changes
            - rendering changes
            - project customizations
        recommend:
                
                  
                   
                    
        
                       

---

Safe Upgrade Logic

upgrade_rules:
    patch:
        risk: very_low
        recommendation:
            Upgrade directly.
    minor:
        risk: low
        recommendation:
            Review release notes and test.
    one_major:
        risk: moderate
        recommendation:
            - Review breaking changes.
            - Review rendering changes.
            - Test the application.
    multiple_major:
        risk: high
        recommendation:
            - Upgrade one major version at a time.
            - Review each major release separately.
            - Validate the application after  
    
        

---

Breaking Changes vs Rendering Changes

Agents must distinguish these concepts.

breaking_changes:
    definition:
        Existing application code may require modification.
rendering_changes:
    definition:
        Generated HTML and/or CSS output changed while APIs may remain compatible.
    common_symptoms:
        - custom CSS no longer applies
        - layout changes
        - spacing differences
        - visual regressions
    recommendation:
        Always review rendering changes documentation after major upgrades.

---

Framework Compatibility

Framework compatibility is an essential part of every upgrade recommendation.

Before recommending an upgrade, agents should consult:

• references/framework-compatibility.md

framework:
    verify:
        - Current .NET SDK version
        - Target .NET SDK version
        - Blazor hosting model
    recommendation:
        Verify that the target Telerik UI for Blazor version supports the intended .NET version before recommending an upgrade.
agent_behavior:
    if_dotnet_version_unknown:
        Ask the developer which .NET version the project currently targets.
    before_recommending_upgrade:
        Consult framework-compatibility.md.
    if_framework_upgrade_required:
        Explain that the Telerik UI            

---

Browser Compatibility

Browser compatibility is tied to the Telerik UI for Blazor release.

browser_compatibility:
    policy:
        Each Telerik UI for Blazor release supports the browser versions available at the time of that release.
    implication:
        Browser versions released after a Telerik UI for Blazor release may introduce rendering or behavioral issues that are addressed only in later Telerik releases.
agent_behavior:
    if_browser_issue_is_reported:
        Ask:
            - Which browser?
            - Which browser version?
            - Which Telerik    

                      
    
                                   

---

Upgrade Readiness Checklist

checklist:
    - Current Telerik UI for Blazor version known
    - Target version known
    - .NET version verified
    - Breaking changes reviewed
    - Rendering changes reviewed
    - Release summary reviewed
    - Custom CSS identified
    - Testing plan prepared

---

Common Upgrade Pitfalls

When discussing upgrade problems, consult:

• references/breaking-changes-by-version.md
• references/rendering-changes-by-version.md

Typical issues include:

pitfalls:
    skipped_major_versions
    outdated_custom_css
    unsupported_dotnet_version
    mixed_package_versions
    ignored_breaking_changes
    missing_regression_testing

---

MCP Bridge

Once the upgrade strategy has been decided, Telerik MCP can assist with implementation.

mcp:
    component_assistant:
        use_for:
            - Updating deprecated APIs
            - Replacing obsolete component usage
            - Explaining new component behavior
    page_generator:
        use_for:
            - Rebuilding pages using current component APIs
    recommendation:
        Use MCP after the upgrade plan has been established.

---

Routing Rules

route_to_telerik_blazor_getting_started_when:
    - installing Telerik UI for Blazor
    - creating a new project
route_to_telerik_blazor_licensing_when:
    - the developer reports licensing errors
    - license activation questions
    - trial or subscription questions
    - license expiration or renewal questions
    - licensing issues that appear after upgrading
stay_in_this_skill_when:
    - planning upgrades
    - comparing versions
    - reviewing release changes
    - discussing rendering changes
       
       

---

Security

security:
    skill_is_read_only: true
    executes_commands: false
    modifies_projects: false
    accesses_source_code: false
    phones_home: false

---

Anti-Patterns

avoid:
    - Recommending "always upgrade."
    - Ignoring the developer's current version.
    - Confusing rendering changes with breaking changes.
    - Recommending multi-major upgrades without planning.
    - Ignoring .NET compatibility.
    - Giving version-specific advice without consulting the reference files.