Contribuir

Release

Como uma versão é publicada no GitHub Releases e no npm, e por que só o mantenedor consegue publicar.

Uma tag v* dispara o workflow release.yml, que builda as quatro plataformas, publica o GitHub Release e envia o pacote npm para o staging do npm. A versão só fica disponível no npm depois que o mantenedor aprova com 2FA.

Atualize a versão e o changelog

Altere version em npm/package.json e mova os itens de “Não lançado” do CHANGELOG.md para a nova versão. Faça o commit na main.
Crie e envie a tag
```
git tag v0.2.0
git push origin v0.2.0
```
A tag precisa ser igual a v + version do npm/package.json: o workflow falha se não for. Só o mantenedor consegue criar tags v* (regra de tag do repositório).
Aguarde o workflow release.yml

Ele builda as quatro plataformas, gera o checksums.txt (SHA-256), publica o GitHub Release e, no job publish-npm, roda npm stage publish.
Aprove a versão no npm
```
npm stage list @gustavofsilva/kraa
npm stage approve <stage-id>
```
Ou pela página do pacote no npmjs.com. A aprovação pede 2FA.

Por que só o mantenedor publica

Camada	O que garante
Regra de tag no GitHub	Só o mantenedor cria, move ou apaga tags `v*`
Environment `npm` restrito a tags `v*`	A identidade OIDC do job de publicação só existe num release de verdade
Trusted publishing (OIDC)	O CI publica sem nenhum token guardado; a provenance é gerada automaticamente
Trusted publisher só com `npm stage publish`	Nada vai ao ar sem a aprovação com 2FA do mantenedor
“Require two-factor authentication and disallow tokens”	Nenhum token do npm consegue publicar o pacote
Actions fixadas por SHA, sem cache nos builds de release	Uma action ou um cache adulterado não entra no build
Releases imutáveis	Tag e binários publicados não podem ser trocados

Primeira publicação

O trusted publisher só pode ser configurado para um pacote que já existe. Por isso a primeira versão foi publicada à mão, com npm publish e 2FA, e o job publish-npm só roda quando a variável de repositório NPM_TRUSTED_PUBLISHING é true.

Assets do release

Asset	Plataforma
`kraa-darwin-universal.app.zip`	macOS (arm64 + x64, assinatura ad-hoc)
`kraa-windows-amd64.exe`	Windows x64
`kraa-linux-amd64`	Linux x64
`kraa-linux-arm64`	Linux arm64
`checksums.txt`	SHA-256 de todos os assets

Nomes são contrato

O instalador npm (npm/src/platform.ts) e os scripts scripts/install.sh e scripts/install.ps1 baixam por esses nomes. Mudar um nome no release.yml exige mudar lá também.

Versionamento

O projeto segue SemVer. Enquanto estiver em 0.x, mudanças incompatíveis na configuração ou na CLI podem acontecer em versões menores e ficam registradas no changelog.

Editar esta página