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.

// New method (the replacement)
requestSummary() {
    // Real implementation here
}

Step 2: Add JSDoc @deprecated tag

Include: what was deprecated, when, the replacement, and when it will be removed.

/**
 * @deprecated Deprecated since v17. Use `requestSummary()` instead. Will be removed in v19.
 */
getSummary() {
    return this.requestSummary();
}

For types and interfaces:

/**
 * @deprecated Deprecated since v17. Use `UmbNewInterface` instead. Scheduled for removal in Umbraco 19.
 */
export interface UmbOldInterface {
    // ...
}

Step 3: Add UmbDeprecation runtime warning

import { UmbDeprecation } from '@umbraco-cms/backoffice/utils';

/**
 * @deprecated Deprecated since v17. Use `requestSummary()` instead. Will be removed in v19.
 */
getSummary() {
    new UmbDeprecation({
        deprecated: 'UmbMyContext.getSummary()',
        removeInVersion: '19.0.0',
        solution: 'Use requestSummary() instead.',
    }).warn();

    return this.requestSummary();
}

Placement by symbol type

For deprecated classes

/**
 * @deprecated Deprecated since v17. Use `UmbNewRepository` instead. Will be removed in v19.
 */
export class UmbOldRepository extends UmbControllerBase {
    constructor(host: UmbControllerHost) {
        super(host);

        new UmbDeprecation({
            deprecated: 'UmbOldRepository is deprecated.',
            removeInVersion: '19.0.0',
            solution: 'Use UmbNewRepository instead.',
        }).warn();
    }
}

Step 4: Delegate old to new

The deprecated API must keep working. Delegate to the replacement internally:

/**
 * @deprecated Deprecated since v17. Use `getContentTypeUnique()` instead. Will be removed in v19.
 */
getContentTypeId(): string | undefined {
    new UmbDeprecation({
        deprecated: 'UmbMemberWorkspaceContext.getContentTypeId()',
        removeInVersion: '19.0.0',
        solution: 'Use getContentTypeUnique() instead.',
    }).warn();

    return this.getContentTypeUnique();
}

Step 5: Update internal callers

All internal code must use the new API. No code within the repository should call the deprecated member.

What counts as a breaking change

Any of the following to a publicly exported symbol:

• Removing/renaming an exported class, function, type, constant, or context token
• Removing/renaming a public method or property
• Changing a public method signature (required params, return type)
• Removing/renaming a subpath export from package.json
• Changing an extension type alias or manifest schema
• Removing/renaming a global component's tag name

Not breaking: Internal code (unexported classes, private methods) can be changed freely without deprecation.

Checklist

• Replacement API introduced and working
• @deprecated JSDoc tag added with: since version, replacement, removal version
• UmbDeprecation runtime warning added with deprecated, removeInVersion, solution
• Deprecated code delegates to the replacement (still works)
• All internal callers updated to use the new API
• Removal version follows the 2-major-version rule (current + 2)
• Compiles: npm run compile