feat(component): add overlay metadata and 'component overlays' command#242
Open
liunan-ms wants to merge 1 commit into
Open
feat(component): add overlay metadata and 'component overlays' command#242liunan-ms wants to merge 1 commit into
liunan-ms wants to merge 1 commit into
Conversation
Add an optional [metadata] block on overlays (category, commits, PR, bug links, upstreamability) and a per-file .overlay.toml format loaded from a component's overlay-dir. Add the read-only 'azldev component overlays' command with --category, --only-annotated, and --upstreamability filters. Metadata and overlay-dir are excluded from fingerprints. Regenerate docs, JSON schema, and scenario snapshots.
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds structured overlay metadata and per-file overlay support, plus a new CLI/MCP command to list overlays across components.
Changes:
- Extend project config schema with
overlay-dirfor components andmetadatafor overlays. - Implement
.overlay.tomloverlay directory loading (file-level metadata stamped onto overlays) and validation. - Add
azldev component overlayscommand (and docs/snapshots) to inspect overlays and filter by metadata.
Reviewed changes
Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| schemas/azldev.schema.json | Adds overlay-dir and OverlayMetadata schema definitions. |
| scenario/snapshots/TestSnapshots_config_generate-schema_stdout_1.snap | Updates schema-generation snapshot to include new fields/defs. |
| scenario/snapshots/TestSnapshotsContainer_config_generate-schema_stdout_1.snap | Updates container schema-generation snapshot to include new fields/defs. |
| scenario/snapshots/TestMCPServerMode_1.snap.json | Adds new MCP tool entry for component-overlays. |
| internal/projectconfig/overlay_metadata.go | Introduces metadata types/enums and validation rules. |
| internal/projectconfig/overlay_metadata_test.go | Adds validation tests for overlay metadata and overlay validation integration. |
| internal/projectconfig/overlay_file.go | Implements overlay-dir scanning + .overlay.toml parsing/stamping behavior. |
| internal/projectconfig/overlay_file_test.go | Adds tests for overlay-dir load/stamping, ordering, path resolution, and errors. |
| internal/projectconfig/overlay.go | Adds optional Metadata to overlays and validates it when present. |
| internal/projectconfig/loader.go | Hooks overlay-dir resolution into config load pipeline (pre-validation). |
| internal/projectconfig/fingerprint_test.go | Marks ComponentOverlay.Metadata and ComponentConfig.OverlayDir as excluded from fingerprinting. |
| internal/projectconfig/component.go | Adds OverlayDir field and preserves verbatim value in WithAbsolutePaths. |
| internal/app/azldev/cmds/component/overlays.go | Adds azldev component overlays command + filtering/sorting logic. |
| internal/app/azldev/cmds/component/overlays_test.go | Adds tests for listing and filtering overlays by annotation/category/upstreamability. |
| internal/app/azldev/cmds/component/component.go | Registers the new overlays subcommand. |
| docs/user/reference/config/overlays.md | Documents overlay metadata and per-file .overlay.toml overlay-dir format. |
| docs/user/reference/cli/azldev_component_overlays.md | Adds auto-generated CLI reference for the new command. |
| docs/user/reference/cli/azldev_component.md | Adds the new subcommand to the CLI index. |
|
|
||
| // Upstreamability records whether this overlay's change can be upstreamed: 'yes', 'no', | ||
| // or 'unknown'. Omitting the field defaults to 'unknown' (not yet assessed). | ||
| Upstreamability OverlayUpstreamability `toml:"upstreamability,omitempty" json:"upstreamability,omitempty" jsonschema:"enum=yes,enum=no,enum=unknown,default=unknown,title=Upstreamability,description=Whether this overlay's change can be upstreamed: 'yes', 'no', or 'unknown' (the default)"` |
| return nil, fmt.Errorf("%w (overlay %d in %q)", ErrOverlayFilePerOverlayMetadata, idx+1, overlayPath) | ||
| } | ||
|
|
||
| overlay.Metadata = deep.MustCopy(&ofile.Metadata) |
|
|
||
| // Field-level constraints (for example 'pr' and 'bug' must be http(s) URLs) are | ||
| // expressed as 'validate' struct tags and enforced here. | ||
| if err := validator.New().Struct(m); err != nil { |
Comment on lines
+225
to
+231
| if options.Upstreamability != "" { | ||
| // The filter value is validated upfront in ListOverlays, so the error is unreachable here. | ||
| want, _ := normalizeUpstreamabilityFilter(options.Upstreamability) | ||
| if info.Upstreamability != want { | ||
| return false | ||
| } | ||
| } |
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
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.
Summary
Overlays currently carry no record of why they exist or when they can be removed, so reviewers can't tell a temporary Fedora backport from a permanent AZL branding change. This PR adds an optional
[metadata]block to overlays, a per-file.overlay.tomlformat for grouping related overlays, and a read-onlyazldev component overlayscommand for inspecting them.What's new
Overlays can now declare optional documentation metadata:
A component can set
overlay-dir = "overlays"to load*.overlay.tomlfiles, one per logical change. Each file has a single file-level[metadata]block (stamped onto every overlay in the file) plus an ordered list of[[overlays]]. Files load in filename order (0001-, 0002- convention), are appended after inline overlays, and resolve source paths relative to the overlay file. Per-overlay metadata inside these files is rejected.azldev component overlayscommandA read-only command listing overlays and their metadata across components, with
--category,--only-annotated, and--upstreamabilityfilters. Table (default) or JSON output. Available as an MCP tool. Does not parse spec files or fetch sources, so it's fast and works with missing/stale locks.Validated against real overlays (microsoft/azurelinux#17727)