Skip to content

DEPRECATION.md

Latest commit

 

History

History
86 lines (63 loc) · 3.01 KB

DEPRECATION.md

File metadata and controls

86 lines (63 loc) · 3.01 KB
Raw

Deprecation Policy — @tikka/sdk

This document governs how public API symbols are removed from @tikka/sdk and its sub-path exports (/read, /write, /light).

API surface report

Every public export across all four entry points is recorded in committed Markdown reports under sdk/etc/:

Report file Entry point
etc/tikka-sdk.api.md @tikka/sdk (main, full NestJS)
etc/tikka-sdk-read.api.md @tikka/sdk/read (read-only)
etc/tikka-sdk-write.api.md @tikka/sdk/write (signing + submission)
etc/tikka-sdk-light.api.md @tikka/sdk/light (browser-light)

These files are generated by @microsoft/api-extractor and must be committed with every change that touches the public API surface. CI fails when the committed report does not match the compiled output (see .github/workflows/ci.yml, step API surface report check).

To regenerate all reports locally after a build:

pnpm run api-extractor:all

SemVer bump rules

Change type Required bump
New export added minor
Existing export changed in a backwards-compatible way (e.g. new optional param) minor
Existing export removed or renamed major
Existing export changed in a breaking way (e.g. required param added, return type narrowed) major
Internal-only change (no diff in etc/*.api.md) patch

Use the diff in the etc/*.api.md report as the primary input when choosing the changeset bump during release review (docs/RELEASE.md).

Deprecation lifecycle

Removals follow a two-release minimum notice period:

  1. Deprecate — Annotate the symbol with a @deprecated TSDoc tag and add a migration note. The @deprecated tag appears in the API report and in generated docs, making it visible in PR review.

    /**
 * @deprecated Use `ReadOnlyRaffleService` instead. Will be removed in the
 * next major release.
 */
export class LegacyRaffleReader { … }

  2. Report diff — Regenerate the relevant etc/*.api.md file and commit it alongside the deprecation annotation so reviewers see the @deprecated flag in the diff.

  3. Remove — The symbol may be removed in the next major version after the deprecating release has been published. The removal must again be reflected by a report diff committed in the same PR.

Skipping the deprecation step and removing a symbol directly is only permitted for symbols that have never appeared in a published release (i.e., they were added and removed within the same major version cycle without a public release in between).

Enforcement

  • CI runs api-extractor run (without --local) for all four entry points after every build. A stale or missing etc/*.api.md file causes the step to exit non-zero and blocks merge.
  • The API report diff is a required part of every PR that touches sdk/src/.
  • Reviewers must confirm that any symbol marked @deprecated in the diff is accompanied by a migration note before approving.