juraj-blahunka/release

simctlhouse veröffentlichen

Veröffentlicht die Version X.Y.Z dieses Repositorys: ein GitHub-Release mit der notarisierten Tarball-Datei und die Formel im Tap. scripts/release.sh erstellt den Build, signiert, notarisiert und packt; dieses Skill erledigt alles drumherum. docs/how-to.md („Ein Release erstellen“) und D27 in docs/decisions.md erklären das Design.

Feste Namen:

Was	Wert
GitHub-Repository	juraj-blahunka/simctlhouse (Remote origin)
Tap-Auscheckung	../homebrew-tap, GitHub juraj-blahunka/homebrew-tap, verwendet als juraj-blahunka/tap
Formel im Tap	Formula/simctlhouse.rb
Tag	vX.Y.Z
Tarball	dist/simctlhouse-X.Y.Z-macos.tar.gz
Release-Notes	dist/release-notes-X.Y.Z.md (dist/ wird von Git ignoriert)

Führen Sie jeden Befehl aus dem Repository-Stammverzeichnis aus, es sei denn, ein Schritt sagt etwas anderes. Stoppen Sie beim ersten Fehler, melden Sie den Fehler mit seiner Ausgabe und umgehen Sie ihn nicht (kein --skip-notarize, --allow-dirty, --force oder --no-verify).

1. Version auswählen

Verwenden Sie die vom Benutzer angegebene Version. Andernfalls schlagen Sie eine vor und fragen Sie: Listen Sie die Änderungen seit dem letzten Tag mit git log --oneline $(git describe --tags --abbrev=0 2>/dev/null)..HEAD auf (alle Commits, wenn es keinen Tag gibt), dann erhöhen Sie die Nebenversion für feat:-Commits und die Patch-Version nur für Fehlerbehebungen.

2. Vorbedingungen prüfen

Prüfen Sie alles, bevor Sie etwas ändern, und melden Sie jeden Fehler auf einmal:

git rev-parse --abbrev-ref HEAD                  # main
git status --porcelain --untracked-files=no      # leer
git fetch origin && git status -sb | head -1     # nicht hinter origin/main
git ls-remote --tags origin "refs/tags/vX.Y.Z"   # leer: die Version ist unveröffentlicht
gh auth status                                   # angemeldet
git -C ../homebrew-tap status --porcelain        # Tap existiert und ist sauber
git -C ../homebrew-tap pull --ff-only            # Tap ist auf dem neuesten Stand

Wenn origin oder der Tap fehlt, stoppen Sie und sagen Sie dem Benutzer, was er erstellen soll; erstellen Sie niemals selbst GitHub-Repositorys. Ein neuer Tap benötigt das GitHub-Repository juraj-blahunka/homebrew-tap, geklont nach ../homebrew-tap, mit einem Formula/-Verzeichnis.

3. Version erhöhen

Wenn version: in Sources/simctlhouse/SimctlHouse.swift nicht X.Y.Z ist, ändern Sie es dort, führen Sie swift build und swift test aus, und committen Sie nur diese Datei:

git commit -m "chore: release X.Y.Z" Sources/simctlhouse/SimctlHouse.swift

4. Release-Notes mit dem Benutzer schreiben

Entwerfen Sie die Notizen basierend auf den Änderungen seit dem letzten Release:

git log --format='%h %s%n%b' $(git describe --tags --abbrev=0 2>/dev/null)..HEAD
git diff --stat $(git describe --tags --abbrev=0 2>/dev/null)..HEAD

Lesen Sie die Commits und, wo ein Betreff unklar ist, den Diff selbst; die Notizen beschreiben, was Benutzer der CLI und des Skills bemerken, nicht wie sich der Code geändert hat.

• Beginnen Sie mit ein oder zwei Sätzen, worum es bei dem Release geht.

• Dann Abschnitte, wobei leere weggelassen werden: ## Neu, ## Geändert, ## Behoben und ## Breaking zuerst, wenn etwas Skripte oder Agents unterbricht (umbenannte Befehle oder Flags, geänderte Ausgabe, geänderte Exit-Codes).

• Ein Punkt pro Änderung, mit dem Befehl oder Flag in Backticks, z. B. simctlhouse skill install.

• Lassen Sie chore:, refactor:, test: und reine Dokumentations-Commits weg, es sei denn, Benutzer würden sie bemerken.

• Beenden Sie mit der Installationsanleitung, genau so:

  ## Installieren
  
  ```sh
  brew install juraj-blahunka/tap/simctlhouse   # oder: brew upgrade simctlhouse
  simctlhouse skill install                     # einmalig, um das Agent-Skill zu verknüpfen
  ```
  

Schreiben Sie den Entwurf in dist/release-notes-X.Y.Z.md und zeigen Sie dem Benutzer den vollständigen Text. Bitten Sie ihn, ihn zu akzeptieren oder zu sagen, was geändert werden soll; wenden Sie seine Änderungen auf die Datei an und zeigen Sie den gesamten Text erneut an. Wiederholen Sie dies, bis er ihn explizit akzeptiert, und fahren Sie erst dann mit dem Build fort. Die Datei wird wörtlich veröffentlicht, darf also nichts enthalten, das an den Benutzer gerichtet ist, wie Fragen oder TODOs.

5. Release erstellen

scripts/release.sh X.Y.Z

Es dauert einige Minuten, die meiste Zeit wartet das Skript auf die Notarisierung durch Apple; erlauben Sie bis zu 10 Minuten. Es weigert sich, bei einem Versionskonflikt, nicht committeten Quellen oder einem Tag, der woanders hin zeigt, ausgeführt zu werden, führt die Tests und Lint aus, erstellt über scripts/build.sh, prüft, ob Apple das Notarisierungs-Ticket veröffentlicht hat, und verifiziert seine eigene Tarball-Datei. Am Ende gibt es den Pfad der Tarball-Datei, ihren sha256 und dist/simctlhouse.rb aus.

6. Rauchtest der Tarball-Datei

Führen Sie die genauen Bytes, die Sie veröffentlichen werden, gegen echte Simulatoren aus:

scripts/smoke-test.sh dist/simctlhouse-X.Y.Z-macos.tar.gz

Es entpackt die Tarball-Datei in ein temporäres Verzeichnis, verknüpft das Skill dort, erwirbt ein Gerät in einem wegwerfbaren SIMCTLHOUSE_HOME, prüft, ob der Daemon gestartet wurde und gestoppt und wieder gestartet werden kann, gibt das Gerät frei und wartet, bis der Daemon es herunterfährt und von selbst beendet, löscht es und prüft, ob alle Simulatoren, die zuvor existierten, noch existieren. Ein erster Start dauert etwa 30 Sekunden; erlauben Sie bis zu 5 Minuten auf einer ausgelasteten Maschine. Wenn es fehlende Simulatoren meldet, zeigen Sie die Liste dem Benutzer: andere Agents könnten zwischenzeitlich ihre eigenen Geräte gelöscht haben, und nur der Benutzer kann das beurteilen.

7. Vor der Veröffentlichung bestätigen

Alles ab hier ist öffentlich und schwer rückgängig zu machen. Zeigen Sie dem Benutzer die Version, den Commit (git log --oneline -1), den sha256, das Ergebnis des Rauchtests, die akzeptierte Release-Notes-Datei und die folgenden Schritte und warten Sie auf eine explizite Zustimmung.

8. Veröffentlichen

In dieser Reihenfolge, damit jeder veröffentlichte Schritt auf etwas zeigt, das bereits existiert:

git push origin main
git tag -a vX.Y.Z -m "simctlhouse X.Y.Z"
git push origin vX.Y.Z
gh release create vX.Y.Z dist/simctlhouse-X.Y.Z-macos.tar.gz \
    --repo juraj-blahunka/simctlhouse --verify-tag --title "simctlhouse X.Y.Z" --notes-file dist/release-notes-X.Y.Z.md

Prüfen Sie, ob die hochgeladene Tarball-Datei diejenige ist, die die Formel beschreibt; eine Nichtübereinstimmung bedeutet, dass scripts/release.sh nach dem Upload erneut ausgeführt wurde:

gh release download vX.Y.Z --repo juraj-blahunka/simctlhouse --pattern '*.tar.gz' --output - | shasum -a 256
grep sha256 dist/simctlhouse.rb

Dann veröffentlichen Sie die Formel:

mkdir -p ../homebrew-tap/Formula
cp dist/simctlhouse.rb ../homebrew-tap/Formula/simctlhouse.rb
git -C ../homebrew-tap add Formula/simctlhouse.rb
git -C ../homebrew-tap commit -m "simctlhouse X.Y.Z"
git -C ../homebrew-tap push

9. Über Homebrew verifizieren

Der Push startet den tests-Workflow des Taps, der die Formel auditieren, auf sauberen macOS 15- und 26-Maschinen installieren und ihren test-Block ausführen soll. Das ist die einzige echte Installation der veröffentlichten Formel, bevor Benutzer sie erhalten, also warten Sie, bis sie bestanden ist:

commit="$(git -C ../homebrew-tap rev-parse HEAD)"
gh run list --repo juraj-blahunka/homebrew-tap --commit "$commit" --json databaseId,url   # einige Sekunden nach dem Push leer
gh run watch <databaseId> --repo juraj-blahunka/homebrew-tap --exit-status

Dann prüfen Sie die Formel von dieser Maschine aus. Homebrew weigert sich, Formeln aus einem Tap zu laden, dem niemand vertraut, selbst für brew info, also vertrauen Sie zuerst dieser einen Formel; das ändert die Homebrew-Konfiguration des Benutzers, wie es brew install juraj-blahunka/tap/simctlhouse tun würde. Der Rest liest und lädt nur herunter; es installiert nichts:

brew tap juraj-blahunka/tap 2>/dev/null; brew update
brew trust --formula juraj-blahunka/tap/simctlhouse
brew info juraj-blahunka/tap/simctlhouse            # zeigt X.Y.Z
brew fetch --force juraj-blahunka/tap/simctlhouse   # lädt herunter und prüft den sha256
brew audit --strict --online juraj-blahunka/tap/simctlhouse

Wenn der Benutzer bereits simctlhouse aus dem Tap installiert hat, bieten Sie brew upgrade simctlhouse und dann simctlhouse --version und simctlhouse skill status an.

10. Bericht

Geben Sie dem Benutzer die Release-URL (gh release view vX.Y.Z --repo juraj-blahunka/simctlhouse --json url -q .url), den Tap-Commit, die URL des bestandenen tests-Laufs und den Installationsbefehl brew install juraj-blahunka/tap/simctlhouse.

Wiederherstellung nach einem fehlgeschlagenen Release

• Fehler vor Schritt 8: nichts ist öffentlich. Beheben Sie die Ursache und beginnen Sie von vorne; scripts/release.sh erneut auszuführen ist in Ordnung.
• Tag gepusht, Release fehlt: führen Sie den Schritt gh release create erneut aus.
• Release erstellt, Tap nicht aktualisiert: führen Sie die Tap-Schritte erneut aus.
• Der tests-Lauf des Taps schlägt fehl: zeigen Sie dem Benutzer das Log des fehlgeschlagenen Schritts (gh run view <databaseId> --repo juraj-blahunka/homebrew-tap --log-failed), da Benutzer, die jetzt installieren, auf denselben Fehler stoßen. Beheben Sie vorwärts mit einem neuen Tap-Commit; führen Sie niemals einen Force-Push auf den Tap durch, da Benutzer' brew update ihn zieht.
• Notizen müssen nach der Veröffentlichung korrigiert werden: bearbeiten Sie dist/release-notes-X.Y.Z.md mit dem Benutzer, dann gh release edit vX.Y.Z --repo juraj-blahunka/simctlhouse --notes-file dist/release-notes-X.Y.Z.md.
• Führen Sie niemals scripts/release.sh für eine Version erneut aus, deren Tarball hochgeladen ist, da jeder Build einen neuen sha256 hat. Um einen fehlerhaften Upload zu ersetzen, fragen Sie zuerst den Benutzer, dann gh release upload vX.Y.Z <tarball> --clobber mit einem frischen Build und veröffentlichen Sie die passende Formel.
• Löschen oder verschieben Sie niemals einen gepushten Tag oder ein veröffentlichtes Release ohne die ausdrückliche Zustimmung des Benutzers.