Releasing

Ein release macht neue Funktionalität für Kunden als gepinnte Version des Code-Repositorys verfügbar. Kunden führen das Upgrade durch, wann sie wollen; siehe Was zu tun ist, wenn eine neue Version veröffentlicht wird. Die Release-Historie und die Upgrade- Leitfäden stehen unter Releases und Upgrade-Hinweise.

Versionierung

Versionen werden von GitVersion berechnet (.GitVersion.yml, Workflow GitHubFlow/v1, Modus ContinuousDelivery):

Branch	Muster	Label	Inkrement
main	^main$	alpha	Minor
Release	release/v<major>.<minor>	beta	Patch
Feature	feature/<name> oder features/<name>	<name>	Geerbt

• Releases werden mit v<major>.<minor>.<patch> auf dem release branch getaggt (zum Beispiel v4.12.2 auf release/v4.12).

• Versionssprünge kommen nur aus Merge-Messages (commit-message-incrementing: MergeMessageOnly):

  Merge-Message enthält	Sprung
  +semver: major oder +semver: breaking	major
  +semver: minor oder +semver: feature	minor
  +semver: patch oder +semver: fix	patch
  +semver: none oder +semver: skip	none

• Kunden pinnen einen release branch (release/v4.12) und erhalten Patch-Releases auf diesem Branch daher automatisch beim nächsten Lauf. Sie ändern den Pin, um auf eine neue Minor- oder Major-Version zu wechseln.

Ein gepinnter release branch bewegt sich

Da Entry Pipelines release/vX.Y und keinen Tag pinnen, erreicht ein auf diesen Branch gemergter Patch die Kunden beim nächsten container + hub-Lauf. Behandle jeden Merge auf einen release branch als Release für alle Kunden auf dieser Minor- Version.

Container-Image-Tags

Get-XebiaMcpContainerTags.ps1 taggt jedes mcp-Image:

Build von	Tags
jedem Commit	die semantische Version und sha-<short sha>
main	+ alpha
einem release branch	+ beta
einem getaggten Release-Commit	+ latest
einem Feature-Branch	+ latest-<label>

Entry Pipelines laufen auf imageRef: mcp:latest. Das Image wird in der eigenen ACR jedes Kunden von dessen container Pipeline gebaut, aus der Code-Version, die er pinnt.

Release-Schritte

flowchart LR
    m["main<br/>(features merged)"] --> rb["1. Cut release/vX.Y"]
    rb --> v["2. Validate<br/>Demo + customer canary"]
    v --> g["3. Upgrade guide"]
    g --> t["4. Tag vX.Y.0"]
    t --> s["5. Sync to remotes"]
    s --> n["6. Release notes"]
    n --> c["7. Communicate"]

1. Den release branch anlegen

Lege release/v<major>.<minor> von main aus an, wenn die Features für die Version gemergt sind. Ab jetzt gehen nur noch Fixes auf diesen Branch.

2. Validieren

1. Führe container aus, dann hub und spoke im Plan-Modus vom release branch aus gegen die Demo-canary- Konfiguration, ohne die Konfiguration zu ändern. Erwarte keine Änderungen an bestehenden Ressourcen (siehe Abwärtskompatibilität).
2. Wende auf Demo canary an und prüfe die neuen Features mit eingeschalteten Flags.
3. Plane gegen mindestens ein Kunden-canary. Notiere jeden manuellen Schritt, den du brauchtest: Diese gehören in den Upgrade-Leitfaden.

Frühere Releases verwendeten für diese Phase Release-Candidate-Tags (rc<version>, zum Beispiel rc4.8.0). Nutze einen, wenn du eine feste Referenz zum Testen brauchst.

3. Den Upgrade-Leitfaden schreiben

Schreibe einen versionsspezifischen Upgrade-Leitfaden, wenn irgendeine Kundenaktion über das Anheben der Version hinaus nötig ist: neue Pflicht- variablen, Dateien, die im Konfigurations-Repository gelöscht oder umbenannt werden müssen, Ressourcen oder Policy-Zuweisungen, die im Azure-Portal entfernt werden müssen, Migrations-Flags, die umgelegt werden müssen, oder eine vorgeschriebene Reihenfolge der Schritte.

Verwende diese Struktur:

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

Füge den Leitfaden den Upgrade-Leitfäden der Plattform hinzu, unter einer Überschrift Version <X.Y>.x, und ergänze eine Zeile in deren Übersichtstabelle und in der Tabelle der manuellen Schritte in der Release-Historie. Die bestehenden Leitfäden sind die besten Beispiele. Wie Leser sie nutzen, steht unter Was zu tun ist, wenn eine neue Version veröffentlicht wird. Gibt es für eine Version keinen Leitfaden, ist nichts Besonderes nötig.

Schreibe den Leitfaden anhand dessen, was du bei der Validierung (Schritt 2) gebraucht hast, nicht aus dem Gedächtnis: Jeder manuelle Schritt auf dem Demo- oder Kunden- canary ist ein Schritt für jeden Kunden. Halte jeden Schritt konkret (Dateipfad, Name des Objekts, Scope) und sage, für welches pipeline- Layout er gilt, wenn es abweicht.

4. Das Release taggen

Tagge den Release-Commit v<major>.<minor>.<patch> auf dem release branch. Der getaggte Build erhält den Image-Tag latest.

5. Zu den Kunden-Remotes synchronisieren

.github/workflows/trigger-sync.yaml läuft bei Pushes auf main, release/** und v*-Tags in xmms/xms-cloud-platform-code und ruft xmms/xms-code-sync (sync-dispatcher.yaml) auf. Prüfe, dass die Synchronisierung gelaufen ist, und kontrolliere stichprobenartig einen Kunden-Remote auf den neuen Branch oder Tag (Historie des Branches aktualisiert, Tag vorhanden). Wie die Synchronisierung funktioniert, wie Ziele vorbereitet und abgesichert werden und was du bei einem Fehler prüfst: Code-Synchronisierung.

6. Die Release Notes schreiben

Release Notes sagen den Personen, die das Release übernehmen, was sich für sie geändert hat. Sie sind kein Change Log des Codes. Vergleiche den neuen Tag mit dem vorherigen, prüfe die tatsächlichen Änderungen und nicht nur die Commit-Titel und gruppiere, was du findest. Nutze die mit den Commits verknüpften Work Items für Details. Lass rein interne Arbeit weg.

# Release notes for version <version>

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

Verlinke den Upgrade-Leitfaden aus den Release Notes, wenn es einen gibt. Füge der Release-Historie einen kurzen Eintrag für die Version hinzu, wenn es ein Major- oder Minor-Release ist oder wenn es manuelle Schritte brauchte. Die Konventionen für den Text stehen unter Konventionen für release notes.

7. Kommunizieren

Sende die Release Notes an die Personen, die das Release übernehmen:

• Managed-Kunden: der Product Owner jedes Kunden und die XMMS-Engineers, die diese Plattformen betreiben. Bisher geschah das per E-Mail vom Produktteam, mit den Release Notes im Anhang.
• Kunden im Eigenbetrieb (self-managed): das Plattform-Team des Kunden, über den bei der Übergabe vereinbarten Kanal (zum Beispiel die Release Notes im Code-Repository, das sie synchronisieren, plus eine Benachrichtigung an ihren Ansprechpartner).

Konventionen für release notes

Der spoke canvas hatte, als er noch ein eigenes Produkt war, ein kurzes, striktes Format für seine Release Notes. Dieselben Konventionen funktionieren für die Plattform-Notes und sind eine gute Grundlage für ein Plattform-Team im Eigenbetrieb, das seine eigenen Notes schreibt.

Regel	Warum
Schreibe für die Person, die das Release übernimmt, in einfacher Sprache	Die Leser sind Product Owner und Engineers des Plattform-Teams, nicht die Autoren des Codes
Sag, was sich für den Nutzer geändert hat, nicht wie es gebaut wurde. Keine Code-Verweise, keine internen Namen	Implementierungsdetails helfen dem Leser nicht, zu entscheiden oder zu handeln
Fasse zusammengehörige Änderungen in einer Zeile zusammen	Zehn Commits für ein Feature sind ein neues Feature
Halte jeden Punkt kurz: eine Zeile, eine Änderung	Die Notes müssen überfliegbar sein
Sortiere unter New features, Improvements und Bug fixes	Leser suchen zuerst, was neu ist, dann, was behoben ist
Nenne Version und Versionssprung im Titel, zum Beispiel Spoke Canvas version 2.6.0 - Minor Release	Der Leser sieht sofort, wie viel er erwarten kann
Lass eine Überschrift ohne Punkte weg	Ein Patch-Release hat normalerweise nur Bug fixes
Wenn du unsicher bist, was eine Änderung für den Nutzer bewirkt, frag den Autor	Eine falsche Note ist schlimmer als eine späte
Ändere beim Entwerfen keine Dateien des Repositorys	Notes sind Output, kein Code. Prüfe den Entwurf und veröffentliche ihn dann dort, wo dein Team die Notes führt

So bereitest du die Notes vor:

1. Lege die Version fest: Nimm die Nummer aus dem Release-Plan oder leite sie vom neuesten Tag und der Art des Releases (major, minor oder patch) ab.
2. Stelle sicher, dass du auf dem release branch bist und die neuesten Tags geholt hast.
3. Finde den neuesten Release-Tag (v*) und vergleiche ihn mit dem aktuellen Head.
4. Lies die Änderungen selbst. Titel und Nachrichten sind ein Anfang, nicht die Quelle.
5. Entwirf die Notes im Format unten, im Ton der Beispiele.

Ein Entwurf für ein Minor-Release des spoke canvas sah so aus. Die Punkte sind kurz und beschreiben ein Ergebnis:

# 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

Ein Patch-Release hat nur die Abschnitte, die zutreffen:

# 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

Lass einen Assistenten entwerfen und einen Menschen entscheiden

Das Repository des spoke canvas verwendete einen Prompt für einen KI-Assistenten, der den Entwurf aus der Differenz zwischen dem neuesten Tag und main als Snippet im Chat erzeugte. Das spart nützlich Zeit, aber der Autor prüft weiterhin jeden Punkt gegen die echte Änderung und entscheidet, was ein Breaking Change oder ein Known Issue ist. Diese beiden Abschnitte des Plattform-Formats brauchen ein menschliches Urteil.

Patch-Releases

1. Fixe auf einem Branch von main, merge mit +semver: patch.
2. Cherry-picke den Fix auf jeden unterstützten release/vX.Y-Branch (über einen pull request auf diesen Branch).
3. Validiere auf Demo canary vom release branch aus und tagge vX.Y.<patch+1>.
4. Ergänze eine Zeile in den Release Notes dieser Version, unter Bug fixes, im Stil der Konventionen für release notes.

Release-Stand heute

Beobachtet in den Repositories am 15. Oktober 2026:

Element	Stand
Neueste 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
Referenz-Konfigurations-Repository (XDEV)	pinnt release/v4.11
Release Notes	Als Notizen bis v4.6.1 gepflegt; die Übersichtsseite dieser Notizen nennt "current stable v4.4.0" (veraltet). Verdichtet in der Release-Historie. Für v4.7 und später gibt es keine Notizen
Upgrade-Leitfäden	Bis v4.12.x, in Upgrade-Leitfäden der Plattform