@@ -92,6 +92,26 @@ behavior is a bug fix, not an enhancement — diffs that remove an
9292over-restrictive condition, add a fallback branch, or invert an ` && `
9393usually belong here. Describe the user-visible symptom.
9494
95+ ## metadata.yaml is documentation, not evidence
96+
97+ Files named ` metadata.yaml ` (typically under
98+ ` instrumentation/<name>/metadata.yaml ` ) are static documentation
99+ describing each module's configs, libraries, and semconv surfaces.
100+ They are read by tooling (instrumentation-list generation, declarative-
101+ config bridge) but not by runtime instrumentation.
102+
103+ Adding, renaming, or filling in entries in ` metadata.yaml ` does NOT
104+ introduce, rename, or change any user-facing config. The corresponding
105+ config property already exists in ` src/main ` Java code, and its name is
106+ unaffected by the YAML diff. A ` declarative_name: ` value added to a
107+ ` metadata.yaml ` entry is the declarative-config alias for an existing
108+ flat property; it is not a new mapping or a runtime change.
109+
110+ When the only ` src/main ` evidence is a metadata.yaml entry — even one
111+ that names a real-looking config property — set ` decision: "omit" ` with
112+ a surface like "metadata.yaml documentation only". Do not emit an
113+ Enhancements bullet that introduces a config the diff merely documents.
114+
95115## When to omit
96116
97117Omit only when the PR's ` src/main ` runtime changes are entirely limited
@@ -101,7 +121,8 @@ to one or more of:
101121- test-only changes, cross-testing, moving tests out of default packages,
102122- CI/build-tooling with no runtime effect,
103123- renames of internal (not extension-API) fields, packages, or helpers,
104- - new package-private, ` internal ` -package, or test-only methods.
124+ - new package-private, ` internal ` -package, or test-only methods,
125+ - ` metadata.yaml ` documentation (see section above).
105126
106127Trivial omits (renovate bumps, all-test/docs/build paths, post-release
107128version bumps) are handled by ` classify.py --preclassify-only ` .
0 commit comments