feat(config): hint when a config key requires a newer schema version#3550
Merged
Conversation
docker-agent
reviewed
Jul 9, 2026
docker-agent
left a comment
docker-agent
left a comment
Contributor
There was a problem hiding this comment.
Assessment: 🟢 APPROVE
The newerVersionHint implementation is clean and correct. The logic correctly:
- Gates on
*yaml.UnknownFieldError(so type mismatches and genuine typos stay silent) - Compares version numbers numerically (not lexicographically), preventing
"9" > "10"-style ordering bugs - Picks the smallest accepting version, giving users the most precise upgrade target
- Only runs on the already-failed error path — no performance impact on the happy path
The doc comment honestly acknowledges the best-effort nature of the hint (a newer parser accepting the doc for unrelated reasons). Test coverage via TestLoadUnknownKeyFromNewerVersionHint, TestLoadUnknownKeyNoNewerVersionNoHint, and TestLoadNewerVersionHintNumericOrdering is solid for the key scenarios.
No bugs or significant concerns found in the changed code.
aheritier
added
area/config
Sayt-0
approved these changes
Jul 9, 2026
dgageot
force-pushed
the
feat/config-version-hint
branch
from
July 9, 2026 11:39
24415b6 to
1c77982
Compare
Piyush0049
pushed a commit
to Piyush0049/docker-agent
that referenced
this pull request
Jul 10, 2026
Piyush0049
pushed a commit
to Piyush0049/docker-agent
that referenced
this pull request
Jul 15, 2026
feat(config): hint when a config key requires a newer schema version
Piyush0049
pushed a commit
to Piyush0049/docker-agent
that referenced
this pull request
Jul 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
When a config file fails strict YAML parsing, the error message today gives no guidance on why — it just says the key is unknown. This is particularly confusing when someone copies a snippet from the docs that uses a feature introduced in a newer schema version, because the fix is simple (bump the top-level
versionfield) but invisible from the error alone.This change adds a hint in that failure path. After a strict parse fails, the code probes each parser for schema versions above the one declared in the file, finds the smallest version that successfully parses the document, and appends a message like:
The probing is cheap — it only runs when strict parsing has already failed — and is gated on finding a strictly higher version that actually accepts the input, so it stays silent when the error is a genuine typo or unsupported key. A follow-up commit adds a numeric version ordering test and expands the
newerVersionHintdoc comment.