Releasen

Een release maakt nieuwe functionaliteit beschikbaar voor klanten als een gepinde versie van de coderepository. Klanten upgraden wanneer zij dat willen; zie Wat te doen als er een nieuwe versie is uitgebracht. De releasegeschiedenis en de upgradehandleidingen staan in Releases en upgradebegeleiding.

Versiebeheer

Versies worden berekend door GitVersion (.GitVersion.yml, workflow GitHubFlow/v1, mode ContinuousDelivery):

Branch	Patroon	Label	Verhoging
main	^main$	alpha	Minor
Release	release/v<major>.<minor>	beta	Patch
Feature	feature/<name> of features/<name>	<name>	Overgenomen

• Releases krijgen een tag v<major>.<minor>.<patch> op de release branch (bijvoorbeeld v4.12.2 op release/v4.12).

• Verhogingen komen alleen uit merge messages (commit-message-incrementing: MergeMessageOnly):

  Merge message bevat	Verhoging
  +semver: major of +semver: breaking	major
  +semver: minor of +semver: feature	minor
  +semver: patch of +semver: fix	patch
  +semver: none of +semver: skip	geen

• Klanten pinnen een release branch (release/v4.12), dus ze krijgen patch releases op die branch automatisch bij hun volgende run. Ze wijzigen de pin om naar een nieuwe minor- of major-versie te gaan.

Een gepinde release branch beweegt mee

Omdat entry pipelines release/vX.Y pinnen en geen tag, bereikt een patch die naar die branch wordt gemerged klanten bij hun volgende container + hub run. Beschouw elke merge naar een release branch als een release voor alle klanten op die minor versie.

Container image tags

Get-XebiaMcpContainerTags.ps1 tagt elk mcp image:

Build van	Tags
elke commit	de semantische versie en sha-<short sha>
main	+ alpha
een release branch	+ beta
een getagde release-commit	+ latest
een feature branch	+ latest-<label>

Entry pipelines draaien op imageRef: mcp:latest. Het image wordt gebouwd in de eigen ACR van elke klant door hun container pipeline, vanaf de codeversie die ze pinnen.

Releasestappen

flowchart LR
    m["main<br/>(features gemerged)"] --> rb["1. Maak release/vX.Y aan"]
    rb --> v["2. Valideren<br/>Demo + klant-canary"]
    v --> g["3. Upgradehandleiding"]
    g --> t["4. Tag vX.Y.0"]
    t --> s["5. Sync naar remotes"]
    s --> n["6. Release notes"]
    n --> c["7. Communiceren"]

1. De release branch aanmaken

Maak release/v<major>.<minor> aan vanaf main zodra de features voor de versie gemerged zijn. Vanaf dat moment gaan er alleen fixes naar deze branch.

2. Valideren

1. Draai container, daarna hub en spoke in Plan mode vanaf de release branch tegen de Demo canary- configuratie, zonder de configuratie te wijzigen. Verwacht geen wijzigingen voor bestaande resources (zie Achterwaartse compatibiliteit).
2. Apply op Demo canary en controleer de nieuwe features met hun flags aan.
3. Plan tegen minimaal één klant-canary. Noteer elke handmatige stap die je nodig had: die komen in de upgradehandleiding.

Eerdere releases gebruikten voor deze fase release-candidate tags (rc<version>, bijvoorbeeld rc4.8.0). Gebruik er een als je een vaste referentie nodig hebt om te testen.

3. De upgradehandleiding schrijven

Schrijf een versiespecifieke upgradehandleiding wanneer er ook maar enige actie van de klant nodig is naast het ophogen van de versie: nieuwe verplichte variabelen, bestanden die in de configuratierepository verwijderd of hernoemd moeten worden, resources of policy assignments die in de Azure portal verwijderd moeten worden, migratieflags die omgezet moeten worden, of een verplichte volgorde van stappen.

Gebruik deze structuur:

# Version <X.Y>.x – release-specific upgrade steps

## From v<previous X.Y>.x

### <Step title>

1. What to change, with the exact file path in the configuration repository
1. What to remove or check in the Azure portal, with the scope
1. Commit and push

## Expected plan

- Layer <layer>: <what you should see>, e.g. "replace of azurerm_… is expected"

Voeg de handleiding toe aan de upgradehandleidingen voor het platform, onder een kop Version <X.Y>.x, en voeg een rij toe aan de samenvattingstabel daarvan en aan de tabel met handmatige stappen in de releasegeschiedenis. Bestaande handleidingen zijn de beste voorbeelden. Voor hoe lezers ze gebruiken, zie Wat te doen als er een nieuwe versie is uitgebracht. Als er voor een versie geen handleiding bestaat, is er niets bijzonders nodig.

Schrijf de handleiding op basis van wat je tijdens de validatie (stap 2) nodig had, niet uit je hoofd: elke handmatige stap op de Demo- of klant-canary is een stap voor elke klant. Houd elke stap concreet (bestandspad, naam van het object, scope) en geef aan voor welke pipeline-indeling die geldt als die verschilt.

4. De release taggen

Tag de release-commit v<major>.<minor>.<patch> op de release branch. De getagde build krijgt de image tag latest.

5. Syncen naar klant-remotes

.github/workflows/trigger-sync.yaml draait bij pushes naar main, release/** en v* tags in xmms/xms-cloud-platform-code en roept xmms/xms-code-sync aan (sync-dispatcher.yaml). Controleer of de sync gedraaid heeft en doe een steekproef op een klant-remote voor de nieuwe branch of tag (geschiedenis van de branch bijgewerkt, tag aanwezig). Hoe de sync werkt, hoe doelen worden voorbereid en afgeschermd, en wat je controleert als de sync faalt: Codesynchronisatie.

6. De release notes schrijven

Release notes vertellen de mensen die de release oppakken wat er voor hen veranderd is. Ze zijn geen change log van de code. Vergelijk de nieuwe tag met de vorige, controleer de daadwerkelijke wijzigingen en niet alleen de commit-titels, en groepeer wat je vindt. Gebruik de work items die aan de commits gekoppeld zijn voor details. Laat werk dat alleen intern is weg.

# Release notes for version <version>

## New features
## Improvements
## Bug fixes
## Breaking changes
## Known issues

Link de upgradehandleiding vanuit de release notes als die er is. Voeg een korte vermelding van de versie toe aan de releasegeschiedenis als het een major of minor release is, of als er handmatige stappen nodig waren. De conventies voor de tekst staan in Release note conventions.

7. Communiceren

Stuur de release notes naar de mensen die de release oppakken:

• Managed klanten: de product owner van elke klant en de XMMS-engineers die die platformen beheren. Tot nu toe gebeurde dit per e-mail van het productteam, met de release notes als bijlage.
• Klanten met zelfbeheer: het platformteam van de klant, via het kanaal dat bij de overdracht is afgesproken (bijvoorbeeld de release notes in de coderepository die ze syncen, plus een bericht aan hun contactpersoon).

Release note conventions

Het spoke canvas hanteerde, toen het nog een apart product was, een korte en strikte opmaak voor zijn release notes. Dezelfde conventies werken ook voor de platformnotes, en ze vormen een goede basis voor een zelfbeherend platformteam dat zelf notes schrijft.

Regel	Waarom
Schrijf voor degene die de release oppakt, in gewone taal	De lezers zijn product owners en engineers van het platformteam, niet de schrijvers van de code
Zeg wat er voor de gebruiker veranderd is, niet hoe het gebouwd is. Geen coderverwijzingen, geen interne namen	Implementatiedetails helpen de lezer niet om te beslissen of te handelen
Groepeer verwante wijzigingen in één regel	Tien commits voor één feature zijn één nieuwe feature
Houd elk item kort: één regel, één wijziging	De notes moeten scanbaar zijn
Sorteer onder New features, Improvements en Bug fixes	Lezers zoeken eerst wat er nieuw is, dan wat er is opgelost
Noem de versie en de bump in de titel, bijvoorbeeld Spoke Canvas version 2.6.0 - Minor Release	De lezer ziet meteen hoeveel hij kan verwachten
Laat een kop zonder items weg	Een patchrelease heeft normaal alleen bugfixes
Weet je niet zeker wat een wijziging voor de gebruiker doet, vraag het de auteur	Een foute note is erger dan een late
Wijzig geen bestanden van de repository terwijl je de notes opstelt	Notes zijn output, geen code. Review het concept en publiceer het daarna waar je team de notes bewaart

Zo bereid je de notes voor:

1. Bepaal de versie: neem het nummer uit het releaseplan, of leid het af van de laatste tag en het type release (major, minor of patch).
2. Zorg dat je op de release branch zit en de nieuwste tags hebt opgehaald.
3. Zoek de laatste release tag (v*) en vergelijk die met de huidige head.
4. Lees de wijzigingen zelf. Titels en berichten zijn een begin, niet de bron.
5. Stel de notes op in de opmaak hieronder, in de stem van de voorbeelden.

Een concept voor een minor release van het spoke canvas zag er zo uit. De items zijn kort en beschrijven een resultaat:

# Spoke Canvas version 2.6.0 - Minor Release

## New features

- Support federated credentials using Workload Identity Federation
- Support checking out a different repository for spoke configuration

## Improvements

- Use server pool for approval job
- Create the Azure storage container for the Terraform state files if it does not exist

Een patchrelease heeft alleen de secties die van toepassing zijn:

# Spoke Canvas version 2.8.2 - Patch Release

## Bug fixes

- Changes to `required_resource_access` for the spoke service principal are now ignored to prevent unnecessary updates

Laat een assistent het concept maken, en een mens beslissen

De repository van het spoke canvas gebruikte een prompt voor een AI-assistent die het concept als snippet in de chat maakte uit het verschil tussen de laatste tag en main. Dat bespaart tijd, maar de auteur controleert nog steeds elk item aan de hand van de echte wijziging en bepaalt wat een breaking change of een known issue is. Die twee secties van het platformformaat vragen om een menselijk oordeel.

Patch releases

1. Fix op een branch vanaf main, merge met +semver: patch.
2. Cherry-pick de fix naar elke ondersteunde release/vX.Y branch (via een pull request naar die branch).
3. Valideer op Demo canary vanaf de release branch en tag vX.Y.<patch+1>.
4. Voeg een regel toe aan de release notes van die versie, onder Bug fixes, in de stijl van de release note conventions.

Huidige releasestatus

Waargenomen in de repositories op 15 oktober 2026:

Onderdeel	Status
Laatste tags	v4.12.2, v4.12.1, v4.12.0, v4.11.4
Release branches	release/v4.9, release/v4.10, release/v4.11, release/v4.12
Referentieconfiguratierepository (XDEV)	pint release/v4.11
Release notes	Bijgehouden als notes tot en met v4.6.1; de overzichtspagina van die notes zegt "current stable v4.4.0" (verouderd). Samengevat in de releasegeschiedenis. Er bestaan geen notes voor v4.7 en later
Upgradehandleidingen	Tot en met v4.12.x, in Upgradehandleidingen voor het platform