chore(comps): annotate backport overlays with category metadata by liunan-ms · Pull Request #17727 · microsoft/azurelinux

liunan-ms · 2026-06-16T00:03:56Z

This PR annotates the overlays surfaced by the overlay classifier with structured [metadata] (a category plus, for genuine backports, the verified upstream commits), so future Fedora rebases can mechanically identify and retire overlays that have landed upstream. It also pins azldev to a version that understands these annotations and the per-file overlay-files layout, and regenerates the authoritative JSON schema to match.

Changes:

Project config

base/comps/components.toml gains a project-wide [default-component-config] with overlay-files = ["overlays/*.overlay.toml"], so every component discovers its own overlays/*.overlay.toml without redeclaring the glob.

Per-file overlay migration (24 components)

ant, apache-ivy, atlas, cloud-init, cpio, glade, gnulib, grub2, gt, intel-qpl, javapackages-tools, kdump-utils, maven, maven4, rust-podman-sequoia, sos, sssd, vamp-plugin-sdk, xbean, xclock, xmvn, xmvn5, xsimd, zbar — inline overlays were moved into per-logical-change overlays/*.overlay.toml files, each carrying one file-level [metadata] block. Multi-commit backports (e.g. javapackages-tools openjdk21 drop) consolidate related upstream commits into a single file via commits = [url1, url2, …]. Patch source paths are rewritten to ../<patch> to point back at the component root.

Category spread

Most overlays are upstream-backport (with verified upstream commits). A few non-backport overlays surfaced alongside them are labelled accordingly: azl-pruning (e.g. grub2 xen-module disable), azl-security-compliance (grub2 os-prober reverts — restoring upstream GRUB's secure default Fedora diverged from), azl-compatibility, azl-branding-policy, and azl-temp-workaround for the gnulib source-URL filter shim and the gt -std=gnu89 compiler workaround, which are alternative/transient fixes rather than backports of their referenced Fedora commits.

Validation

Pure annotation/restructuring: the rendered spec is byte-identical before and after (verified via before/after prepare-sources diffs for every migrated component).
azldev comp update reports no lock drift (metadata is excluded from fingerprints; the overlay-files restructuring keeps the same input set).
azldev comp render all passed in PR check.

dmcilvaney · 2026-06-16T19:59:38Z

-replacement = ""
+# Overlays live as one-logical-change-per-file under ./overlays/.
+# See https://github.com/microsoft/azure-linux-dev-tools/blob/main/docs/user/reference/config/overlays.md#per-file-overlay-format-overlaytoml
+overlay-dir = "overlays"


It would be great to update the AI instructions to explain when to use this pattern vs. not, and what sort of data to add to each overlay.

Yes, I'll add a SKILL.md and instruction in a separate PR for using this pattern and suggesting annotations for new overlays.

Copilot

Pull request overview

This PR annotates the Azure Linux overlays previously flagged by the overlay classifier with structured metadata (a category plus upstream commits/pr/bugs), so future Fedora rebases can mechanically identify and retire backported overlays once they land upstream. It also bumps the pinned azldev version to one that understands these annotations and a new per-file overlay layout.

Changes:

Inline annotations (17 components): add a [components.<name>.overlays.metadata] block to existing single-/few-overlay .comp.toml files. Note these attach per-overlay (to the immediately preceding overlay), which is used deliberately in some files (e.g. sos, sssd) but is inconsistent in xbean.
Per-file migration (7 components): cpio, gnulib, javapackages-tools, qemu, zbar, apache-ivy, cloud-init move inline overlays into overlays/*.overlay.toml files (top-level [metadata] + [[overlays]], with source paths rewritten to ../ to point back at the component root). qemu also consolidates per-section subpackage removals into spec-remove-subpackage (verified output-equivalent against the rendered spec).
.azldev-version bump to enable the new overlay-files/metadata features; the committed authoritative schema was not regenerated to match.

Reviewed changes

Copilot reviewed 39 out of 39 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`.azldev-version`	Bumps pinned azldev to a version supporting `overlay-files`/`metadata`; committed schema not regenerated (flagged).
`base/comps/{ant,atlas,glade,gt,intel-qpl,maven,maven4,xclock,xmvn,xmvn5}/*.comp.toml`	Single-overlay inline `metadata` annotations (correct attachment).
`base/comps/{sos,sssd,kdump-utils,rust-podman-sequoia,vamp-plugin-sdk}/*.comp.toml`	Multi-overlay inline `metadata` with distinct per-overlay commits (correct).
`base/comps/xbean/xbean.comp.toml`	Inline `metadata`; remove/add openjdk retarget pair annotated inconsistently (flagged).
`base/comps/cpio/*`	Migrated to per-file overlay; `rmt` BR drop annotated.
`base/comps/gnulib/*`	Migrated; temporary Source-URL backport annotated.
`base/comps/javapackages-tools/*`	Migrated; openjdk21-drop multi-commit backport consolidated.
`base/comps/qemu/*`	Migrated to 4 overlay files; subpackage removals consolidated to `spec-remove-subpackage` (output-equivalent).
`base/comps/zbar/*`	Migrated; GIR-drop (backport) and video-disable (pruning) split into two files.
`base/comps/apache-ivy/*`	Migrated; `0001` overlays lack required `description` fields (flagged nit).
`base/comps/cloud-init/*`	Migrated to 3 overlay files (cpe-fix, azl4 patch series, branding); `../` source paths point at component-root patches.

Copilot

Pull request overview

Copilot reviewed 34 out of 34 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 34 out of 34 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 60 out of 60 changed files in this pull request and generated 4 comments.

- apache-ivy: add per-overlay descriptions to the pack200 backport file (hygiene rule #1 — every overlay must explain why the change is needed). - gnulib: drop the redundant per-component overlay-files declaration; the project-wide [default-component-config] already discovers overlays/*.overlay.toml. - grub2: reconcile the os-prober revert overlays (0002 + 0003) to a single category. Re-disabling os-prober restores upstream GRUB's secure default that Fedora diverged from (it will not retire on a Fedora rebase), so both halves are azl-security-compliance and the misleading backport commits are dropped. - external/schemas/azldev.schema.json: regenerate against the pinned azldev (4b5f72c) so the authoritative schema knows the new metadata / overlay-files / BugRef fields used throughout this PR. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 60 out of 60 changed files in this pull request and generated no new comments.

Copilot

Pull request overview

Copilot reviewed 61 out of 61 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 60 out of 60 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

base/comps/components.toml:11

The project schema is still stale: external/schemas/azldev.schema.json defines ComponentConfig with additionalProperties: false but has no overlay-files property (lines 102-155), and it also lacks the new overlay metadata definitions. Consequently this newly added setting is rejected by the repository's authoritative schema even though the pinned CLI accepts it. Regenerate and commit the schema using the final .azldev-version pin.

overlay-files = ["overlays/*.overlay.toml"]

base/comps/gnulib/overlays/0001-fix-source-url-filter.overlay.toml:9

This is not a backport of 41cae067: that Fedora commit replaces the erislabs URLs with salsa.debian.org, whereas these overlays deliberately retain the old URLs and add fragment hints as a temporary filter workaround. The pinned azldev definition reserves azl-temp-workaround for transient workarounds waiting on an external fix, so labeling this upstream-backport records inaccurate provenance for the retirement tooling.

category = "upstream-backport"

base/comps/gt/overlays/0001-add-std-gnu89-cflags.overlay.toml:10

The referenced Fedora commit does not backport this -std=gnu89 change; it adds and applies the source-level gt-0.4-std23.patch. This overlay is an alternative compiler-mode workaround that can be removed once that Fedora fix is imported, which matches azl-temp-workaround, not upstream-backport. Keeping the current category makes the structured provenance claim that the Fedora change itself was backported.

category = "upstream-backport"

Copilot

Pull request overview

Copilot reviewed 61 out of 61 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

base/comps/vamp-plugin-sdk/overlays/0001-re-number-existing-patch.overlay.toml:14

This metadata says the fix is only upstreamable, but the immediately preceding comment identifies it as already shipped in Fedora Rawhide 2.10-4. Under the status convention used here, that makes it upstreamed; keeping the current value prevents the rebase-retirement tooling from recognizing the Fedora landing. Record the Fedora dist-git commit as well so the retirement provenance is machine-readable.

Copilot

Pull request overview

Copilot reviewed 61 out of 61 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

base/comps/gnulib/overlays/0001-fix-source-url-filter.overlay.toml:2

This shim does not backport 41cae067: it keeps the old URLs and adds filename fragments while waiting for that Fedora change. Calling it a backport conflicts with the azl-temp-workaround classification and may mislead future retirement work; describe it as a workaround pending that commit instead.

# Temporary backport of upstream Fedora commit 41cae067 ("Update to git4a3650d
# branch stable-202601") which updated the Source URLs from erislabs.net to

Copilot

Pull request overview

Copilot reviewed 61 out of 61 changed files in this pull request and generated no new comments.

tobiasb-ms · 2026-07-29T14:49:16Z

/azp run

azure-pipelines · 2026-07-29T14:49:23Z

Azure Pipelines will not run the associated pipelines, because the pull request was updated after the run command was issued. Review the pull request again and issue a new run command.

tobiasb-ms

I confirmed via before/after runs of azldev component list --all-components that the only changes are the addition of metadata and a few new description fields.

Seems good.

Annotate every overlay surfaced by the overlay classifier with structured [metadata] so future Fedora rebases can mechanically identify and retire overlays that have landed upstream. - Add a project-wide [default-component-config] in base/comps/components.toml with overlay-files = ["overlays/*.overlay.toml"], so each component discovers its own per-file overlays without redeclaring the glob. - Migrate all 24 annotated components to the per-file overlay-files layout: inline overlays move into per-logical-change overlays/*.overlay.toml files, each carrying one file-level [metadata] block. Patch source paths are rewritten to ../<patch> to point back at the component root. - Categories: most overlays are upstream-backport (with verified commits); the rest are labelled by intent (azl-pruning, azl-security-compliance, azl-compatibility, azl-branding-policy, and azl-temp-workaround for the gnulib source-URL filter shim and the gt -std=gnu89 compiler workaround, which are alternative/transient fixes rather than backports of their referenced Fedora commits). Pure annotation/restructuring: the rendered spec is byte-identical before and after (verified via prepare-sources), and azldev comp update reports no lock drift (metadata is excluded from fingerprints).

Regenerate external/schemas/azldev.schema.json against the pinned .azldev-version (661c69b6) so the authoritative schema matches the CLI. Adds the overlay-files property to ComponentConfig and the OverlayMetadata definitions (category, upstream-status, commits) required by the per-file overlay layout.

Copilot

Pull request overview

Copilot reviewed 62 out of 62 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

base/comps/apache-ivy/overlays/0001-pack200-commons-compress.overlay.toml:7

This file-level metadata is stamped onto all six overlays, but Source5 is not part of the referenced backport: d772841 adds/renames plugins/pack/Pack200Packing.java, while remove-Pack200Packing-java.patch deletes that file again. Classifying the whole document as upstream-backport therefore gives the downstream deletion false provenance and could make retirement tooling drop it when Fedora imports d772841. Split the Source5 removal into a separately classified AZL overlay document (and keep only the exact backport under this metadata), or classify the combined change as a non-backport.

category = "upstream-backport"
upstream-status = "upstreamable"
commits = [{ url = "https://github.com/apache/ant-ivy/commit/d77284167b6695903b80c72afed57469ffab5cc3" }]

tobiasb-ms · 2026-07-29T18:00:50Z

/azp run

azure-pipelines · 2026-07-29T18:00:58Z

Azure Pipelines: 3 pipeline(s) were filtered out due to trigger conditions.

Discussed offline; changes look good now.

liunan-ms mentioned this pull request Jun 16, 2026

feat(component): add overlay metadata and 'component metadata' command microsoft/azure-linux-dev-tools#242

Closed

dmcilvaney reviewed Jun 16, 2026

View reviewed changes

liunan-ms changed the title ~~chore(comps): annotate backport-fedora overlays with category metadata~~ chore(comps): annotate backport overlays with category metadata Jun 18, 2026

liunan-ms force-pushed the liunan/overlay_metadata branch from 93c3e9b to e29cdb5 Compare June 18, 2026 19:11

Copilot AI review requested due to automatic review settings June 25, 2026 20:37

Copilot started reviewing on behalf of liunan-ms June 25, 2026 20:38 View session

liunan-ms force-pushed the liunan/overlay_metadata branch from 23ed86c to 4107a39 Compare June 25, 2026 20:44

Copilot AI reviewed Jun 25, 2026

View reviewed changes

Comment thread .azldev-version Outdated

Comment thread base/comps/xbean/xbean.comp.toml Outdated

Comment thread base/comps/apache-ivy/overlays/0001-pack200-commons-compress.overlay.toml

Copilot AI review requested due to automatic review settings June 25, 2026 20:49

Copilot started reviewing on behalf of liunan-ms June 25, 2026 20:50 View session

liunan-ms force-pushed the liunan/overlay_metadata branch from 4107a39 to 13381f7 Compare June 25, 2026 20:58

Copilot AI reviewed Jun 25, 2026

View reviewed changes

Comment thread base/comps/xbean/xbean.comp.toml Outdated

Comment thread .azldev-version Outdated

Copilot AI review requested due to automatic review settings June 25, 2026 21:05

Copilot started reviewing on behalf of liunan-ms June 25, 2026 21:05 View session

Copilot AI reviewed Jun 25, 2026

View reviewed changes

Comment thread base/comps/xbean/xbean.comp.toml Outdated

Comment thread base/comps/apache-ivy/overlays/0001-pack200-commons-compress.overlay.toml

Copilot AI review requested due to automatic review settings June 29, 2026 21:44

Copilot started reviewing on behalf of liunan-ms June 29, 2026 21:44 View session

Copilot AI reviewed Jun 29, 2026

View reviewed changes

Comment thread base/comps/gnulib/gnulib.comp.toml Outdated

Comment thread base/comps/apache-ivy/overlays/0001-pack200-commons-compress.overlay.toml

Comment thread base/comps/grub2/overlays/0003-append-patch0383-patch0384-patch0385.overlay.toml Outdated

Comment thread base/comps/components.toml

Copilot AI review requested due to automatic review settings June 30, 2026 17:05

Copilot started reviewing on behalf of liunan-ms June 30, 2026 17:05 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings June 30, 2026 20:50

Copilot started reviewing on behalf of liunan-ms June 30, 2026 20:51 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

Comment thread base/comps/gt/overlays/0001-add-std-gnu89-cflags.overlay.toml Outdated

liunan-ms force-pushed the liunan/overlay_metadata branch from f55c1ce to 7db736c Compare June 30, 2026 21:04

microsoft deleted a comment from github-actions Bot Jun 30, 2026

liunan-ms marked this pull request as ready for review June 30, 2026 21:27

liunan-ms requested a review from a team as a code owner June 30, 2026 21:27

Copilot AI review requested due to automatic review settings June 30, 2026 21:27

Copilot started reviewing on behalf of liunan-ms July 27, 2026 22:45 View session

Copilot AI reviewed Jul 27, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 28, 2026 23:25

liunan-ms force-pushed the liunan/overlay_metadata branch from 67be8e2 to 6f1f478 Compare July 28, 2026 23:25

Copilot started reviewing on behalf of liunan-ms July 28, 2026 23:26 View session

Copilot AI reviewed Jul 28, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 28, 2026 23:42

liunan-ms force-pushed the liunan/overlay_metadata branch from 6f1f478 to 6dbe7ee Compare July 28, 2026 23:42

Copilot started reviewing on behalf of liunan-ms July 28, 2026 23:43 View session

Copilot AI reviewed Jul 28, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 29, 2026 00:00

liunan-ms force-pushed the liunan/overlay_metadata branch from 6dbe7ee to e3b0ed9 Compare July 29, 2026 00:00

Copilot started reviewing on behalf of liunan-ms July 29, 2026 00:01 View session

Copilot AI reviewed Jul 29, 2026

View reviewed changes

tobiasb-ms approved these changes Jul 29, 2026

View reviewed changes

liunan-ms added 2 commits July 29, 2026 17:04

Copilot AI review requested due to automatic review settings July 29, 2026 17:09

liunan-ms force-pushed the liunan/overlay_metadata branch from e3b0ed9 to 7aee486 Compare July 29, 2026 17:09

Copilot started reviewing on behalf of liunan-ms July 29, 2026 17:09 View session

Copilot AI reviewed Jul 29, 2026

View reviewed changes

tobiasb-ms requested a review from reubeno July 29, 2026 18:00

tobiasb-ms approved these changes Jul 29, 2026

View reviewed changes

tobiasb-ms merged commit 5b489b8 into 4.0 Jul 29, 2026
12 checks passed

tobiasb-ms deleted the liunan/overlay_metadata branch July 29, 2026 18:27

Uh oh!

Conversation

liunan-ms commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes:

Project config

Per-file overlay migration (24 components)

Category spread

Validation

Uh oh!

dmcilvaney Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

liunan-ms Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

tobiasb-ms commented Jul 29, 2026

Uh oh!

azure-pipelines Bot commented Jul 29, 2026

Uh oh!

tobiasb-ms left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

liunan-ms commented Jun 16, 2026 •

edited

Loading

liunan-ms Jun 16, 2026 •

edited

Loading