Skip to content

Files

Latest commit

 

History

History
114 lines (86 loc) · 5.49 KB

public-api-surface.md

File metadata and controls

114 lines (86 loc) · 5.49 KB

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 a 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 (ɵ), 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.

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.

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 yarn to execute the Bazel target in your terminal shell of choice (a recent version of bash is recommended).

yarn 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.

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:
  yarn bazel run //packages/core:core_api.accept