Angular Public API interface design

According to the definition of Angular official Github repo , Angular's semver, timed release cycle and deprecation policy currently apply to these npm packages:

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

The one deliberately omitted from this list is @angular/compiler, which is currently considered a low-level API and may undergo internal changes. These changes will not affect any applications or libraries that use higher-level APIs (command line interface or JIT compilation via @angular/platform-browser-dynamic). Only very specific use cases require direct access to the compiler API (mainly IDE, linter, etc. tool integration).

The package @angular/bazel is currently an Angular Labs project and is not covered by the public API guarantee.

In addition, only the command line usage of @angular/compiler-cli is covered (not directly using the API).

Other projects developed by the Angular team, such as angular-cli and Angular Material, will be included in these or similar guarantees as they mature in the future.

Among the supported packages, Angular provides the following guarantees:

(1) Symbols exported through the main entry point (such as @angular/core) and the test entry point (such as @angular/core/testing). This applies to runtime JavaScript values and TypeScript types.

(2) Symbols exported through the global namespace ng (eg ng.core)

(3) Packages located in the bundles/ directory of the npm package (for example @angular/core/bundles/core.umd.js)

The following is not Angular public API surface:

(1) Any file/import path in our package, except /, /testing and /bundles/* and other recorded package entry points.
(2) Constructors of injectable classes (services and instructions)-please use DI to obtain instances of these classes
(3) Any class member or symbol marked as private, or prefixed with underscore (_), forbidden Latin o (ɵ), and double forbidden Latin o (ɵɵ).
(4) Extend any of our classes, unless support for this is specifically documented in the API documentation
(5) The content and API surface of the code generated by the Angular compiler (with one obvious exception: the existence and name of the NgModuleFactory instance derived from the generated code is guaranteed)

Angular peer dependencies (such as TypeScript, Zone.js, or RxJS) are not considered part of the Angular API surface, but they are included in our SemVer policy. If the update does not cause major changes to the Angular application, we may update the required version of any of these dependencies in a minor version. Peer dependency updates that cause major disruptive changes must be postponed to the major Angular version.

Extending Angular classes

Unless explicitly stated in the API documentation, all classes in the Angular public API are final (they should not be extended).

The extension of such final classes is not supported, because protected members and internal implementations may change outside the major version.

Golden files

Angular tracks the state of public APIs in a golden file, which is maintained by a tool called public API protection. If you modify any part of the public API in one of the supported public packages, the PR may fail the test in CI and display an error message instructing you to accept the gold file.

The public API guard provides a Bazel target to update the current state of a given package. If you add or modify the public API in any way, you must use yarn to execute the Bazel target in the terminal shell of your choice (the latest version of bash is recommended).