chore: document why compile-check skips dependents that use none of the changed names
Merged
HA
3d ago+88+88+01234567890123456789-1-1-0123456789
Summary
- Records, as ADR 0017, why compile-check leaves out a dependent that writes none of the names a reference's public API change touches.
- The compile-check skill now says
SkippedAssembliesalso counts assemblies whose references changed only names they never write. - Builds on #3348.
User Impact
Agents reading the compile-check skill learn that a skipped assembly may be one whose reference changed, but only in names it never uses. Maintainers get the decision, the measurements behind it, the accepted gaps, and when to revisit it.
Changes
docs/adr/0017-compile-check-skips-dependents-that-name-nothing-a-reference-changed.md:- Decision: which changes are named and which are unnamed (assembly-level rows, type shape, abstract members added, operators, pattern-bound members, handler and builder types, well-known
System/Microsoft.CodeAnalysistypes, moved rows, more than 2000 names), and that anything the check cannot read compiles. - Context: measurements on a project with 561 assemblies. A specific name is written by 0 to 2 of the 67 dependents of an assembly; a short common name by 48 to 52; a target-typed
new(by 59. Saved generator output existed for only 4 dependents, and none of it used a name of the edited assembly. - Consequences: the expected time for such an edit, and the known gaps:
- generator-only names, made the common case because a left-out dependent loses its saved generator output;
- async method builder types;
\uescapes;- extension classes in
System.*; - common pattern-bound method names.
- Revisit when: a dependent compiled by Unity fails on a change this check left it out of, or reading the names takes more than a tenth of a run.
- Decision: which changes are named and which are unnamed (assembly-level rows, type shape, abstract members added, operators, pattern-bound members, handler and builder types, well-known
Packages/src/Editor/CliOnlyTools~/CompileCheck/Skill/SKILL.md: one line onSkippedAssemblies.
Verification
go run ./cmd/check-skill-size --root <repository root>(incli/release-automation): no SKILL.md exceeds the limit.scripts/sync-tool-docs.sh --check: the tool catalog matches the skill tables.- Documentation only; no code changes.