gugabfigueiredo/semver-howto

Was macht semver-howto?

Die gesamte Logik befindet sich in scripts/resolve-version.sh. Diese Datei teilt dem Agenten mit, wann er sie aufrufen soll und welche Regeln gelten. Sie leitet das Verfahren nicht erneut ab – lies die --help-Ausgabe des Skripts für Flags und seine Inline-Kommentare für den Algorithmus.

Wann aufrufen

• Nach einer Code-Änderung, wenn ein Versions-Tag vorgeschlagen werden muss.
• Wenn der Benutzer „tag this“ / „bump version“ / „what version?“ sagt.
• Von einem CI-Schritt, der die Tag-Auswahl an einen Agenten delegiert.

Nicht aufrufen für das Erstellen von Commit-Nachrichten oder die Generierung von Changelogs.

Regeln, die das Skript durchsetzt

1. Auswirkungsbereich: geänderte Pfade → git log -1 -- <paths> → git describe --match "*v*" <commit>. Erweitert niemals auf alle Tags in einem Monorepo.
2. Bump: feat: in Commits des Auswirkungsbereichs → Minor; sonst Patch. Major wird niemals autonom durchgeführt.
3. Kollision: Musterspezifisches git tag -l lokal, dann gezieltes git ls-remote --tags origin "refs/tags/<candidate>" für einen flachen Vorab-Check. Geht vorwärts durch bereits belegte Adressen.
4. Nur RC: Autonome Ausgabe ist immer -rc[n]. Saubere Tags werden abgelehnt.
5. Vorschlagen, nicht pushen: stdout = ein Tag. Der Mensch (oder ein Promotion-Workflow) führt die Mutation durch.

Verwendung

./skills/semver-howto/scripts/resolve-version.sh              # nächsten -rc[n] vorschlagen
./skills/semver-howto/scripts/resolve-version.sh --promote    # -rc vom höchsten RC entfernen
./skills/semver-howto/scripts/resolve-version.sh --paths "a b" # expliziten Auswirkungsbereich
./skills/semver-howto/scripts/resolve-version.sh --help       # Flags + Algorithmus-Hinweise

Exit 0 bei Erfolg. Ungleich null bei mehrdeutigem/unsicherem Zustand (Details auf stderr).

Leistung & Sicherheit

• git describe --match "<prefix>*v*" <commit> begrenzt den Tag-Durchlauf auf relevante Referenzen – kritisch bei Monorepos mit Tausenden von Modul-Tags.
• git tag -l "<pattern>" wird aus packed-refs bedient; O(matches), nicht O(history).
• git ls-remote --tags origin "refs/tags/<candidate>" fragt nach einer einzelnen Referenz. Kein Objekt-Fetch, kein FETCH_HEAD-Aufwand, typischerweise unter einer Sekunde selbst bei riesigen Remotes. Vermeidet git fetch --tags vollständig.
• Diff- und Log-Abfragen sind auf Pfade des Auswirkungsbereichs beschränkt, sodass jeder Lauf nur den relevanten Teil des Verlaufs berührt.
• Sicherheit: Nur RC-Schreibvorgänge, duale lokale+remote Kollisionsprüfung, kein Push, keine Major-Bumps, deterministischer Bootstrap (v0.1.0-rc1) wenn kein vorheriger Tag existiert – wird für menschliche Bestätigung auf stderr ausgegeben.