juraj-blahunka/release

Publicar simctlhouse

Publica la versión X.Y.Z de este repositorio: un release de GitHub con el tarball notarizado y la fórmula en el tap. scripts/release.sh realiza la compilación, firma, notarización y empaquetado; esta habilidad hace todo lo demás. docs/how-to.md ("Hacer un release") y D27 en docs/decisions.md explican el diseño.

Nombres fijos:

Qué	Valor
Repositorio de GitHub	juraj-blahunka/simctlhouse (remoto origin)
Clon del tap	../homebrew-tap, GitHub juraj-blahunka/homebrew-tap, usado como juraj-blahunka/tap
Fórmula en el tap	Formula/simctlhouse.rb
Tag	vX.Y.Z
Tarball	dist/simctlhouse-X.Y.Z-macos.tar.gz
Notas de publicación	dist/release-notes-X.Y.Z.md (dist/ es ignorado por git)

Ejecuta todos los comandos desde la raíz del repositorio a menos que un paso indique lo contrario. Detente ante el primer fallo, informa qué falló con su salida y no lo evites (sin --skip-notarize, --allow-dirty, --force ni --no-verify).

1. Elegir la versión

Usa la versión que haya dado el usuario. De lo contrario, propón una y pregunta: lista los cambios desde el último tag con git log --oneline $(git describe --tags --abbrev=0 2>/dev/null)..HEAD (todos los commits si no hay tag), luego incrementa la versión menor para commits feat: y la de parche solo para correcciones.

2. Verificar condiciones previas

Verifica todo esto antes de cambiar nada e informa de cada fallo de una vez:

git rev-parse --abbrev-ref HEAD                  # main
git status --porcelain --untracked-files=no      # vacío
git fetch origin && git status -sb | head -1     # no está detrás de origin/main
git ls-remote --tags origin "refs/tags/vX.Y.Z"   # vacío: la versión no se ha publicado
gh auth status                                   # autenticado
git -C ../homebrew-tap status --porcelain        # el tap existe y está limpio
git -C ../homebrew-tap pull --ff-only            # el tap está actualizado

Si falta origin o el tap, detente e indica al usuario qué debe crear; nunca crees repositorios de GitHub por tu cuenta. Un tap nuevo necesita el repositorio de GitHub juraj-blahunka/homebrew-tap, clonado en ../homebrew-tap, con un directorio Formula/.

3. Incrementar la versión

Si version: en Sources/simctlhouse/SimctlHouse.swift no es X.Y.Z, cámbialo allí, ejecuta swift build y swift test, y haz commit solo de ese archivo:

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

4. Redactar las notas de publicación con el usuario

Redacta las notas a partir de lo que cambió desde el último 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

Lee los commits y, cuando un asunto no sea claro, el diff mismo; las notas describen lo que notan los usuarios de la CLI y la habilidad, no cómo cambió el código.

• Empieza con una o dos frases sobre qué trata el release.

• Luego secciones, omitiendo las vacías: ## Nuevo, ## Cambiado, ## Corregido y primero ## Ruptura si algo rompe scripts o agentes (comandos o flags renombrados, salida cambiada, códigos de salida cambiados).

• Una viñeta por cambio, con el comando o flag entre backticks, p. ej. simctlhouse skill install.

• Omite los commits chore:, refactor:, test: y los solo de documentación a menos que los usuarios los noten.

• Termina con cómo obtenerlo, exactamente así:

  ## Instalar
  
  ```sh
  brew install juraj-blahunka/tap/simctlhouse   # o: brew upgrade simctlhouse
  simctlhouse skill install                     # una vez, para enlazar la habilidad del agente
  ```
  

Escribe el borrador en dist/release-notes-X.Y.Z.md y muéstrale al usuario el texto completo. Pídele que lo acepte o que diga qué cambiar; aplica sus cambios al archivo y vuelve a mostrar el texto completo. Repite hasta que lo acepte explícitamente y no continúes con la compilación antes de eso. El archivo se publica tal cual, por lo que no debe contener nada dirigido al usuario, como preguntas o TODOs.

5. Compilar el release

scripts/release.sh X.Y.Z

Tarda unos minutos, la mayor parte esperando la notarización de Apple; permite hasta 10 minutos. Se niega a ejecutarse si hay un desajuste de versión, fuentes sin commit o un tag que apunta a otro lado, ejecuta las pruebas y el linter, compila a través de scripts/build.sh, verifica que Apple haya publicado el ticket de notarización y valida su propio tarball. Termina imprimiendo la ruta del tarball, su sha256 y dist/simctlhouse.rb.

6. Prueba de humo del tarball

Ejecuta los bytes exactos que vas a publicar contra simuladores reales:

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

Descomprime el tarball en un directorio temporal, enlaza la habilidad allí, adquiere un dispositivo en un SIMCTLHOUSE_HOME desechable, verifica que el daemon se inició y se puede detener y volver a iniciar, libera el dispositivo y espera a que el daemon lo apague y salga por sí solo, lo elimina y verifica que todos los simuladores que existían antes todavía existen. Un primer arranque tarda unos 30 segundos; permite hasta 5 minutos en una máquina cargada. Si informa de simuladores faltantes, muéstrale la lista al usuario: otros agentes pueden haber eliminado sus propios dispositivos mientras tanto, y solo el usuario puede decirlo.

7. Confirmar antes de publicar

Todo a partir de aquí es público y difícil de deshacer. Muéstrale al usuario la versión, el commit (git log --oneline -1), el sha256, el resultado de la prueba de humo, el archivo de notas de publicación aceptado y los pasos siguientes, y espera una autorización explícita.

8. Publicar

En este orden, para que cada paso publicado apunte a algo que ya existe:

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

Verifica que el tarball subido es el que describe la fórmula; un desajuste significa que scripts/release.sh se ejecutó de nuevo después de la subida:

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

Luego publica la fórmula:

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. Verificar a través de Homebrew

El push inicia el workflow tests del tap, que audita la fórmula, la instala en máquinas macOS 15 y 26 limpias y ejecuta su bloque test. Esa es la única instalación real de la fórmula publicada antes de que los usuarios la obtengan, así que espera a que pase:

commit="$(git -C ../homebrew-tap rev-parse HEAD)"
gh run list --repo juraj-blahunka/homebrew-tap --commit "$commit" --json databaseId,url   # vacío durante unos segundos tras el push
gh run watch <databaseId> --repo juraj-blahunka/homebrew-tap --exit-status

Luego verifica la fórmula desde esta máquina. Homebrew se niega a cargar fórmulas de un tap que nadie ha confiado, incluso para brew info, así que primero confía en esta única fórmula; eso cambia la configuración de Homebrew del usuario, como lo haría brew install juraj-blahunka/tap/simctlhouse. El resto solo lee y descarga; no instala nada:

brew tap juraj-blahunka/tap 2>/dev/null; brew update
brew trust --formula juraj-blahunka/tap/simctlhouse
brew info juraj-blahunka/tap/simctlhouse            # muestra X.Y.Z
brew fetch --force juraj-blahunka/tap/simctlhouse   # descarga y verifica el sha256
brew audit --strict --online juraj-blahunka/tap/simctlhouse

Si el usuario ya tiene simctlhouse instalado desde el tap, ofrécele brew upgrade simctlhouse y luego simctlhouse --version y simctlhouse skill status.

10. Informar

Dale al usuario la URL del release (gh release view vX.Y.Z --repo juraj-blahunka/simctlhouse --json url -q .url), el commit del tap, la URL de su ejecución de tests exitosa y el comando de instalación brew install juraj-blahunka/tap/simctlhouse.

Recuperación de un release fallido

• Falla antes del paso 8: nada es público. Corrige la causa y vuelve a empezar; volver a ejecutar scripts/release.sh está bien.
• Tag subido, release faltante: ejecuta el paso gh release create de nuevo.
• Release creado, tap no actualizado: vuelve a ejecutar los pasos del tap.
• La ejecución de tests del tap falla: muéstrale al usuario el registro del paso fallido (gh run view <databaseId> --repo juraj-blahunka/homebrew-tap --log-failed), porque los usuarios que instalen ahora se encontrarán con el mismo fallo. Corrige hacia adelante con un nuevo commit del tap; nunca hagas force-push al tap, ya que los usuarios lo obtienen mediante brew update.
• Las notas necesitan corrección después de publicar: edita dist/release-notes-X.Y.Z.md con el usuario, luego gh release edit vX.Y.Z --repo juraj-blahunka/simctlhouse --notes-file dist/release-notes-X.Y.Z.md.
• Nunca vuelvas a ejecutar scripts/release.sh para una versión cuyo tarball ya se haya subido, porque cada compilación tiene un nuevo sha256. Para reemplazar una subida defectuosa, primero pregunta al usuario, luego gh release upload vX.Y.Z <tarball> --clobber con una compilación nueva y publica la fórmula correspondiente.
• Nunca elimines ni muevas un tag ya subido o un release publicado sin la aprobación explícita del usuario.