Achterwaartse compatibiliteit

Klanten pinnen een versie van de coderepository vast en upgraden op hun eigen tempo, soms meerdere versies tegelijk. Een release is achterwaarts compatibel wanneer een klant de versie kan ophogen, hub en spoke in Plan-modus kan draaien en geen wijzigingen ziet die niet zijn aangevraagd.

Het contract

Versieverhoging	Belofte aan de klant
Patch (v4.12.1 → v4.12.2)	Alleen bugfixes. Geen configuratiewijzigingen nodig. Plans tonen geen wijzigingen, of alleen de fix.
Minor (v4.11.x → v4.12.0)	Nieuwe functionaliteit, allemaal opt-in. Bestaande configuratie blijft werken. Elke handmatige stap staat beschreven in een versiespecifieke upgradehandleiding.
Major (v4.x → v5.0)	Breaking changes zijn toegestaan, maar elke wijziging staat met bijbehorende migratie in de upgradehandleiding.

Versieverhogingen komen uit het merge-bericht (+semver: major|minor|patch, zie Releasen). Een breaking change die met +semver: minor wordt gemerged, schendt het contract.

Regels voor contributors

Nieuwe functionaliteit

• Zet elke nieuwe resource achter een feature flag (use_<x>_module, create_<x>, enable_<x>), standaard false. Zie de feature flags-referentie voor het bestaande patroon.
• Geef elke nieuwe variabele een standaardwaarde die het huidige gedrag behoudt. Een nieuwe variabele zonder standaardwaarde dwingt elke klant om de eigen tfvars aan te passen.
• Maak nieuwe JSON-properties optioneel in het schema (src/Xebia.Mcp/Files/json/*schema.json). Een nieuwe verplichte schema-property laat de config test voor elk bestaand bestand falen.

Hernoemen en refactoren

• Hernoem nooit een Terraform-resource of module-adres zonder moved block. Voorbeelden in de code: module.virtual_wan[0] → module.virtual_wan (infra/deploy/connectivity/main.tf) en module.policy_assignements → module.policy_assignments (infra/deploy/postdeployment/main.tf).
• Wanneer de key van een for_each verandert (bijvoorbeeld van bestandspad naar name), is een moved block niet genoeg. Voeg een migratieflag toe die standaard de oude keys behoudt, zoals use_new_ip_group_naming, use_new_fwp_rulecollectiongroup_naming en use_new_application_gateway_naming. Zo'n flag omzetten is een migratie, geen standaardwijziging.
• Behoud het oude codepad wanneer je een nieuw pad toevoegt, en kies tussen beide met een flag. De firewall layer ondersteunt nog steeds de legacy indeling met één map naast de multi-region-indeling (use_multiregion_fwp_rulecollectiongroup_naming).
• Hernoem of verwijder geen variabele in een minor release. Deprecate hem eerst: behoud hem, vermeld dat in de beschrijving en negeer hem. Bijvoorbeeld: create_virtual_wan blijft bestaan maar is gedocumenteerd als ongebruikt.

Provider- en toolversies

• Root modules pinnen providers op een exacte versie. scripts/Test-TerraformRootProviderPins.ps1 controleert dit in de lefthook pre-commit hook en in de GitHub CI workflow.
• Een major upgrade van een provider (bijvoorbeeld azurerm 4 → 5) is een major platformversie en vereist een upgradehandleiding.

Pipelines en entry-bestanden

• Klanten beheren hun eigen kopie van de entry pipelines (hub.yaml, spoke.yaml, …). Een nieuwe verplichte template parameter breekt hun pipeline. Voeg parameters toe met een standaardwaarde.
• Houd Azure DevOps en GitHub Actions gelijk (docs/PIPELINE_SYNCHRONIZATION.md in de coderepository).

Controleren voordat je released

1. Draai hub en spoke in Plan-modus tegen de Demo canary-configuratie zonder die te wijzigen. De plan moet geen wijzigingen tonen voor bestaande resources. De pull-request.yaml pipeline van de coderepository doet dit voor elke pull request naar main (hub deploy en destroy, spoke deploy en destroy, allemaal in Plan/WhatIf).
2. Draai een plan tegen minstens één echte klant-canary op de releasebranch.
3. Als er een handmatige stap nodig is, schrijf dan de upgradehandleiding voordat je de release tagt.

Wanneer je niet compatibel kunt blijven

Soms kan een wijziging niet compatibel worden gemaakt, bijvoorbeeld wanneer Azure een policy of een API verwijdert. Doe dan het volgende:

1. Verhoog de versie als +semver: major, of documenteer de handmatige stap in de upgradehandleiding van de minor release als de impact beperkt en onvermijdelijk is.
2. Beschrijf elke stap in de upgradehandleiding: wat je moet wijzigen in de configuratierepository, wat je moet verwijderen in de Azure portal, en in welke volgorde.
3. Noem het in de release notes onder Breaking changes of Known issues.

Voorbeelden uit eerdere releases: v4.11.x verwijderde de oude DNS policy initiatives (bestanden om te verwijderen in de configuratie repository en assignments om te verwijderen in de portal), en v4.12.x vereiste een geldige firewall_policy_id in elke App Gateway JSON. Zie Wat te doen als een nieuwe versie wordt gereleased.

Wat de geschiedenis laat zien

Het contract hierboven is het doel. De releasegeschiedenis laat zien waar eerdere releases handmatige stappen nodig hadden en welke soorten wijzigingen daarvoor zorgen:

Soort wijziging	Voorbeeld	Les
Policy- of alertobjecten die door nieuwe worden vervangen	v4.4.0 (policy sets verhuisd naar de coderepository), v4.5.1 (alert policies), v4.7.0 (Defender assignments), v4.11.x en v4.12.x (DNS policy)	De handleidingen vragen om de oude objecten met de hand in de portal te verwijderen. Noem ze stuk voor stuk in de upgradehandleiding, met hun scope, en zeg in welke volgorde ze verwijderd moeten worden
Bestanden in de configuratierepository die de code nu zelf beheert	v4.4.0, v4.11.x	Noem de te verwijderen bestanden per omgevingsmap
Een nieuwe verplichte instelling met een standaardwaarde die niet voor elk platform past	v4.4.0 (overrides voor state storage), v4.9.0 (variabele voor de map met firewallregels)	Geef een standaardwaarde die het huidige gedrag behoudt. Waar dat niet kan, leg in de handleiding uit hoe je controleert en wat je instelt
Een wijziging in hoe paden of entry pipelines worden geschreven	v4.5.0, v4.9.0	Klanten beheren hun eigen entry-bestanden, dus een wijziging daar is altijd een handmatige stap. Houd wijzigingen in entry-bestanden zeldzaam
Een eigenschap moet nu een geldige waarde hebben	v4.12.x (firewall_policy_id)	Controleer bestaande bestanden in een validatiestap en leg uit hoe je ze herstelt

Gebruik de tabel als reviewchecklist wanneer je bepaalt of een wijziging een minor versie kan zijn. De upgradehandleidingen staan in Upgradehandleidingen voor het platform.