Abwärtskompatibilität

Kunden fixieren eine Version des Code-Repositorys und führen Upgrades nach ihrem eigenen Zeitplan durch, manchmal mehrere Versionen auf einmal. Ein release ist abwärtskompatibel, wenn ein Kunde die Version anheben, hub und spoke im Plan mode ausführen und keine Änderungen sehen kann, die er nicht angefordert hat.

Der Vertrag

Versionssprung	Zusage an den Kunden
Patch (v4.12.1 → v4.12.2)	Nur Bugfixes. Keine Konfigurationsänderungen nötig. Pläne zeigen keine Änderungen oder nur den Fix.
Minor (v4.11.x → v4.12.0)	Neue Features, alle opt-in. Bestehende Konfiguration funktioniert weiter. Jeder manuelle Schritt wird in einem versionsspezifischen Upgrade-Leitfaden beschrieben.
Major (v4.x → v5.0)	Breaking Changes sind erlaubt, aber jede einzelne wird mit ihrer Migration im Upgrade-Leitfaden aufgeführt.

Versionssprünge ergeben sich aus der merge-Nachricht (+semver: major|minor|patch, siehe Releasing). Ein Breaking Change, der mit +semver: minor gemergt wird, bricht den Vertrag.

Regeln für Contributors

Neue Features

• Lege jede neue Ressource hinter ein feature flag (use_<x>_module, create_<x>, enable_<x>), Default false. Das bestehende Muster findest du in der feature-flags-Referenz.
• Gib jeder neuen Variable einen Default, der das heutige Verhalten beibehält. Eine neue Variable ohne Default zwingt jeden Kunden, seine tfvars zu ändern.
• Mache neue JSON-Properties im Schema optional (src/Xebia.Mcp/Files/json/*schema.json). Eine neue erforderliche Schema-Property lässt den config test für jede bestehende Datei fehlschlagen.

Umbenennungen und Refactorings

• Benenne niemals eine Terraform-Ressourcen- oder Modul-Adresse ohne moved-Block um. Beispiele im Code: module.virtual_wan[0] → module.virtual_wan (infra/deploy/connectivity/main.tf) und module.policy_assignements → module.policy_assignments (infra/deploy/postdeployment/main.tf).
• Wenn sich der Schlüssel eines for_each ändert (zum Beispiel vom Dateipfad zu name), reicht ein moved-Block nicht aus. Füge ein Migrations-Flag hinzu, das standardmäßig die alten Schlüssel beibehält, etwa use_new_ip_group_naming, use_new_fwp_rulecollectiongroup_naming und use_new_application_gateway_naming. Das Umlegen eines solchen Flags ist eine Migration, keine Standardänderung.
• Behalte den alten Codepfad bei, wenn du einen neuen hinzufügst, und wähle über ein Flag zwischen beiden. Der firewall layer unterstützt weiterhin das alte Single-Folder-Layout neben dem Multi-Region-Layout (use_multiregion_fwp_rulecollectiongroup_naming).
• Benenne eine Variable in einem Minor-release weder um noch entferne sie. Markiere sie zuerst als veraltet: behalte sie, vermerke das in ihrer Beschreibung und ignoriere sie. Beispiel: create_virtual_wan bleibt erhalten, ist aber als ungenutzt dokumentiert.

Provider- und Tool-Versionen

• Root modules fixieren Provider auf eine exakte Version. scripts/Test-TerraformRootProviderPins.ps1 prüft das im lefthook-pre-commit-Hook und im GitHub-Workflow CI.
• Ein Provider-Major-Upgrade (zum Beispiel azurerm 4 → 5) ist eine Major-Plattformversion und braucht einen Upgrade-Leitfaden.

Pipelines und Entry-Dateien

• Kunden pflegen ihre eigene Kopie der Entry-pipelines (hub.yaml, spoke.yaml, …). Ein neuer erforderlicher Template-Parameter bricht ihre pipeline. Füge Parameter mit einem Default hinzu.
• Halte Azure DevOps und GitHub Actions auf demselben Stand (docs/PIPELINE_SYNCHRONIZATION.md im Code-Repository).

So prüfst du vor dem release

1. Führe hub und spoke im Plan-mode gegen die Demo-canary-Konfiguration aus, ohne sie zu ändern. Der Plan darf für bestehende Ressourcen keine Änderungen zeigen. Die pipeline pull-request.yaml des Code-Repositorys macht das für jeden pull request auf main (hub deploy und destroy, spoke deploy und destroy, jeweils in Plan/WhatIf).
2. Führe einen Plan gegen mindestens eine echte Kunden-canary auf dem release-Branch aus.
3. Wenn ein manueller Schritt nötig ist, schreibe den Upgrade-Leitfaden, bevor du den release taggst.

Wenn du nicht kompatibel bleiben kannst

Manchmal lässt sich eine Änderung nicht kompatibel umsetzen, zum Beispiel wenn Azure eine Policy oder eine API entfernt. Dann:

1. Erhöhe die Version mit +semver: major, oder dokumentiere den manuellen Schritt im Upgrade-Leitfaden des Minor-release, wenn die Auswirkung begrenzt und unvermeidbar ist.
2. Beschreibe jeden Schritt im Upgrade-Leitfaden: was im Konfigurations-Repository zu ändern ist, was im Azure portal zu entfernen ist und in welcher Reihenfolge.
3. Erwähne es in den release notes unter Breaking changes oder Known issues.

Beispiele aus früheren releases: v4.11.x hat die alten DNS-Policy-initiatives entfernt (Dateien, die im Konfigurations-Repository zu löschen sind, und Assignments, die im portal zu entfernen sind), und v4.12.x verlangte eine gültige firewall_policy_id in jeder App Gateway-JSON. Siehe Was zu tun ist, wenn eine neue Version veröffentlicht wird.

Was die Historie zeigt

Der Vertrag oben ist das Ziel. Die release-Historie zeigt, wo frühere releases manuelle Schritte brauchten und welche Arten von Änderungen sie verursachen:

Art der Änderung	Beispiel	Lehre
Policy- oder Alert-Objekte werden durch neue ersetzt	v4.4.0 (Policy-Sets in das Code-Repository verschoben), v4.5.1 (Alert-Policies), v4.7.0 (Defender-Assignments), v4.11.x und v4.12.x (DNS-Policy)	Die Leitfäden verlangen, die alten Objekte von Hand im portal zu entfernen. Führe im Upgrade-Leitfaden jedes Objekt mit seinem Scope auf und nenne die Reihenfolge, in der sie zu entfernen sind
Dateien im Konfigurations-Repository, die jetzt dem Code gehören	v4.4.0, v4.11.x	Liste die zu löschenden Dateien pro Umgebungsordner auf
Eine neue Pflicht-Einstellung mit einem Default, der nicht für jede Plattform passt	v4.4.0 (Overrides für state storage), v4.9.0 (Variable für den Firewallregel-Ordner)	Gib ihr einen Default, der das heutige Verhalten beibehält. Wo das nicht möglich ist, beschreibe im Leitfaden, wie man prüft und was zu setzen ist
Eine Änderung daran, wie Pfade oder Entry-pipelines geschrieben werden	v4.5.0, v4.9.0	Kunden besitzen ihre Entry-Dateien, daher ist eine Änderung dort immer ein manueller Schritt. Halte Änderungen an Entry-Dateien selten
Eine Property muss jetzt einen gültigen Wert enthalten	v4.12.x (firewall_policy_id)	Prüfe bestehende Dateien in einem Validierungsschritt und beschreibe, wie man sie korrigiert

Nutze die Tabelle als Review-Checkliste, wenn du entscheidest, ob eine Änderung eine Minor-Version sein kann. Die Upgrade-Leitfäden stehen unter Plattform-Upgrade-Leitfäden.