-
Notifications
You must be signed in to change notification settings - Fork 698
chore(azldev): bump azldev to faaa0f4 #18689
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
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
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
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
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,178 @@ | ||
| --- | ||
| name: azldev-overlay-metadata | ||
| description: "Read this before adding or reviewing an overlay `metadata` table; do not guess the category or upstream status from memory. Explains the overlay metadata schema that documents why an overlay exists and when it can be dropped, covering the required category and upstream-status values, commit/bug URL references, and the per-file overlay metadata block. Triggers include overlay metadata, category, upstream-status, upstream-backport, azl-pruning, azl-branding-policy, needs-upstream-hook, why overlay." | ||
| --- | ||
|
|
||
| # Overlay metadata — pick a category and annotate | ||
|
|
||
| Every overlay documents *why* it exists (`description`, **required**) and *what class | ||
| of change* it is (`metadata`). When a `[metadata]` block is present it **requires** both | ||
| a `category` and an `upstream-status`. This skill covers how to pick the right values, | ||
| attach provenance, and write the TOML at the moment you author or review an overlay. | ||
|
|
||
| Metadata is **pure documentation** — it never changes the rendered spec and is excluded | ||
| from component fingerprints, so adding or editing it never invalidates build caches or | ||
| locks. For overlay *types* and the render-and-inspect loop, read the `azldev-overlays` | ||
| skill; this skill is only about the `metadata` table. | ||
|
|
||
| ## One `[metadata]` block = one logical change | ||
|
|
||
| A single logical change (a CVE backport, a feature disablement, a Fedora cherry-pick) | ||
| may need **several overlays** — e.g. remove a sub-package *and* drop the configure flags | ||
| that went with it. The per-file overlay format (`overlay-files`) captures exactly this: | ||
| one top-level `[metadata]` table and one or more `[[overlays]]` entries it applies to. | ||
| Per-overlay `metadata` inside an overlay file is **rejected** — the file-level block is | ||
| the single source of truth. | ||
|
|
||
| So: if you find yourself stamping the *same* metadata on several inline overlays, that is | ||
| a signal they are one logical change — move them into a single overlay file with one | ||
| `[metadata]` block. | ||
|
|
||
| ## When to add metadata | ||
|
|
||
| - **New overlay** (any inline `[[components.<name>.overlays]]` block or `[[overlays]]` | ||
| entry in an overlay file): add `metadata` with both a `category` and an `upstream-status`. | ||
| - **An overlay's intent changed** (e.g. a prune becomes a backport): update the `category` | ||
| and `upstream-status` to match the new intent. | ||
|
|
||
| ## Step 1 — Pick the category | ||
|
|
||
| Choose exactly one `category` from this closed set (authoritative — matches | ||
| `metadata.category` in the schema): | ||
|
|
||
| | `category` | Use when the overlay… | Extra required/expected fields | | ||
| |------------|-----------------------|--------------------------------| | ||
| | `upstream-backport` | Backports a fix from an upstream source (Fedora dist-git or the component's OSS project) that AZL will inherit once it bumps past the fix. Self-resolves on version bump. | `commits` (≥1 upstream commit URL) — **required**. `upstream-status` must be `upstreamed` or `upstreamable`. | | ||
| | `azl-pruning` | Removes content for AZL: unshipped deps, unneeded features, sub-packages, or files. | — | | ||
| | `azl-compatibility` | Adapts a component to *how Azure Linux is built and shipped* — build tooling, buildroot, infrastructure, runtime ecosystem — when upstream builds/behaves incorrectly for AZL-specific reasons that are **not** branding, a missing dependency, architecture, or tests (e.g. `azldev` downloader quirks, `rpmdiff` reproducibility, buildroot gaps, Fedora version-skew). | — | | ||
| | `azl-temp-workaround` | Temporary workaround explicitly intended to be dropped once an upstream or environmental fix lands. Covers a dependency not yet imported into AZL (or unavailable on a target) **and** any other transient workaround waiting on an external change. | — | | ||
| | `azl-branding-policy` | Fedora→Azure Linux identity differences: intentional name/path/vendor conventions **and** spec fixes for upstream code that hard-codes Fedora identity strings (e.g. `_vendor=redhat`, `<cpu>-redhat-linux[-gnu]` triples, `redhat-linux-build` dirs). Also covers repointing a `Source`/`URL` tag from a Fedora mirror to an Azure Linux one (e.g. `azurelinux-rpm-config`, `golang`). | — | | ||
| | `azl-disable-flaky-tests` | Skips tests that fail intermittently / due to environmental flakiness, not a real component bug. | — | | ||
| | `azl-disable-unsupported-tests` | Skips tests that cannot meaningfully run in AZL's build/runtime env (need network, root, or unavailable hardware in mock). | — | | ||
| | `azl-security-compliance` | Makes FIPS or crypto-policy changes. | — | | ||
| | `azl-release-management` | Adjusts release-tag / changelog mechanics. | — | | ||
| | `azl-platform-adaptation` | Makes architecture-specific adjustments. | — | | ||
|
|
||
| ### Disambiguation tips | ||
|
|
||
| - **Backport vs. compatibility/pruning:** if the exact change exists as a commit in Fedora | ||
| dist-git or the upstream project, it is `upstream-backport` (supply `commits`, with | ||
| `upstream-status` of `upstreamed` or `upstreamable`). Use an `azl-*` category only when | ||
| the change is AZL-specific with no upstream equivalent. | ||
| - **Pruning vs. temp-workaround:** removing a dependency we deliberately don't ship is | ||
| `azl-pruning`; temporarily working around a dep that *should* exist but hasn't been | ||
| imported yet (or any transient workaround waiting on an external fix) is | ||
| `azl-temp-workaround`. | ||
| - **Flaky vs. unsupported tests:** flaky = the test *could* pass but is intermittent; | ||
| unsupported = the test *cannot* run in mock (network/root/hardware). Require evidence of | ||
| the limitation before choosing `azl-disable-unsupported-tests`; investigate or ask when | ||
| the failure mode is unclear. | ||
| - **Compatibility vs. platform-adaptation:** reserve `azl-platform-adaptation` for | ||
| architecture-specific (`%ifarch`-style) changes; general toolchain/mock/build-env fixes | ||
| are `azl-compatibility`. | ||
|
|
||
| ## Step 2 — Set `upstream-status` | ||
|
|
||
| Required whenever `[metadata]` is present. It classifies the overlay's relationship to | ||
| upstream — "why are we carrying this?" and "what would it take to drop it?" Pick exactly one: | ||
|
|
||
| | Value | Meaning | | ||
| |-------|---------| | ||
| | `upstreamed` | Already in Fedora; carried only until AZL bumps past it. | | ||
| | `upstreamable` | The patch we carry is itself upstream-shaped (or already in the OSS project but not in Fedora yet); the same diff could be sent upstream and plausibly accepted. Link the upstream PR when you can. | | ||
| | `needs-upstream-hook` | AZL-specific change that upstream wouldn't take as-is, but upstream could add a `bcond`/`%if`/config knob so we could drop the overlay. | | ||
| | `inapplicable` | Permanent AZL-only deviation with no upstream story (branding, deliberate pruning, enterprise policy). | | ||
| | `unknown` | Not yet assessed. Prefer a definite value; reviewers should push back on `unknown` before approving. | | ||
|
|
||
| On an `upstream-backport` overlay only `upstreamed` and `upstreamable` are allowed — any | ||
| other value is a validation error. | ||
|
|
||
| **`upstreamable` vs. `needs-upstream-hook`:** `upstreamable` means the patch we carry is | ||
| itself upstream-shaped (send the same diff upstream); `needs-upstream-hook` means the | ||
| change is AZL-specific and would *not* be accepted as-is, but upstream could add a hook | ||
| that makes patching unnecessary. | ||
|
|
||
| ## Step 3 — Add provenance (`commits`, `bugs`) | ||
|
|
||
| - `commits` — list of `{ url = "..." }` tables pointing at upstream commits (absolute | ||
| http(s) URLs). **Required for `upstream-backport`**; optional elsewhere but valuable | ||
| whenever a change traces to a specific commit. For one logical change spanning several | ||
| commits, list them all. Verify each SHA actually exists upstream before recording it — a | ||
| discovered-and-verified URL is not "inventing" metadata; an unverified guess is. | ||
| - `bugs` — list of `{ url = "..." }` tables referencing tracker entries. Never fabricate one. | ||
|
|
||
| ## Step 4 — Write the metadata (TOML forms) | ||
|
|
||
| **Prefer the per-file layout (an overlay file loaded via `overlay-files`) for all new | ||
| work — even a component with a single overlay.** It keeps `category`/`commits`/`bugs` on | ||
| their own lines (no inline-table one-line limit) and means a change never has to be | ||
| reshuffled when it grows a second overlay. One top-level `[metadata]` table applies to | ||
| every `[[overlays]]` entry in the file. | ||
|
|
||
| Multi-overlay change (one logical change, several overlays): | ||
|
|
||
| ```toml | ||
| # One logical change: drop the devel sub-package AZL does not ship. | ||
| [metadata] | ||
| category = "azl-pruning" | ||
| upstream-status = "inapplicable" | ||
|
|
||
| [[overlays]] | ||
| description = "Remove the devel sub-package — AZL ships no -devel for this component" | ||
| type = "spec-remove-subpackage" | ||
| package = "devel" | ||
|
|
||
| [[overlays]] | ||
| description = "Drop the BuildRequires only the devel sub-package needed" | ||
| type = "spec-remove-tag" | ||
| tag = "BuildRequires" | ||
| value = "some-devel-only-dep" | ||
| ``` | ||
|
|
||
| ### Inline forms | ||
|
|
||
| Use inline `metadata` only when the component is already inline and you are not | ||
| restructuring it. A single-line inline table must fit on one line (no lists), so it is | ||
| limited to one or two scalar fields: | ||
|
|
||
| ```toml | ||
| [[components.rpm.overlays]] | ||
| description = "Customize RPM vendor to Azure Linux" | ||
| type = "spec-search-replace" | ||
| regex = "RPM_VENDOR=redhat" | ||
| replacement = "RPM_VENDOR=azurelinux" | ||
| metadata = { category = "azl-branding-policy", upstream-status = "inapplicable" } | ||
| ``` | ||
|
|
||
| Use the sub-table form whenever you need a list (`commits`, `bugs`) or more than a couple | ||
| of fields: | ||
|
|
||
| ```toml | ||
| [[components.xclock.overlays]] | ||
| description = "Pass --force to autoreconf so the build survives newer autotools" | ||
| type = "spec-search-replace" | ||
| regex = "autoreconf -i" | ||
| replacement = "autoreconf -fi" | ||
|
|
||
| [components.xclock.overlays.metadata] | ||
| category = "upstream-backport" | ||
| upstream-status = "upstreamed" | ||
| commits = [{ url = "https://src.fedoraproject.org/rpms/xclock/c/1e407488" }] | ||
| ``` | ||
|
|
||
| ## Step 5 — Verify | ||
|
|
||
| Adding or editing metadata must be a no-op on the rendered spec. Re-render and confirm | ||
| there is no diff: | ||
|
|
||
| ```sh | ||
| azldev comp render -p <name> | ||
| git diff specs/ | ||
| ``` | ||
|
|
||
| If you also moved overlays into files, prove the apply order was preserved with | ||
| `azldev comp diff-sources -p <name>` before and after — any difference means an overlay | ||
| changed or the sequence shifted. Metadata-only edits need no rebuild or lock refresh; if | ||
| you also changed an overlay's behavior, finalize with the `azldev-update-component` skill. | ||
|
|
||
| Generated by `azldev docs agent`; do not hand-edit. Generated for azldev version `v0.4.0`. |
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
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
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
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1 @@ | ||
| 261ae7471a4421377d557c51aaae70add8bc9caf | ||
| faaa0f4e6f4a59b3ccdd723be0802520a67db9c8 |
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
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
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
Oops, something went wrong.
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
question(non-blocking): Nan Liu (@liunan-ms) I don't think we should change it this second, but what do you think about having fewer files updated solely to bump the version? Perhaps there could be a single text file / README left behind in .agent/skills/ somewhere that indicates which version of azldev generated these, though?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That makes sense. I’ll follow up on implementing that in azldev.