Public API

The published exports of every @angular/* package, snapshotted in goldens/public-api/. The snapshots are version-controlled .api.md files that fail CI on unintended drift.

Why snapshots matter

A new export, a renamed type, or a changed signature is a public API event. Reviewers can't always catch them by reading the diff because the public-API surface is large and spread across many index.ts files. The snapshots make every change visible: a single goldens/ diff in the PR is the entire surface impact.

How they're generated

@microsoft/api-extractor reads each package's .d.ts output and produces a flat .api.md snapshot. The mechanism is wired in goldens/public-api/manage.js:

pnpm public-api:check    # Verify against current state. Fails CI if drift.
pnpm public-api:update   # Regenerate snapshots from the current built .d.ts files.

Run update locally after intentional API changes; commit the resulting diff in the same commit that introduces the change.

Layout

goldens/public-api/
├── animations/
├── common/
├── compiler/
├── compiler-cli/
├── core/
├── elements/
├── forms/
├── language-service/
├── localize/
├── platform-browser/
├── platform-browser-dynamic/
├── platform-server/
├── router/
├── service-worker/
├── ssr/
├── upgrade/
└── zone.js/

Each subdirectory mirrors the entry points the package exposes. For multi-entry-point packages like @angular/common (which has @angular/common, @angular/common/http, @angular/common/upgrade, @angular/common/locales, @angular/common/testing), there's one .api.md per entry point.

What counts as a public API change

Anything visible from a .api.md. The most common forms:

• Adding an exported symbol → CI fails until you regenerate.
• Renaming a symbol → also a remove + add. Treat as a breaking change.
• Changing a signature (parameter types, return type) → may be breaking depending on the change.
• Changing a JSDoc that affects extracted documentation → CI fails until you regenerate.
• Adding/removing a generic parameter → typically breaking.
• Removing an exported symbol → always breaking.

For breaking changes, follow the deprecation cycle documented in contributing-docs/public-api-surface.md: mark @deprecated in one major, ship a migration if needed, remove in the next.

@experimental / @developerPreview

Symbols marked @experimental or @developerPreview show up in the snapshots but the team reserves the right to change them without a deprecation cycle. The matching JSDoc tag is part of the diff, so changing a stable symbol to experimental (or vice versa) is itself a reviewable event.

Bundle-size goldens

A separate set of snapshots under goldens/size-tracking/ records the exported top-level symbols of compiled bundles, generated by tools/symbol-extractor/. These detect when a refactor accidentally pulls a previously-tree-shakable symbol into the always-included surface.

pnpm symbol-extractor:check
pnpm symbol-extractor:update

Circular-deps goldens

Yet another snapshot set: goldens/circular-deps/ tracks known circular import edges. New circulars fail CI; pre-existing ones are tolerated until they're broken intentionally.

pnpm ts-circular-deps:check

In review

A reviewer scanning a PR for impact will:

1. Check whether goldens/public-api/ appears in the diff.
2. If yes, read each .api.md change carefully for backward compatibility.
3. Confirm a BREAKING CHANGE: footer exists if the change is breaking.
4. Confirm a corresponding ng update migration is provided if the change requires user-code edits.

This pattern is what review enforces; it's also a quick-and-honest answer to "does this PR change Angular's public surface?".