From 218099e400fa827b609b63ecceeea56fbc956c0e Mon Sep 17 00:00:00 2001 From: Nan Liu Date: Thu, 9 Jul 2026 23:42:27 +0000 Subject: [PATCH] refactor(overlays): rename azl-dep-missing-workaround to azl-temp-workaround Broaden the category to cover any overlay that is explicitly intended to be dropped once an upstream or environmental fix lands, including (but not limited to) workarounds for dependencies not yet imported into AZL. Also broaden the azl-branding-policy to cover fixes for upstream code that hard-codes Fedora identity strings --- docs/user/reference/config/overlays.md | 6 ++--- internal/projectconfig/overlay_metadata.go | 22 ++++++++++--------- .../projectconfig/overlay_metadata_test.go | 4 ++-- ...ainer_config_generate-schema_stdout_1.snap | 2 +- ...shots_config_generate-schema_stdout_1.snap | 2 +- schemas/azldev.schema.json | 2 +- 6 files changed, 20 insertions(+), 18 deletions(-) diff --git a/docs/user/reference/config/overlays.md b/docs/user/reference/config/overlays.md index 9ff05e67..40e7a6d4 100644 --- a/docs/user/reference/config/overlays.md +++ b/docs/user/reference/config/overlays.md @@ -93,9 +93,9 @@ Overlays can carry an optional `metadata` table that documents *why* the overlay |----------|-------------| | `upstream-backport` | Fix backported 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. Requires at least one entry in `commits` pointing to the upstream change. `upstream-status` must be `upstreamed` or `upstreamable` — any other value contradicts the category. See [Upstream status](#upstream-status). | | `azl-pruning` | Removing content from a component for AZL: dependencies that are not shipped, unneeded features, subpackages, or files. | -| `azl-compatibility` | Making a component work in the AZL build/runtime environment: toolchain and mock adjustments, and similar compatibility fixes that are not themselves backports. | -| `azl-dep-missing-workaround` | Working around a runtime or build dependency that has not yet been imported into AZL (or is unavailable on a given target). Drop the overlay once the dependency lands. | -| `azl-branding-policy` | Fedora→Azure Linux name/path changes; RHEL/enterprise convention alignment. | +| `azl-compatibility` | Adapting a component to *how Azure Linux is built and shipped* — its build tooling, buildroot, infrastructure, and runtime ecosystem — when an upstream package builds or behaves incorrectly for AZL-specific reasons that are not branding, a missing dependency, architecture, or tests. Examples: quirks of the `azldev` source downloader, reproducibility fixes for AZL's multi-arch Koji `rpmdiff`, buildroot gaps where an AZL build option breaks a transitive dependency, and Fedora version-skew or config fixes for AZL targets. Use `upstream-status` to separate AZL-only concerns (`inapplicable`) from fixes upstream could also take (`upstreamable` / `upstreamed`). | +| `azl-temp-workaround` | Temporary workaround that is explicitly intended to be dropped once an upstream or environmental fix lands. Covers overlays working around a runtime or build dependency that has not yet been imported into AZL (or is unavailable on a given target), as well as any other transient workaround waiting on an external change. Drop the overlay once the fix lands. | +| `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`, `-redhat-linux[-gnu]` triples, `redhat-linux-build` dirs). Covers both permanent branding choices and the fallout from AZL setting `_vendor=azurelinux`; use `upstream-status` to separate permanent choices (`inapplicable`) from upstreamable fallout (`upstreamable` / `needs-upstream-hook`). | | `azl-disable-flaky-tests` | Skipping tests that fail intermittently or due to environmental flakiness rather than a real problem with the component. | | `azl-disable-unsupported-tests` | Skipping tests that cannot meaningfully run in AZL's build/runtime environment (e.g. tests that require network access, root, or hardware that is unavailable in mock). | | `azl-security-compliance` | FIPS or crypto-policy changes. | diff --git a/internal/projectconfig/overlay_metadata.go b/internal/projectconfig/overlay_metadata.go index 4bc5c302..0c07b3a3 100644 --- a/internal/projectconfig/overlay_metadata.go +++ b/internal/projectconfig/overlay_metadata.go @@ -26,15 +26,17 @@ const ( OverlayCategoryAZLPruning OverlayCategory = "azl-pruning" // OverlayCategoryAZLCompatibility makes a component work in the AZL build/runtime // environment: toolchain and mock adjustments and similar compatibility fixes that - // are not themselves backports. See [OverlayCategoryAZLDepMissingWorkaround] for - // workarounds for dependencies that have not yet been imported into AZL. + // are not themselves backports. OverlayCategoryAZLCompatibility OverlayCategory = "azl-compatibility" - // OverlayCategoryAZLDepMissingWorkaround works around a runtime or build dependency - // that has not yet been imported into AZL (or is unavailable on a given target). Drop - // the overlay once the dependency lands. - OverlayCategoryAZLDepMissingWorkaround OverlayCategory = "azl-dep-missing-workaround" - // OverlayCategoryAZLBrandingPolicy applies Fedora→AzureLinux name/path changes or - // RHEL/enterprise convention alignment. + // OverlayCategoryAZLTemporaryWorkaround marks overlays that are explicitly intended to be + // dropped once an upstream or environmental fix lands. This covers both overlays that + // work around a runtime or build dependency that has not yet been imported into AZL + // and any other transient workaround waiting on an external change. + OverlayCategoryAZLTemporaryWorkaround OverlayCategory = "azl-temp-workaround" + // OverlayCategoryAZLBrandingPolicy handles Fedora→Azure Linux identity differences: + // name/path/vendor conventions and fixes for specs that hard-code Fedora identity + // strings (e.g. `_vendor=redhat`, `redhat-linux` triples). Use `upstream-status` to + // distinguish permanent AZL choices from fallout that could be upstreamed. OverlayCategoryAZLBrandingPolicy OverlayCategory = "azl-branding-policy" // OverlayCategoryAZLDisableFlakyTests skips tests that fail intermittently or due to // environmental flakiness rather than a real problem with the component, @@ -59,7 +61,7 @@ var allOverlayCategories = []OverlayCategory{ OverlayCategoryUpstreamBackport, OverlayCategoryAZLPruning, OverlayCategoryAZLCompatibility, - OverlayCategoryAZLDepMissingWorkaround, + OverlayCategoryAZLTemporaryWorkaround, OverlayCategoryAZLBrandingPolicy, OverlayCategoryAZLDisableFlakyTests, OverlayCategoryAZLDisableUnsupportedTests, @@ -130,7 +132,7 @@ type URLRef struct { // are optional but constrained by category-specific rules (see [OverlayMetadata.Validate]). type OverlayMetadata struct { // Category classifies the overlay's intent. Required. - Category OverlayCategory `toml:"category" json:"category" jsonschema:"required,enum=upstream-backport,enum=azl-pruning,enum=azl-compatibility,enum=azl-dep-missing-workaround,enum=azl-branding-policy,enum=azl-disable-flaky-tests,enum=azl-disable-unsupported-tests,enum=azl-security-compliance,enum=azl-release-management,enum=azl-platform-adaptation,title=Category,description=Classification of the overlay's intent"` + Category OverlayCategory `toml:"category" json:"category" jsonschema:"required,enum=upstream-backport,enum=azl-pruning,enum=azl-compatibility,enum=azl-temp-workaround,enum=azl-branding-policy,enum=azl-disable-flaky-tests,enum=azl-disable-unsupported-tests,enum=azl-security-compliance,enum=azl-release-management,enum=azl-platform-adaptation,title=Category,description=Classification of the overlay's intent"` // Commits references upstream commits (typically Fedora dist-git or upstream-project // commits) that this overlay backports or references. Each entry must carry an diff --git a/internal/projectconfig/overlay_metadata_test.go b/internal/projectconfig/overlay_metadata_test.go index 46ce0a1f..2d683bd2 100644 --- a/internal/projectconfig/overlay_metadata_test.go +++ b/internal/projectconfig/overlay_metadata_test.go @@ -56,9 +56,9 @@ func TestOverlayMetadata_Validate(t *testing.T) { }, }, { - name: "azl-dep-missing-workaround with unknown status is valid", + name: "azl-temp-workaround with unknown status is valid", metadata: projectconfig.OverlayMetadata{ - Category: projectconfig.OverlayCategoryAZLDepMissingWorkaround, + Category: projectconfig.OverlayCategoryAZLTemporaryWorkaround, UpstreamStatus: projectconfig.OverlayUpstreamStatusUnknown, }, }, diff --git a/scenario/__snapshots__/TestSnapshotsContainer_config_generate-schema_stdout_1.snap b/scenario/__snapshots__/TestSnapshotsContainer_config_generate-schema_stdout_1.snap index 3fc85201..3d337d26 100755 --- a/scenario/__snapshots__/TestSnapshotsContainer_config_generate-schema_stdout_1.snap +++ b/scenario/__snapshots__/TestSnapshotsContainer_config_generate-schema_stdout_1.snap @@ -746,7 +746,7 @@ "upstream-backport", "azl-pruning", "azl-compatibility", - "azl-dep-missing-workaround", + "azl-temp-workaround", "azl-branding-policy", "azl-disable-flaky-tests", "azl-disable-unsupported-tests", diff --git a/scenario/__snapshots__/TestSnapshots_config_generate-schema_stdout_1.snap b/scenario/__snapshots__/TestSnapshots_config_generate-schema_stdout_1.snap index 3fc85201..3d337d26 100755 --- a/scenario/__snapshots__/TestSnapshots_config_generate-schema_stdout_1.snap +++ b/scenario/__snapshots__/TestSnapshots_config_generate-schema_stdout_1.snap @@ -746,7 +746,7 @@ "upstream-backport", "azl-pruning", "azl-compatibility", - "azl-dep-missing-workaround", + "azl-temp-workaround", "azl-branding-policy", "azl-disable-flaky-tests", "azl-disable-unsupported-tests", diff --git a/schemas/azldev.schema.json b/schemas/azldev.schema.json index 3fc85201..3d337d26 100644 --- a/schemas/azldev.schema.json +++ b/schemas/azldev.schema.json @@ -746,7 +746,7 @@ "upstream-backport", "azl-pruning", "azl-compatibility", - "azl-dep-missing-workaround", + "azl-temp-workaround", "azl-branding-policy", "azl-disable-flaky-tests", "azl-disable-unsupported-tests",