Toolbox

Deprecation policy with dates

Deprecate with dates CI enforces: 22 checks, a JSON registry, a checker that fails on overdue removals, notice generation and a codemod.

What it is

Field Guide 09: a 22-item deprecation policy with six months of minimum notice and removals only in major windows. The kit adds a JSON registry with announce and removal dates, a zero-dependency checker with 10 rules that fails CI on short notice, patch-release deprecations and overdue removals, a generator for the notice, JSDoc line, console warning and changeset, a dev-only warning helper and a jscodeshift codemod for the Button href deprecation.

When to use

When deprecations linger for years, removals surprise teams who missed the announcement, or nobody can say when a deprecated API will actually go.

How to use

Set your minimum notice, major windows and usage threshold in the registry's policy block
Register every current deprecation in deprecations.json with its dates and replacement
Run node scripts/check-deprecations.mjs on every pull request and on a daily schedule
Generate each notice with node scripts/deprecation-notice.mjs DEP-NNNN
Ship a codemod for mechanical changes and test it with node scripts/test-codemod.mjs

Before you start

Prerequisites and when to skip this.

Prerequisites

Semantic versioning with planned major releases
A way to measure usage across consuming repositories (code search is enough)

When NOT to use this

Experimental or beta APIs that you promised could change without notice
Internal code no other team imports

Consider instead

You are retiring a whole package, not an API inside one: Register it with kind package and add an npm deprecate message on the removal date

Downloads

Guide (PDF)Full kit (ZIP): PDF, HTML, Markdown, registry, checker, codemod

One-page RFC templateMonthly release cadenceEnterprise UX that ships

The share link includes source tracking so LinkedIn traffic stays measurable in analytics.

Share on LinkedIn