juraj-blahunka/release

Release simctlhouse

Publica a versão X.Y.Z deste repositório: um GitHub Release com o tarball notarizado e a fórmula no tap. scripts/release.sh faz o build, assinatura, notarização e empacotamento; esta skill cuida de todo o resto. docs/how-to.md ("Make a release") e D27 em docs/decisions.md explicam o design.

Nomes fixos:

O quê	Valor
Repositório GitHub	juraj-blahunka/simctlhouse (remote origin)
Checkout do tap	../homebrew-tap, GitHub juraj-blahunka/homebrew-tap, usado como juraj-blahunka/tap
Fórmula no tap	Formula/simctlhouse.rb
Tag	vX.Y.Z
Tarball	dist/simctlhouse-X.Y.Z-macos.tar.gz
Notas de release	dist/release-notes-X.Y.Z.md (dist/ é ignorado pelo git)

Execute todos os comandos a partir da raiz do repositório, a menos que uma etapa indique o contrário. Pare no primeiro erro, reporte o que falhou com sua saída e não contorne o problema (sem --skip-notarize, --allow-dirty, --force ou --no-verify).

1. Escolha a versão

Use a versão fornecida pelo usuário. Caso contrário, proponha uma e pergunte: liste as alterações desde a última tag com git log --oneline $(git describe --tags --abbrev=0 2>/dev/null)..HEAD (todos os commits se não houver tag), depois incremente a versão minor para commits feat: e patch apenas para correções.

2. Verifique as pré-condições

Verifique todas antes de alterar qualquer coisa e reporte todas as falhas de uma vez:

git rev-parse --abbrev-ref HEAD                  # main
git status --porcelain --untracked-files=no      # vazio
git fetch origin && git status -sb | head -1     # não atrás de origin/main
git ls-remote --tags origin "refs/tags/vX.Y.Z"   # vazio: a versão não foi lançada
gh auth status                                   # logado
git -C ../homebrew-tap status --porcelain        # tap existe e está limpo
git -C ../homebrew-tap pull --ff-only            # tap está atualizado

Se origin ou o tap estiver faltando, pare e informe ao usuário o que criar; nunca crie repositórios GitHub por conta própria. Um tap novo precisa do repositório GitHub juraj-blahunka/homebrew-tap, clonado em ../homebrew-tap, com um diretório Formula/.

3. Atualize a versão

Se version: em Sources/simctlhouse/SimctlHouse.swift não for X.Y.Z, altere-o, execute swift build e swift test, e faça commit apenas desse arquivo:

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

4. Escreva as notas de release com o usuário

Elabore as notas a partir do que mudou desde o ú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

Leia os commits e, quando o assunto não estiver claro, o próprio diff; as notas descrevem o que os usuários da CLI e da skill percebem, não como o código mudou.

• Comece com uma ou duas frases sobre o que é o release.

• Depois, seções, omitindo as vazias: ## Novo, ## Alterado, ## Corrigido e ## Breaking primeiro se algo quebrar scripts ou agentes (comandos ou flags renomeados, saída alterada, códigos de saída alterados).

• Um bullet por mudança, com o comando ou flag entre crases, ex.: simctlhouse skill install.

• Deixe de fora commits chore:, refactor:, test: e apenas de documentação, a menos que os usuários os notem.

• Termine com como obter, exatamente assim:

  ## Instalação
  
  ```sh
  brew install juraj-blahunka/tap/simctlhouse   # ou: brew upgrade simctlhouse
  simctlhouse skill install                     # uma vez, para vincular a skill do agente
  ```
  

Escreva o rascunho em dist/release-notes-X.Y.Z.md e mostre o texto completo ao usuário. Peça que ele aceite ou diga o que mudar; aplique as alterações ao arquivo e mostre o texto novamente. Repita até que ele aceite explicitamente e não prossiga para o build antes disso. O arquivo é publicado literalmente, portanto não deve conter nada direcionado ao usuário, como perguntas ou TODOs.

5. Faça o build do release

scripts/release.sh X.Y.Z

Leva alguns minutos, a maior parte esperando a notarização da Apple; permita até 10 minutos. Ele se recusa a executar em caso de incompatibilidade de versão, fontes não commitadas ou tag apontando para outro lugar, executa os testes e lint, faz o build através de scripts/build.sh, verifica que a Apple publicou o ticket de notarização e valida seu próprio tarball. Ele termina exibindo o caminho do tarball, seu sha256 e dist/simctlhouse.rb.

6. Teste o tarball (smoke test)

Execute os bytes exatos que você está prestes a publicar contra simuladores reais:

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

Ele descompacta o tarball em um diretório temporário, vincula a skill lá, adquire um dispositivo em um SIMCTLHOUSE_HOME descartável, verifica se o daemon iniciou e pode ser parado e iniciado novamente, libera o dispositivo e aguarda o daemon desligá-lo e sair por conta própria, exclui-o e verifica se todos os simuladores que existiam antes ainda existem. Uma primeira inicialização leva cerca de 30 segundos; permita até 5 minutos em uma máquina carregada. Se ele reportar simuladores ausentes, mostre a lista ao usuário: outros agentes podem ter excluído seus próprios dispositivos nesse meio tempo, e apenas o usuário pode informar.

7. Confirme antes de publicar

Tudo a partir daqui é público e difícil de desfazer. Mostre ao usuário a versão, o commit (git log --oneline -1), o sha256, o resultado do smoke test, o arquivo de notas de release aceito e as etapas abaixo, e aguarde uma autorização explícita.

8. Publique

Nesta ordem, para que cada etapa publicada aponte para algo que já 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

Verifique se o tarball enviado é o mesmo descrito pela fórmula; uma incompatibilidade significa que scripts/release.sh foi executado novamente após o upload:

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

Em seguida, publique a 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. Verifique via Homebrew

O push inicia o workflow tests do tap, que audita a fórmula, instala-a em máquinas macOS 15 e 26 limpas e executa seu bloco test. Essa é a única instalação real da fórmula publicada antes de os usuários a obterem, portanto aguarde que ela passe:

commit="$(git -C ../homebrew-tap rev-parse HEAD)"
gh run list --repo juraj-blahunka/homebrew-tap --commit "$commit" --json databaseId,url   # vazio por alguns segundos após o push
gh run watch <databaseId> --repo juraj-blahunka/homebrew-tap --exit-status

Depois, verifique a fórmula a partir desta máquina. O Homebrew se recusa a carregar fórmulas de um tap que ninguém confiou, mesmo para brew info, então confie nesta fórmula primeiro; isso altera a configuração do Homebrew do usuário, como brew install juraj-blahunka/tap/simctlhouse faria. O restante apenas lê e baixa; não 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            # mostra X.Y.Z
brew fetch --force juraj-blahunka/tap/simctlhouse   # baixa e verifica o sha256
brew audit --strict --online juraj-blahunka/tap/simctlhouse

Se o usuário já tiver o simctlhouse instalado a partir do tap, ofereça brew upgrade simctlhouse e depois simctlhouse --version e simctlhouse skill status.

10. Relate

Forneça ao usuário a URL do release (gh release view vX.Y.Z --repo juraj-blahunka/simctlhouse --json url -q .url), o commit do tap, a URL da execução bem-sucedida de tests, e o comando de instalação brew install juraj-blahunka/tap/simctlhouse.

Recuperação de um release com falha

• Falha antes da etapa 8: nada é público. Corrija a causa e recomece; reexecutar scripts/release.sh é seguro.
• Tag enviada, release ausente: execute a etapa gh release create novamente.
• Release criado, tap não atualizado: execute as etapas do tap novamente.
• A execução de tests do tap falha: mostre ao usuário o log da etapa que falhou (gh run view <databaseId> --repo juraj-blahunka/homebrew-tap --log-failed), porque os usuários que instalarem agora encontrarão a mesma falha. Corrija com um novo commit no tap; nunca force push no tap, pois o brew update dos usuários o puxa.
• Notas precisam de correção após a publicação: edite dist/release-notes-X.Y.Z.md com o usuário, depois gh release edit vX.Y.Z --repo juraj-blahunka/simctlhouse --notes-file dist/release-notes-X.Y.Z.md.
• Nunca reexecute scripts/release.sh para uma versão cujo tarball já foi enviado, porque cada build tem um novo sha256. Para substituir um upload defeituoso, pergunte primeiro ao usuário, depois gh release upload vX.Y.Z <tarball> --clobber com um novo build e publique a fórmula correspondente.
• Nunca exclua ou mova uma tag enviada ou um release publicado sem a aprovação explícita do usuário.