馃摎 Docs or angular.io bug report
Description
When any contributor submits a PR to the project, they may see build failures like the following
CircleCI Test Failure
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;
Accept the new golden file:
bazel run //tools/public_api_guard:forms_api.accept
================================================================================
==================== 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;
Accept the new golden file:
bazel run //tools/public_api_guard:forms_api.accept
================================================================================
The important output here is the following
Accept the new golden file:
bazel run //tools/public_api_guard:forms_api.accept
Issues
- "Accept the new golden file"
- These words have little to no meaning to new contributors
- It is not clear that this is an instruction to the PR author
bazel run //tools/public_api_guard:forms_api.accept
- For contributors who have never used Bazel before
- It's not clear that this is a shell command
- It's also not clear that
public_api_guard:forms_api.accept is a script or a runnable target
- There is no explanation here (or link to) about what is wrong or why the PR author needs to take an action.
- There is no explanation here (or link to) on how to read the API diff and how to think about or make API changes.
Mitigation
CONTRIBUTING.md should mention and have some kind of link to the full description of this message, public_api_guard, and Golden files.DEVELOPER.md should mention and have some kind of link to the full description of this message, public_api_guard, and Golden files.COMMITTER.md or a new .md file may be the correct place to put the full description of this message, public_api_guard, and Golden files.
- Update the CircleCI output from
public_api_guard to link to the full description.
Expected vs Actual Behavior**
Expected to find some documentation describing this in one of these
but found nothing.
PUBLIC_API.md starts to touch on some of the relevant concepts, but it doesn't cover anything from the contributor or PR author's perspective.
馃實 Your Environment
Browser info
N/A
Anything else relevant?
Related issues
Full build job and failure that the above CircleCI output was sourced from: https://circleci.com/gh/angular/angular/457388
馃摎 Docs or angular.io bug report
Description
When any contributor submits a PR to the project, they may see build failures like the following
CircleCI Test Failure
The important output here is the following
Issues
bazel run //tools/public_api_guard:forms_api.acceptpublic_api_guard:forms_api.acceptis a script or a runnable targetMitigation
CONTRIBUTING.mdshould mention and have some kind of link to the full description of this message,public_api_guard, and Golden files.DEVELOPER.mdshould mention and have some kind of link to the full description of this message,public_api_guard, and Golden files.COMMITTER.mdor a new.mdfile may be the correct place to put the full description of this message,public_api_guard, and Golden files.public_api_guardto link to the full description.Expected vs Actual Behavior**
Expected to find some documentation describing this in one of these
but found nothing.
PUBLIC_API.md starts to touch on some of the relevant concepts, but it doesn't cover anything from the contributor or PR author's perspective.
馃實 Your Environment
Browser info
N/A
Anything else relevant?
Related issues
Full build job and failure that the above CircleCI output was sourced from: https://circleci.com/gh/angular/angular/457388