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",