OpenParable
Skip to content
← Back to skills

General Deprecate API

Development
general-deprecate-api

General Deprecate API is an Agent Skill for development published in the umbraco/Umbraco-CMS repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/umbraco/Umbraco-CMS/blob/HEAD/src/Umbraco.Web.UI.Client/.claude/skills/general-deprecate-api/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/general-deprecate-api, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

SymbolWhere to place UmbDeprecation
MethodInside the method body
ClassIn the constructor
Property getterInside the getter
ConstantAt module level (executes on import)

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