general-deprecate-api

name	general-deprecate-api
description	Deprecate a public API (class, method, property, type, constant, or context token) following the 2-major-version rule. Use when removing or replacing any publicly exported symbol that external consumers may depend on — includes exports from package index.ts files, global components, extension type aliases, and manifest schemas.
allowed-tools	Read, Write, Edit, Grep, Glob

Deprecate API

Deprecate a public API following Umbraco's breaking changes policy.

What you need from the user

1. What to deprecate — The class, method, property, type, or constant
2. The replacement — What consumers should use instead
3. Current major version — Read from version.json at the repository root

The 2-Major-Version Rule

Deprecated in vN -> earliest removal in vN+2.

Example: deprecated in v17 -> scheduled for removal in v19.

Read version.json to determine the current major version and calculate the removal version.

Both mechanisms are required

Every deprecation must use both:

1. JSDoc @deprecated tag — for IDE warnings and documentation
2. UmbDeprecation runtime warning — for console output at runtime

Step 1: Add the replacement API

Introduce the new API alongside the old one. The old API should delegate to the new implementation internally.