Zum Hauptinhalt springen

Versionierung & Releases (SemVer)

Postbox folgt seit v2.0.0 (Laravel-13-Upgrade, Juni 2026) Semantic Versioning: MAJOR.MINOR.PATCH.

Source of Truth​

QuelleBedeutung
/VERSION (Repo-Root)Die Version, an der gerade gearbeitet wird (eine Zeile, z. B. 2.0.0)
Git-Tags vX.Y.ZReleased Stände — Tag + Push setzt ausschließlich der Maintainer
docs/changelog.mdDatumsbasierte Einträge; beim Release kommt ein Versions-Header ## vX.Y.Z — YYYY-MM-DD über die zugehörigen Einträge

Alles vor v2.0.0 ist Prä-SemVer-Historie (datumsbasierte Entwicklung ohne Versionsnummern).

Wann welcher Bump?​

BumpKriterium
MAJOR (3.0.0)Breaking Change: Framework-Major-Upgrade, Bruch im Collector-API-Vertrag (zählt als öffentliche API), inkompatible DB-/Config-Änderungen, entfernte Features
MINOR (2.1.0)Neue Features, Seiten, Commands, Endpoints — abwärtskompatibel
PATCH (2.0.1)Bugfixes, Doku, Refactorings ohne Verhaltensänderung, Dependency-Patches

Branch-Konvention​

vMAJOR.MINOR.x              Arbeits-Linie                  v2.0.x
vMAJOR.MINOR.PATCH          gezielte Release-Vorbereitung  v2.0.1
v…-topic-suffix             Topic innerhalb einer Linie    v2.0.x-bonus-fix
develop | main              langlebige Branches (ausgenommen)

Neue Arbeits-Branches tragen immer Versions-Namen; die Ziel-Version wird vor der Branch-Anlage festgelegt. Der erste Commit auf einem neuen Versions-Branch bumpt die VERSION-Datei. In Claude-Code-Sessions wird die Konvention technisch erzwungen (Branch-Guard-Hook) und die Arbeits-Version bei jedem Session-Start angezeigt.

Release-Ablauf​

  1. Release-Check fahren (in Claude-Sessions: /release-check): Konsistenz VERSION ↔ Branch ↔ Changelog-Header ↔ Tag-frei, Working Tree clean, plus Qualitäts-Gates (composer lint:check mit geleertem PHPStan-Result-Cache, php artisan test, composer audit, npm run build).

  2. Changelog-Versions-Header setzen, committen, pushen.

  3. Maintainer taggt und pusht:

    git tag -a v2.0.0 -m "v2.0.0 — Laravel 13"
    git push origin v2.0.0

  4. Deploy (siehe Deployment), danach nächste Arbeits-Version festlegen → neuer vX.Y.x-Branch mit VERSION-Bump als erstem Commit.

Hotfixes​

Patch-Branch von main/Tag aus (z. B. v2.0.1), Fix + Test, Release-Check, Tag durch Maintainer — danach zurück in develop mergen.