skip to content

What does Angular's deprecation policy guarantee between an API being marked deprecated and it being removed?

level: middleimportance: should knowfreq 42%

answer

  1. announced, then kept around
  2. changelog plus JSDoc tag
  3. survives at least one major
  4. removal waits for a major

basics

~20 s

A deprecated Angular API is announced in the changelog with a replacement, tagged @deprecated, and kept for at least the next major (about 12 months). Removal happens only in a major; meanwhile it gets only critical and security fixes.

solid answer

~40 s

When Angular deprecates an API it announces it in the **changelog** together with a recommended update path, tags it `@deprecated` so editors strike it through, and shows it struck through in the API docs. The API then stays present in **at least the next major release**, a minimum of about 12 months; after that it becomes a candidate for removal. A deprecation can be announced in **any** release, even a minor, but a **removal only happens in a major**. Until it is removed, the API is maintained like an LTS version: only critical and security issues are fixed. `InjectFlags` is a good example: deprecated in 14.1.0 and removed only in 20.0.0. The policy does not cover developer preview or experimental APIs.

code

ts · 9 lines
ts
import { Injectable, inject } from '@angular/core';
import { AuditLogger } from './audit-logger';

@Injectable({ providedIn: 'root' })
export class OrderService {
  // Before: inject(AuditLogger, InjectFlags.Optional)
  // InjectFlags was deprecated in 14.1.0 and removed in 20.0.0.
  private readonly logger = inject(AuditLogger, { optional: true });
}

go deeper

for a junior

Know the shape: announced in the changelog, marked @deprecated with a replacement, kept for at least one more major, removed only in a major.

for a middle

Explain the fine print: announcements can come in minors, the period is a minimum, and deprecated APIs get only critical and security fixes.

for a senior

Show that you act on deprecations during the current major, reading the Deprecations section of each changelog rather than waiting for a removal to break the build.

for a principal

Weigh how much deprecated-API debt the organisation carries and schedule its removal work so no major upgrade is blocked by a pile of removals.

Angular needs to remove APIs to keep evolving, but a team with a large codebase needs warning and time. The **deprecation policy**, published on angular.dev's versioning and releases page, is the contract between the two. ## The three stages of a deprecation | Stage | What happens | | :-- | :-- | | **Announcement** | The deprecation is listed in the changelog with a recommended update path. The API gets a `@deprecated` JSDoc tag, so editors and IDEs show a hint, and the API reference shows it with strikethrough. | | **Deprecation period** | The API is still present in **at least the next major release**, a period of at least 12 months. Only after that does it become a *candidate* for removal. | | **Removal** | Happens **only in a major release**, never in a minor or a patch. | Two rules inside that table are easy to miss: - **An announcement can come in any release.** Deprecation is a documentation and typing change, so it can ship in a minor. - **The period is a minimum, not a schedule.** "At least the next major" means the API may survive several majors after it was deprecated. ## Real examples from the changelog and the source 1. **`InjectFlags`** was deprecated in **14.1.0**, a minor, when `inject()` gained an options object such as `{ optional: true }`. It was removed in **20.0.0**, six majors later. 2. **`NgIf`, `NgForOf` and `NgSwitch`** (`*ngIf`, `*ngFor`, `*ngSwitch`) carry `@deprecated 20.0` in favour of `@if`, `@for` and `@switch`, and are still shipped in v22.2 with the note "intent to remove in a future major release". 3. **`ChangeDetectionStrategy.Default`** remains in v22 as a deprecated alias of `ChangeDetectionStrategy.Eager`, marked as due to be removed. 4. **`withFetch()`** is deprecated in v22 because `FetchBackend` is now HttpClient's default backend, so the feature is no longer required. In each case the code keeps compiling after the deprecation, and the replacement is named in the tag itself. ## What a deprecated API is still owed Until it is removed, a deprecated API is **maintained according to the LTS policy**: only critical and security issues are fixed. So "deprecated" is not merely a label: - a non-critical bug in a deprecated API will likely never be fixed; - new capabilities land only on the replacement; - the API can disappear in any major after the minimum period. ## What the policy does not cover - **Developer preview and experimental APIs.** The versioning and deprecation policies explicitly do not apply to them; they can change in any release, even a patch. - **Critical security fixes.** The compatibility policy allows a backward-incompatible change in exceptional cases, such as a critical security patch, with explicit notice. - **Private APIs.** Only the documented public API surface is covered; code that reaches into internals has no guarantee at all. ## How a team should use it 1. **Read the Deprecations section of each release's changelog**, not only the Breaking Changes section: today's deprecations are a later major's removals. 2. **Clear deprecated usages during the current major**, while both the old and new APIs work, instead of discovering them when an upgrade removes them. 3. **Do not plan around the minimum.** A removal is legal in the first major after the period ends, so treat every deprecation as removable at the next major. ## Reading a deprecation tag The tag in the source usually tells you both when the clock started and what to do: | Tag in v22.2 | What it tells you | Earliest legal removal | | :-- | :-- | :-- | | `@deprecated 20.0` on `NgIf`, with "Use the `@if` block instead" | Deprecated in a major, replacement named | 22.0, since it had to survive v21 | | `@deprecated` on `withFetch()` (announced in 22.0): "`FetchBackend` is the default `HttpBackend`" | Deprecated in a major; the call is simply no longer needed | 24.0, since it must survive v23 | | `@deprecated 22.1` on JSONP support: "Intent to remove in future versions" | Deprecated in a minor, for security reasons | 24.0, since it must survive v23 | "Earliest legal" is only the floor; `NgIf` is still shipped in v22.2 although removing it in 22.0 would have been allowed. ## A common confusion Deprecation is not the same as a breaking change. Marking an API deprecated breaks nothing; it starts a clock. The breaking change is the later removal, and the policy's job is to guarantee that removal never comes as a surprise and never arrives in a minor release.

  • Can a deprecated Angular API be removed in a minor release?
    No. A deprecation can be announced in any release, but removal only happens in a major, because minors are fully backward-compatible by policy. The exceptions are APIs that were never stable, meaning developer preview or experimental ones, and rare critical security fixes announced explicitly.
  • Is a deprecated Angular API guaranteed to be removed exactly one major after it was deprecated?
    No. It must survive at least the next major, after which it is only a candidate for removal. InjectFlags was deprecated in 14.1.0 and removed in 20.0.0, and NgIf, deprecated in 20.0, still ships in v22.2.
  • Does a deprecated Angular API still get bug fixes?
    Only critical and security fixes: until removal it is maintained under the LTS rules. Ordinary bugs and new options go to the replacement API, which is one more reason to migrate during the current major.

It works like a bus route announced for withdrawal: a notice is posted with the alternative route, the bus keeps running at least until the next yearly timetable, it gets safety repairs but no new stops, and it can only be dropped when a new timetable starts.

saying these in an interview costs you the question

  • Deprecated Angular APIs are removed in the next minor release.
  • Angular only announces deprecations in major releases.
  • A deprecated API is always removed exactly one major after deprecation.
  • Deprecated APIs keep receiving ordinary bug fixes until they are removed.
  • Developer preview APIs get the same deprecation period as stable ones.