[Feature Request]: Automate / validate changelog area mappings

[lcawl]

Prerequisites

• I have searched existing issues to ensure this feature hasn't already been requested
• I have tested using the latest version of docs-builder

What problem are you trying to solve?

Per https://github.com/elastic/elasticsearch/pull/140141/changes#r3221759284, for teams that have PR/issue labels that change fairly frequently there's a manual step required to ensure the changelog configuration file's pivot settings are up-to-date. Otherwise, the changelog fields can't be derived and must be added by contributors manually.

Proposed Solution

Per https://github.com/elastic/elasticsearch/pull/140141/changes#r3221759284, do teams need some kind of process that will automatically update the changelog configuration file's pivot.areas? Sounds like Elasticsearch might already have something like this in their old changelog system.

Alternatively, if a team decides that lack of an area label is a failure, making this a configurable validation check in the changelog action and/or evaluate-pr command might suffice.

Examples and Research

No response

Alternative Solutions

No response

Additional Context

No response

How important is this feature to you?

Nice to have

[cotti]

AI triage

Automated investigation against the current codebase. A human still needs to confirm before any code change.

Original concern

When a team's GitHub labels change, the changelog pivot.areas mapping in changelog.yml goes stale and there's no automation to refresh it nor a validation check to flag PRs missing an area label — so area fields silently fail to derive and contributors have to add them by hand.

Findings

• src/Elastic.Documentation.Configuration/Changelog/PivotConfiguration.cs:L27-L32 — pivot.areas is a hand-maintained dictionary (area display name → label string(s)). Nothing reads the repo's live GitHub labels; the mapping is fully manual.
• src/Elastic.Documentation.Configuration/Changelog/ChangelogConfigurationLoader.cs:L191-L194 — area keys are taken verbatim (Pivot.Areas.Keys.ToList()) with no validation. Contrast pivot.types (validated against the type enum, L127-L170) and pivot.products (validated against config/products.yml, L203-L217). There is no equivalent check that an area's configured label actually exists, so a renamed/deleted label produces no error.
• src/Elastic.Documentation.Configuration/Changelog/ChangelogConfigurationLoader.cs:L1166-L1192 — BuildLabelToAreasMapping just inverts whatever is in the config; it never reconciles against the repo's real label set.
• src/services/Elastic.Changelog/Evaluation/ChangelogPrEvaluationService.cs:L108-L153 — evaluate-pr resolves type and products from labels and fails with NoLabel only when a type label is missing. Areas are never resolved or evaluated here, so "missing area label" is not a check the action can fail on today.
• src/services/Elastic.Changelog/Creation/PrInfoProcessor.cs:L157-L166 — at changelog add time, areas are derived best-effort: if no label matches the mapping, Areas is simply left empty with no warning or error (compare type derivation at L136-L150, which hard-errors on no match). This is the "silently can't be derived" symptom the issue describes.

Verdict

Needs stakeholder input

The mapping plumbing exists and works, but both requested capabilities are absent: (a) there is no automation that updates pivot.areas from the repo's GitHub labels, and (b) there is no configurable validation — neither at config-load nor in evaluate-pr — that treats a missing/stale area label as a failure. Neither is a mechanical add: each needs design decisions (how/when to fetch GitHub labels, where the sync runs, what "missing area" should mean, and the docs-builder ↔ docs-actions boundary). The cross-repo validate/submit actions just wrap docs-builder changelog evaluate-pr, so the validation half would land primarily in this repo.

Proposal

Open questions, grouped by audience:

Engineering (ai:eng-question)

• Automation home: should a docs-builder changelog subcommand fetch repo labels (via the GitHub API) and emit/patch pivot.areas, or should this be a scheduled job in docs-actions? AOT + token-scope implications either way.
• For validation in evaluate-pr: add area resolution alongside type/products and a config flag (e.g. rules.create.require_area or similar) to fail when no area label matches. Touch points: ChangelogPrEvaluationService.EvaluatePr (:L108-L153) and a new MapLabelsToAreas call mirroring the existing type/product handling.
• Config-load validation: should the loader warn when a configured area label is unknown? That requires a source of truth for "valid labels" (a label list, or a live API call) — decide which.

Writer / contributor workflow (ai:writer-question)

• Who owns the pivot.areas mapping per repo, and is a CI failure on a missing area label acceptable, or should it stay a soft warning? This changes the contributor experience on every PR.
• If auto-sync rewrites changelog.yml, is an automated PR/commit acceptable, and who reviews it?

Related issues

• [Feature Request]: Improve handling of optional version in profile-based changelog bundles #2973 (open) — Improve handling of optional version in profile-based changelog bundles. Not a duplicate; it's a sibling in the broader changelog-configuration enhancement cluster (it concerns bundle versioning, not area mappings). Worth tracking together if maintainers plan a coherent pass over changelog config, but scope is distinct.

Notes

• The issue references the changelog action and evaluate-pr command as possible homes for the validation; confirmed in elastic/docs-actions the changelog/validate and changelog/submit/evaluate actions both shell out to docs-builder changelog evaluate-pr, so a docs-builder-side flag is the natural lever.
• Label suggestion applied: ai:eng-question (automation/build mechanics, cross-repo) + ai:writer-question (mapping ownership + contributor-facing failure mode).