docs: add documentation for API guardian (#13065)

alan-agius4 · vikerman · commit f392f18e428f · 2018-11-30T14:07:36.000-08:00
diff --git a/CONTRIBUTING.md b/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`.
diff --git a/scripts/templates/contributing.ejs b/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`.
