refactor(overlays): rename azl-dep-missing-workaround to azl-temp-workaround

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`, `<cpu>-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. |

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

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

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

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

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