angular/contributing-docs/public-api-surface.md

# Supported public API surface of angular/angular code

Angular's SemVer, release schedule, and deprecation policy applies to these npm packages:

- `@angular/animations`
- `@angular/common`
- `@angular/core`
- `@angular/elements`
- `@angular/forms`
- `@angular/platform-browser-dynamic`
- `@angular/platform-browser`
- `@angular/platform-server`
- `@angular/router`
- `@angular/service-worker`
- `@angular/upgrade`

The `@angular/compiler` package is explicitly excluded from this list. The compiler is generally
considered private/internal API and may change at any time. Only very specific use-cases, such as
linters or IDE integration, require direct access to the compiler API. If you are
working on this kind of integration, please reach out to us first.

Additionally, only the command line usage (not direct use of APIs) of
`@angular/compiler-cli` is covered.

Within the supported packages, Angular keeps stable:

- Symbols exported via the main entry point (e.g. `@angular/core`) and testing entry point (
  e.g. `@angular/core/testing`). This applies to both runtime/JavaScript values and TypeScript
  types.
- Symbols exported via global namespace `ng` (e.g. `ng.core`)

We explicitly consider the following to be _excluded_ from the public API:

- Any file/import paths within our package except for the `/`, `/testing` and `/bundles/*` and other
  documented package entry-points.
- Constructors of injectable classes (services and directives). Use dependency injection to obtain
  instances of these classes
- Any class members or symbols marked as `private`, or prefixed with
  underscore (`_`), [barred latin o](https://en.wikipedia.org/wiki/%C6%9F) (`ɵ`), and double barred latin o (`ɵɵ`).
- Extending any of our classes unless the support for this is specifically documented in the API
  reference.
- The contents and API surface of the code generated by Angular's compiler.
- The `@angular/core/primitives` package, including its descendant entry-points.

Our peer dependencies (such as TypeScript, Zone.js, or RxJS) are not considered part of our API
surface, but they are included in our SemVer policies. We might update the required version of these
dependencies in minor releases if the update doesn't cause breaking changes for Angular
applications. Peer dependency updates that result in non-trivial breaking changes must be deferred
to major Angular releases.

<a name="final-classes"></a>

## Extending Angular classes

All classes in Angular's public API are considered `final`. They should not be extended unless
explicitly stated in the API documentation.

Extending such classes is not supported, since protected members and internal implementation may
change outside major releases.

<a name="golden-files"></a>

## Golden files

Angular tracks the status of the public API in a _golden file_, maintained with a tool called the
_public API guard_.
If you modify any part of a public API in one of the supported public packages, the PR will fail a
test in CI with an error message that instructs you to accept the golden file.

The public API guard provides a Bazel target that updates the current status of a given package. If
you add to or modify the public API in any way, you must use [pnpm](https://pnpm.io/) to execute
the Bazel target in your terminal shell of choice (a recent version of `bash` is recommended).

```shell
pnpm bazel run //packages/<modified_package>:<modified_package>_api.accept
```

Here is an example of a CI test failure that resulted from adding a new allowed type to a public
property in `core.d.ts`. Error messages from the API guard use [`git-diff` formatting](https://git-scm.com/docs/git-diff#_combined_diff_format).

```
FAIL: //packages/core:core_api (see /home/circleci/.cache/bazel/_bazel_circleci/9ce5c2144ecf75d11717c0aa41e45a8d/execroot/angular/bazel-out/k8-fastbuild/testlogs/packages/core/core_api/test_attempts/attempt_1.log)
INFO: From Action packages/compiler-cli/ngcc/test/fesm5_angular_core.js:
[BABEL] Note: The code generator has deoptimised the styling of /b/f/w/bazel-out/k8-fastbuild/bin/packages/core/npm_package/fesm2015/core.js as it exceeds the max of 500KB.
FAIL: //packages/core:core_api (see /home/circleci/.cache/bazel/_bazel_circleci/9ce5c2144ecf75d11717c0aa41e45a8d/execroot/angular/bazel-out/k8-fastbuild/testlogs/packages/core/core_api/test.log)

FAILED: //packages/core:core_api (Summary)
      /home/circleci/.cache/bazel/_bazel_circleci/9ce5c2144ecf75d11717c0aa41e45a8d/execroot/angular/bazel-out/k8-fastbuild/testlogs/packages/core/core_api/test.log
      /home/circleci/.cache/bazel/_bazel_circleci/9ce5c2144ecf75d11717c0aa41e45a8d/execroot/angular/bazel-out/k8-fastbuild/testlogs/packages/core/core_api/test_attempts/attempt_1.log
INFO: From Testing //packages/core:core_api:
==================== Test output for //packages/core:core_api:
/b/f/w/bazel-out/k8-fastbuild/bin/packages/core/core_api.sh.runfiles/angular/packages/core/npm_package/core.d.ts(7,1): error: No export declaration found for symbol "ComponentFactory"
--- goldens/public-api/core/core.d.ts	Golden file
+++ goldens/public-api/core/core.d.ts	Generated API
@@ -563,9 +563,9 @@
     ngModule: Type<T>;
     providers?: Provider[];
 }

-export declare type NgIterable<T> = Array<T> | Iterable<T>;
+export declare type NgIterable<T> = Iterable<T>;

 export declare interface NgModule {
     bootstrap?: Array<Type<any> | any[]>;
     declarations?: Array<Type<any> | any[]>;


If you modify a public API, you must accept the new golden file.


To do so, execute the following Bazel target:
  pnpm bazel run //packages/core:core_api.accept

```