Release-Engineering-Richtlinie

Fünf Richtlinien regeln, wie apothem Releases veröffentlicht.

1. Semantische VersionierungCopy Anchor Link

Das Projekt wird unter Semantic Versioning 2.0 ausgeliefert. Versionsnummern haben die Form MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD].

Kandidaten-Tags verwenden das Format vX.Y.Z-rc.N (Release-Kandidat) oder vX.Y.Z-alpha.N / vX.Y.Z-beta.N (Frühzugang).

2. Release-TagsCopy Anchor Link

Jedes Release setzt auf main ein signiertes Git-Tag der Form vMAJOR.MINOR.PATCH. Das Tag löst .github/workflows/release.yml aus, das baut, signiert, SBOM und SLSA-3-Provenienz erzeugt und die GitHub-Release-Seite veröffentlicht.

Tag-Konventionen:

• Format — genau vMAJOR.MINOR.PATCH. Kein release--Präfix, kein -final-Suffix.
• Annotation — jedes Tag ist ein annotiertes Tag (git tag -a -s), das die Zusammenfassung der Release-Notes in der Tag-Nachricht trägt.
• Signatur — jedes Tag ist GPG-signiert. Der Release-Workflow erzeugt zusätzlich eine schlüssellose Sigstore-cosign-Signatur für jedes Artefakt und einen SLSA-3-Provenienzdatensatz, beide an die GitHub-Release-Seite angehängt.

Release-Modell: additivCopy Anchor Link

Releases sind additiv. Jedes Release fügt einen Commit auf main und ein Tag hinzu; main wird niemals per Force-Push überschrieben, und kein veröffentlichtes Tag, kein GitHub Release und keine npm-Version wird gelöscht, verschoben oder wiederverwendet. Jedes Release behält sein Tag, sein GitHub Release und seine npm-Version, und alle bleiben veröffentlicht. npm-Versionen sind unveränderlich: Ein veröffentlichtes name@version kann niemals ersetzt werden, und eine Nummer, deren Veröffentlichung zurückgezogen wurde, kann niemals wieder verwendet werden. Gepinnte Installationen und reproduzierbare Builds hängen von jedem veröffentlichten Tag ab. Die Runbooks zum Release-Zyklus und zur Release-Wiederherstellung folgen beide diesem Modell.

Die Release-Facade-Regel des Repositorys (der Abschnitt Release Facade der Anweisungen für Mitwirkende) gibt dieses Modell wieder. Die Anforderung, nur die aktuelle Version auszuweisen (in der Freshness-Facade-Regel gespiegelt), betrifft, was öffentliche Oberflächen aussagen. Die Regel begrenzt nicht, welche Releases veröffentlicht bleiben.

3. VeraltungsrichtlinieCopy Anchor Link

Die aktuelle öffentliche Supportlinie ist die zuletzt veröffentlichte Minor-Version. Wenn das Projekt mehrere öffentliche Minor-Versionen hat, ist die Matrix der unterstützten Versionen in SECURITY.md die maßgebliche Quelle für etwaige zusätzliche Supportfenster, die nur kritische Fehlerbehebungen umfassen.

Veraltungsrhythmus:

• Ankündigung — ein veraltetes Symbol oder Verhalten wird im Abschnitt ### Deprecated der CHANGELOG.md des Releases angekündigt, in dem die Veraltung landet. Die Release-Notes spiegeln die Veraltungsankündigung.
• Übergangsfenster — veraltete Symbole bleiben mindestens einen vollständigen Minor-Zyklus lang verfügbar, bevor sie entfernt werden.
• Entfernung — die Entfernung landet in einer MAJOR-Anhebung. Jedes entfernte Symbol trägt eine ### Removed-Zeile in CHANGELOG.md und einen Eintrag im Migrationsleitfaden unter Anleitungen.

Laufzeit-MindestversionenCopy Anchor Link

Apothem deklariert zwei Laufzeit-Mindestversionen: requires-python = ">=3.10" in pyproject.toml und "engines": {"node": ">=18"} in package.json.

• Jede deklarierte Mindestversion wird getestet. Die Python-Mindestversion läuft in der quality-Matrix der CI und im Workflow CI Matrix. Der Workflow npm Shim führt den npm-Shim auf der Node-Mindestversion und auf jeder späteren LTS-Hauptversion aus: Er prüft den Fehler bei fehlender Voraussetzung, node bin/apothem.mjs --version, eine Probeinstallation (Dry-Run) in einem isolierten Home-Verzeichnis und das gepackte Tarball über npx. Eine Laufzeit, die nicht getestet wird, wird nicht deklariert.
• Das Lebensende wird offengelegt. Wenn eine Laufzeit, die noch eine deklarierte Mindestversion ist, ihr Upstream-Lebensende (End of Life) erreicht, sagt der Installationsleitfaden dies und nennt die zu bevorzugenden Versionen. Python 3.10 erreichte sein Lebensende am 2026-10-01; Node.js 18 und 20 am 2025-04-30 bzw. 2026-04-30. Alle drei bleiben unterstützte Mindestversionen.
• Das Anheben einer Mindestversion ist eine Veraltung. Es folgt dem obigen Rhythmus: eine Ankündigung unter ### Deprecated, mindestens ein vollständiger Minor-Zyklus, in dem die alte Mindestversion weiter getestet wird, danach hält das Release, das sie anhebt, die Änderung fest. requires-python, engines.node, die Versionsprüfungen der Installer und die CI-Matrizen ändern sich gemeinsam in diesem Release.

4. Richtlinie für inkompatible ÄnderungenCopy Anchor Link

Inkompatible Änderungen erfordern:

1. Ein RFC-Issue — eröffnet mit dem Issue-Label rfcs, das die inkompatible Änderung, den Migrationspfad und die Rollback-Strategie beschreibt.
2. Ein 30-tägiges Kommentarfenster — das RFC bleibt vor dem Merge mindestens 30 Tage offen. Maintainer können das Fenster verlängern, wenn das Feedback es rechtfertigt.
3. Eine MAJOR-Anhebung — das Release, das die inkompatible Änderung einführt, hebt die MAJOR-Komponente an.
4. Ein Migrationsleitfaden — die Änderung wird mit einem Eintrag unter Anleitungen ausgeliefert, der den Operator durch die Migration führt.

5. Rollback-RichtlinieCopy Anchor Link

Wenn ein Release eine Regression aufweist, die die Einführung blockiert:

1. Zurücknehmen — der bzw. die verursachenden Commits werden auf main per Revert zurückgenommen.
2. Vorwärtskorrektur-Release — ein Folge-Release erscheint als vMAJOR.MINOR.PATCH+1 und trägt den Revert sowie etwaige inkrementelle Korrekturen. Das vorherige fehlerhafte Release wird nicht aus GitHub Releases gelöscht, und seine npm-Version bleibt veröffentlicht (npm-Versionen sind unveränderlich) und wird mit npm deprecate gekennzeichnet. Eine ### Yanked-Annotation in CHANGELOG.md dokumentiert die Situation, damit reproduzierbare Builds verankert bleiben.
3. Kommunikation — eine Security-Advisories-Benachrichtigung (wenn sicherheitsrelevant) oder ein für den Vorfall angeheftetes GitHub-Issue (wenn zuverlässigkeitsrelevant) begleitet den Rollback.

Siehe auchCopy Anchor Link

• CHANGELOG.md — das kanonische Release-Register.
• SECURITY.md — Matrix der unterstützten Versionen und Meldekanäle.
• cicd-pipeline.md — die Klassen von CI-Prüfungen, die jedes Release absichern.
• deployment-checklist.md — der Produktionsreife-Durchlauf pro Release.