Graham/angular-cli
1
0
Fork 0
mirror of https://github.com/angular/angular-cli.git synced 2025-05-23 23:59:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add documentation for API guardian ()

Browse Source
This commit is contained in:
Alan Agius 2018-11-30 23:07:36 +01:00 committed by vikerman
parent cd66d27170
commit f392f18e42
2 changed files with 72 additions and 0 deletions

36
CONTRIBUTING.md

@ -12,6 +12,7 @@ to follow:
- [Coding Rules](#rules)
- [Commit Message Guidelines](#commit)
- [Signing the CLA](#cla)
- [Updating the Public API](#public-api)
## <a name="coc"></a> Code of Conduct
Help us keep Angular open and inclusive. Please read and follow our [Code of Conduct][coc].
@ -274,3 +275,38 @@ changes to be accepted, the CLA must be signed. It's a quick process, we promise
[individual-cla]: http://code.google.com/legal/individual-cla-v1.0.html
[js-style-guide]: https://google.github.io/styleguide/jsguide.html
[stackoverflow]: http://stackoverflow.com/questions/tagged/angular-devkit
## <a name="public-api"></a> Updating the Public API
Our Public API is protected with TS API Guardian. This is a tool that keeps track of public API surface of our packages.
To test if your change effect the public API you need to run the API guardian on that particular package.
For example in case `@angular-devkit/core` package was modified you need to run:
```bash
bazel test //etc/api:angular_devkit_core_api
```
You can also test all packages by running:
```bash
bazel test //etc/api ...
```
If you modified the public API, the test will fail. To update the golden files you need to run:
```bash
bazel run //etc/api:angular_devkit_core_api.accept
```
**Note**: In some cases we use aliased symbols to create namespaces.
Example:
```javascript
import * as foo from './foo';
export { foo };
```
There are currently not supported by the API guardian.
To overcome this limitiation we created `_golden-api.ts` in certain packages.
When adding a new API, it might be the case that you need to add it to `_golden-api.ts`.

36
scripts/templates/contributing.ejs

@ -12,6 +12,7 @@ to follow:
- [Coding Rules](#rules)
- [Commit Message Guidelines](#commit)
- [Signing the CLA](#cla)
- [Updating the Public API](#public-api)
## <a name="coc"></a> Code of Conduct
Help us keep Angular open and inclusive. Please read and follow our [Code of Conduct][coc].
@ -263,3 +264,38 @@ changes to be accepted, the CLA must be signed. It's a quick process, we promise
[individual-cla]: http://code.google.com/legal/individual-cla-v1.0.html
[js-style-guide]: https://google.github.io/styleguide/jsguide.html
[stackoverflow]: http://stackoverflow.com/questions/tagged/angular-devkit
## <a name="public-api"></a> Updating the Public API
Our Public API is protected with TS API Guardian. This is a tool that keeps track of public API surface of our packages.
To test if your change effect the public API you need to run the API guardian on that particular package.
For example in case `@angular-devkit/core` package was modified you need to run:
```bash
bazel test //etc/api:angular_devkit_core_api
```
You can also test all packages by running:
```bash
bazel test //etc/api ...
```
If you modified the public API, the test will fail. To update the golden files you need to run:
```bash
bazel run //etc/api:angular_devkit_core_api.accept
```
**Note**: In some cases we use aliased symbols to create namespaces.
Example:
```javascript
import * as foo from './foo';
export { foo };
```
There are currently not supported by the API guardian.
To overcome this limitiation we created `_golden-api.ts` in certain packages.
When adding a new API, it might be the case that you need to add it to `_golden-api.ts`.