juraj-blahunka/release

Publier simctlhouse

Publie la version X.Y.Z de ce dépôt : une release GitHub avec l'archive notariée et la formule dans le tap. scripts/release.sh effectue la construction, la signature, la notarisation et l'empaquetage ; cette compétence gère tout ce qui l'entoure. docs/how-to.md ("Créer une release") et D27 dans docs/decisions.md expliquent la conception.

Noms fixes :

Quoi	Valeur
Dépôt GitHub	juraj-blahunka/simctlhouse (remote origin)
Checkout du tap	../homebrew-tap, GitHub juraj-blahunka/homebrew-tap, utilisé comme juraj-blahunka/tap
Formule dans le tap	Formula/simctlhouse.rb
Tag	vX.Y.Z
Archive	dist/simctlhouse-X.Y.Z-macos.tar.gz
Notes de version	dist/release-notes-X.Y.Z.md (dist/ est ignoré par git)

Exécutez chaque commande depuis la racine du dépôt sauf indication contraire. Arrêtez-vous à la première erreur, signalez ce qui a échoué avec sa sortie, et ne contournez pas l'erreur (pas de --skip-notarize, --allow-dirty, --force ou --no-verify).

1. Choisir la version

Utilisez la version donnée par l'utilisateur. Sinon, proposez-en une et demandez : listez les modifications depuis le dernier tag avec git log --oneline $(git describe --tags --abbrev=0 2>/dev/null)..HEAD (tous les commits s'il n'y a pas de tag), puis incrémentez la version mineure pour les commits feat: et la version de correction pour les corrections uniquement.

2. Vérifier les prérequis

Vérifiez tout cela avant de modifier quoi que ce soit, et signalez chaque échec d'un coup :

git rev-parse --abbrev-ref HEAD                  # main
git status --porcelain --untracked-files=no      # vide
git fetch origin && git status -sb | head -1     # pas en retard sur origin/main
git ls-remote --tags origin "refs/tags/vX.Y.Z"   # vide : la version n'est pas encore publiée
gh auth status                                   # connecté
git -C ../homebrew-tap status --porcelain        # le tap existe et est propre
git -C ../homebrew-tap pull --ff-only            # le tap est à jour

Si origin ou le tap est manquant, arrêtez-vous et dites à l'utilisateur ce qu'il faut créer ; ne créez jamais vous-même des dépôts GitHub. Un nouveau tap nécessite le dépôt GitHub juraj-blahunka/homebrew-tap, cloné dans ../homebrew-tap, avec un répertoire Formula/.

3. Incrémenter la version

Si version: dans Sources/simctlhouse/SimctlHouse.swift n'est pas X.Y.Z, modifiez-le, exécutez swift build et swift test, et commitez uniquement ce fichier :

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

4. Rédiger les notes de version avec l'utilisateur

Rédigez les notes à partir de ce qui a changé depuis la dernière publication :

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

Lisez les commits et, lorsqu'un sujet n'est pas clair, le diff lui-même ; les notes décrivent ce que les utilisateurs de l'interface en ligne de commande et de la compétence remarquent, pas comment le code a changé.

• Commencez par une ou deux phrases sur l'objet de la release.

• Ensuite, des sections, en omettant les vides : ## Nouveau, ## Modifié, ## Corrigé, et ## Breaking en premier si quelque chose casse des scripts ou des agents (commandes ou flags renommés, sortie modifiée, codes de sortie changés).

• Une puce par changement, avec la commande ou le flag entre backticks, ex. simctlhouse skill install.

• Laissez de côté les commits chore:, refactor:, test: et ceux qui ne concernent que la documentation, sauf si les utilisateurs les remarqueraient.

• Terminez par comment l'obtenir, exactement comme ceci :

  ## Installer
  
  ```sh
  brew install juraj-blahunka/tap/simctlhouse   # ou : brew upgrade simctlhouse
  simctlhouse skill install                     # une fois, pour lier la compétence de l'agent
  ```
  

Écrivez le projet dans dist/release-notes-X.Y.Z.md et montrez le texte complet à l'utilisateur. Demandez-lui d'accepter ou de dire ce qu'il faut changer ; appliquez ses modifications au fichier et montrez à nouveau le texte entier. Répétez jusqu'à ce qu'il accepte explicitement, et ne passez pas à la construction avant cela. Le fichier est publié textuellement, il ne doit donc rien contenir d'adressé à l'utilisateur, comme des questions ou des TODOs.

5. Construire la release

scripts/release.sh X.Y.Z

Cela prend quelques minutes, la plupart du temps d'attente pour la notarisation d'Apple ; prévoyez jusqu'à 10 minutes. Il refuse de s'exécuter en cas de non-correspondance de version, de sources non commitées, ou d'un tag pointant ailleurs, exécute les tests et le lint, construit via scripts/build.sh, vérifie qu'Apple a publié le ticket de notarisation, et vérifie sa propre archive. Il se termine en affichant le chemin de l'archive, son sha256, et dist/simctlhouse.rb.

6. Tester l'archive par fumée

Exécutez les octets exacts que vous allez publier contre de vrais simulateurs :

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

Il décompresse l'archive dans un répertoire temporaire, y lie la compétence, acquiert un appareil dans un SIMCTLHOUSE_HOME jetable, vérifie que le démon a démarré et peut être arrêté et redémarré, libère l'appareil et attend que le démon l'éteigne et se termine tout seul, le supprime, et vérifie que tous les simulateurs qui existaient avant existent toujours. Un premier démarrage prend environ 30 secondes ; prévoyez jusqu'à 5 minutes sur une machine chargée. S'il signale des simulateurs manquants, montrez la liste à l'utilisateur : d'autres agents ont peut-être supprimé leurs propres appareils entre-temps, et seul l'utilisateur peut le dire.

7. Confirmer avant de publier

Tout ce qui suit est public et difficile à annuler. Montrez à l'utilisateur la version, le commit (git log --oneline -1), le sha256, le résultat du test de fumée, le fichier de notes de version accepté, et les étapes ci-dessous, et attendez un feu vert explicite.

8. Publier

Dans cet ordre, pour que chaque étape publiée pointe vers quelque chose qui existe déjà :

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

Vérifiez que l'archive téléchargée est celle que la formule décrit ; une non-correspondance signifie que scripts/release.sh a été exécuté à nouveau après le téléchargement :

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

Puis publiez la formule :

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. Vérifier via Homebrew

Le push lance le workflow tests du tap, qui audite la formule, l'installe sur des machines macOS 15 et 26 propres, et exécute son bloc test. C'est la seule véritable installation de la formule publiée avant que les utilisateurs ne la reçoivent, alors attendez qu'elle réussisse :

commit="$(git -C ../homebrew-tap rev-parse HEAD)"
gh run list --repo juraj-blahunka/homebrew-tap --commit "$commit" --json databaseId,url   # vide pendant quelques secondes après le push
gh run watch <databaseId> --repo juraj-blahunka/homebrew-tap --exit-status

Ensuite, vérifiez la formule depuis cette machine. Homebrew refuse de charger des formules provenant d'un tap non approuvé, même pour brew info, alors approuvez d'abord cette formule uniquement ; cela modifie la configuration Homebrew de l'utilisateur, comme le ferait brew install juraj-blahunka/tap/simctlhouse. Le reste ne fait que lire et télécharger ; cela n'installe rien :

brew tap juraj-blahunka/tap 2>/dev/null; brew update
brew trust --formula juraj-blahunka/tap/simctlhouse
brew info juraj-blahunka/tap/simctlhouse            # affiche X.Y.Z
brew fetch --force juraj-blahunka/tap/simctlhouse   # télécharge et vérifie le sha256
brew audit --strict --online juraj-blahunka/tap/simctlhouse

Si l'utilisateur a déjà simctlhouse installé depuis le tap, proposez brew upgrade simctlhouse puis simctlhouse --version et simctlhouse skill status.

10. Rapporter

Donnez à l'utilisateur l'URL de la release (gh release view vX.Y.Z --repo juraj-blahunka/simctlhouse --json url -q .url), le commit du tap, l'URL de son exécution réussie des tests, et la commande d'installation brew install juraj-blahunka/tap/simctlhouse.

Récupération après un échec de publication

• Échec avant l'étape 8 : rien n'est public. Corrigez la cause et recommencez ; réexécuter scripts/release.sh est acceptable.
• Tag poussé, release manquante : exécutez à nouveau l'étape gh release create.
• Release créée, tap non mis à jour : exécutez à nouveau les étapes du tap.
• L'exécution des tests du tap échoue : montrez à l'utilisateur le journal de l'étape qui a échoué (gh run view <databaseId> --repo juraj-blahunka/homebrew-tap --log-failed), car les utilisateurs qui installent maintenant rencontrent la même erreur. Corrigez en avant avec un nouveau commit du tap ; ne forcez jamais le push du tap, car le brew update des utilisateurs le tire.
• Les notes doivent être corrigées après publication : modifiez dist/release-notes-X.Y.Z.md avec l'utilisateur, puis gh release edit vX.Y.Z --repo juraj-blahunka/simctlhouse --notes-file dist/release-notes-X.Y.Z.md.
• Ne réexécutez jamais scripts/release.sh pour une version dont l'archive est téléchargée, car chaque construction a un nouveau sha256. Pour remplacer un téléchargement défectueux, demandez d'abord à l'utilisateur, puis gh release upload vX.Y.Z <archive> --clobber avec une nouvelle construction et publiez la formule correspondante.
• Ne supprimez ni ne déplacez jamais un tag poussé ou une release publiée sans l'approbation explicite de l'utilisateur.