docs: document golden file requirement (#33900)

PR Close #33900

CONTRIBUTING.md

@@ -279,7 +279,6 @@ changes to be accepted, the CLA must be signed. It's a quick process, we promise
 
 <hr>
 
-
 [angular-group]: https://groups.google.com/forum/#!forum/angular
 [coc]: https://github.com/angular/code-of-conduct/blob/master/CODE_OF_CONDUCT.md
 [commit-message-format]: https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#

docs/PR_REVIEW.md

@@ -152,4 +152,3 @@ NOTE: Notice that we did not have to specify the PR number since the script can
 
 If you visit https://github.com/angular/angular/pull/24623/commits you will see that your `fixup!` commit has been added to the PR.
 This greatly simplifies the work for many minor changes to the PR.
-

docs/PUBLIC_API.md

@@ -42,4 +42,51 @@ We explicitly don't consider the following to be our public API surface:
 - the contents and API surface of the code generated by Angular's compiler (with one notable exception: the existence and name of `NgModuleFactory` instances exported from generated code is guaranteed)
 
 
-Our peer dependencies (e.g. 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 any 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.
+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 any 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="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 can fail a Circle CI test with failures in `testlogs/tools/public_api_guard`, and 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](https://yarnpkg.com/) to execute the Bazel target in your terminal shell of choice (a recent version of `bash` is recommended).
+
+```shell
+yarn bazel run //tools/public_api_guard:<modified_package>_api.accept
+```
+
+Using yarn ensures that you are running the correct version of Bazel.
+(Read more about building Angular with Bazel [here](./BAZEL.md).)
+
+Here is an example of a Circle CI test failure that resulted from adding a new allowed type to a public property in `forms.d.ts`. Error messages from the API guard use [`git-diff` formatting](https://git-scm.com/docs/git-diff#_combined_diff_format).
+
+```
+FAIL: //tools/public_api_guard:forms_api (see /home/circleci/.cache/bazel/_bazel_circleci/9ce5c2144ecf75d11717c0aa41e45a8d/execroot/angular/bazel-out/k8-fastbuild/testlogs/tools/public_api_guard/forms_api/test_attempts/attempt_1.log)
+FAIL: //tools/public_api_guard:forms_api (see /home/circleci/.cache/bazel/_bazel_circleci/9ce5c2144ecf75d11717c0aa41e45a8d/execroot/angular/bazel-out/k8-fastbuild/testlogs/tools/public_api_guard/forms_api/test.log)
+
+FAILED: //tools/public_api_guard:forms_api (Summary)
+      /home/circleci/.cache/bazel/_bazel_circleci/9ce5c2144ecf75d11717c0aa41e45a8d/execroot/angular/bazel-out/k8-fastbuild/testlogs/tools/public_api_guard/forms_api/test.log
+      /home/circleci/.cache/bazel/_bazel_circleci/9ce5c2144ecf75d11717c0aa41e45a8d/execroot/angular/bazel-out/k8-fastbuild/testlogs/tools/public_api_guard/forms_api/test_attempts/attempt_1.log
+INFO: From Testing //tools/public_api_guard:forms_api:
+==================== Test output for //tools/public_api_guard:forms_api:
+--- tools/public_api_guard/forms/forms.d.ts	Golden file
++++ tools/public_api_guard/forms/forms.d.ts	Generated API
+@@ -4,9 +4,9 @@
+     readonly disabled: boolean;
+     readonly enabled: boolean;
+     readonly errors: ValidationErrors | null;
+     readonly invalid: boolean;
+-    readonly parent: FormGroup | FormArray;
++    readonly parent: FormGroup | FormArray | undefined;
+     readonly pending: boolean;
+     readonly pristine: boolean;
+     readonly root: AbstractControl;
+     readonly status: string;
+
+If you modify a public API, you must accept the new golden file.
+
+
+To do so, execute the following Bazel target:
+  yarn bazel run //tools/public_api_guard:forms_api.accept
+```

tools/ts-api-guardian/lib/cli.ts

@@ -82,8 +82,13 @@ export function startCli() {
       if (hasDiff) {
         // Under bazel, give instructions how to use bazel run to accept the golden file.
         if (!!process.env['BAZEL_TARGET']) {
-          console.error('\n\nAccept the new golden file:');
-          console.error(`  bazel run ${process.env['BAZEL_TARGET'].replace(/_bin$/, "")}.accept`);
+          console.error('\n\nIf you modify a public API, you must accept the new golden file.');
+          console.error('\n\nTo do so, execute the following Bazel target:');
+          console.error(
+              `  yarn bazel run ${process.env['BAZEL_TARGET'].replace(/_bin$/, "")}.accept`);
+          console.error('\n\nFor more information, see');
+          console.error(
+              '\n  https://github.com/angular/angular/blob/master/docs/PUBLIC_API.md#golden-files');
         }
         process.exit(1);
       }