deprecate-cds-api

name	deprecate-cds-api
description	Deprecates a CDS component, hook, or other exported symbol with consistent JSDoc, version tags, and docsite metadata across every public export path (web, mobile, common, visualization), not only the original package. Use whenever the user asks to deprecate a CDS component or API, mark something as deprecated, add @deprecated / @deprecationExpectedRemoval, or update deprecation warnings in apps/docs metadata under components or hooks (webMetadata.json / mobileMetadata.json / metadata.json). Also use when replacing a component or hook and sunsetting the old one. Always finish by running `yarn nx run <project>:lint` on modified packages so `internal/deprecated-jsdoc-has-removal-version` passes.
allowed-tools	Read, Grep, Glob, StrReplace, Bash(yarn nx run:*)
argument-hint	<SymbolName or path> — replacement — [@deprecationExpectedRemoval major e.g. v10] — [optional notes]

Deprecate CDS public API

Automate the standard CDS deprecation workflow for symbols exported from packages/web, packages/mobile, or packages/common.

Inputs to confirm first

1. What is being deprecated? Component name, hook, prop, or other exported symbol.
2. What should consumers use instead? The replacement must be named in JSDoc and in docs warning text.
3. Which major should @deprecationExpectedRemoval use? (e.g. v9, v10.) Ask the user to confirm if they have not already stated it. If they want a default, suggest the next major from the relevant package.json (see Step 2) and confirm they accept it before editing.

---

Step 0 — Discover every public export (all packages)

Deprecate the symbol everywhere it is publicly reachable, not only where it is first implemented.

1. For each CDS package (web, mobile, common), trace the symbol from that package’s package.json exports map → barrel / index files → the module that declares or re-exports the symbol.
2. Grep for the symbol name under packages/<name>/src (e.g. export { Foo, export * from, Foo as) to catch re-exports and alternate entry paths.
3. Every package that publicly exports the symbol must end up with deprecation coverage: primary implementation and any re-export site where your tooling or consumers would not see JSDoc from the source file (add JSDoc on the re-export line or duplicate the tags as needed so imports from @coinbase/cds-web, @coinbase/cds-mobile, @coinbase/cds-common, etc. all surface the deprecation).

Do not skip a package because the symbol is “originally” defined elsewhere—if consumers can import it from that package, it must be deprecated there too.

---

Step 1 — JSDoc on the deprecated symbol

Add or extend JSDoc immediately above the deprecated export (component, function, type alias, const, interface field, etc.).

Use the standard JSDoc tag @deprecated (not @deprecate).

Required shape:

/**
 * …existing description if any…
 *
 * @deprecated <Clear guidance referencing the replacement>. This will be removed in a future major release.
 * @deprecationExpectedRemoval v<NEXT_MAJOR>
 */

Rules:

• The @deprecated line must end with exactly: This will be removed in a future major release. (same sentence as the rest of the deprecation message, as in existing CDS examples).
• @deprecationExpectedRemoval must match v + version (e.g. v9 or v9.0.0; full semver is allowed by ESLint).

The repo’s ESLint rule internal/deprecated-jsdoc-has-removal-version (libs/eslint-plugin-internal) enforces the prose ending and the presence of @deprecationExpectedRemoval; lint must pass after edits (see Step 6).

---

Step 2 — Removal version for @deprecationExpectedRemoval

The tag must satisfy @deprecationExpectedRemoval v… as enforced by ESLint (e.g. v10 or v10.0.0).

1. Confirm with the user which major N to use, unless they already specified it in Inputs (e.g. “remove in v10” → use v10).
2. Default suggestion when the user wants a recommendation: read the version field from the relevant package.json and set N = current major + 1.
   • packages/web, packages/mobile, and packages/common always share the same semver — read version from any one of them (e.g. 8.60.0 → suggest v9).
3. After agreeing on N, use @deprecationExpectedRemoval v<N> everywhere for this deprecation (same Step 3).

Do not assume the default without checking—either the user names N, or they accept the suggested next-major after you show the current version.

---

Step 3 — Consistency across export surfaces

• Use the same @deprecated guidance and @deprecationExpectedRemoval v<N> value everywhere the symbol is exported (adjust wording only if a platform’s API genuinely differs).
• Components and hooks that exist as separate web and mobile implementations: deprecate both when both packages export the symbol.
• Shared symbols in packages/common that are also re-exported from web or mobile: follow Step 0 — ensure deprecation is visible on every public import path (common barrels and web/mobile re-exports if applicable).
• Visualization packages: same rules whenever those packages export the symbol.

---

Step 4 — Docsite metadata (apps/docs/docs)

Only when the symbol has existing docs under the docs app. Do not add new doc folders unless the docs workflow already expects them.

Components (apps/docs/docs/components/)

1. Locate the folder, e.g. apps/docs/docs/components/<category>/<ComponentName>/.
2. If present, edit webMetadata.json and/or mobileMetadata.json (some components have both; some only one).
3. Add or update the top-level warning string:

"warning": "This component is deprecated. Please use {replacement} instead."

Examples:

• "Please use Tabs instead."
• "Please use MediaCard instead."

Match the tone of existing deprecations when the replacement is not a single component name (e.g. “Use indeterminate ProgressCircle for loading indicators instead.”) — still keep the opening: This component is deprecated.

Hooks (apps/docs/docs/hooks/)

1. Locate the hook folder, e.g. apps/docs/docs/hooks/<hookName>/.
2. Hooks may use webMetadata.json and mobileMetadata.json, or a single shared metadata.json — update whichever file(s) exist for that hook.
3. Add or update the top-level warning string using hook wording:

"warning": "This hook is deprecated. Please use {replacement} instead."

Use the same {replacement} phrasing as in JSDoc. If the replacement is not a single hook name, adapt the sentence but keep the opening: This hook is deprecated.

---

Step 5 — Verification checklist

• Every public export path across packages that expose the symbol has been found (Step 0) and carries deprecation (implementation and re-exports as needed).
• @deprecated includes replacement guidance and the exact closing sentence about future major removal.
• @deprecationExpectedRemoval v<N> matches the confirmed removal major (Step 2), not an unverified default.
• Web + mobile implementations and metadata (when applicable) are updated; nothing skipped because the symbol was “only” defined in common or another package.
• warning in metadata matches the replacement story: this component is deprecated for component docs, this hook is deprecated for hook docs (apps/docs/docs/hooks/).
• yarn nx run <project>:lint has been run for every touched project (Step 6) and passes.

---

Step 6 — Run ESLint (required)

After all edits, run the lint target on every Nx project that contains changed source files so internal/deprecated-jsdoc-has-removal-version (and the rest of the package lint config) passes.

Use the workspace convention:

yarn nx run <project>:lint

Examples: web, mobile, common — run each project you touched. Fix any reported issues before finishing (most often: missing @deprecationExpectedRemoval, or @deprecated text not ending with the standard sentence).

---

Reference examples in-repo

• JSDoc: search for @deprecationExpectedRemoval under packages/web/src (e.g. TabNavigation.tsx, Spinner.tsx).
• ESLint: libs/eslint-plugin-internal — rule deprecated-jsdoc-has-removal-version (exposed as internal/deprecated-jsdoc-has-removal-version in the root eslint.config.mjs).
• Metadata: search for "warning": "This component is deprecated under apps/docs/docs/components; hook docs live under apps/docs/docs/hooks/ (use This hook is deprecated for hook warning text).