# Como gerar uma nova versão no NPM

Pacote: [`automacao-core-playwright`](https://www.npmjs.com/package/automacao-core-playwright)

Publicar é um clique no GitHub Actions. Esta doc mostra o caminho completo:
onde clicar e o que acontece depois.

---

## O fluxo em uma olhada

```text
 1. PR aprovado          →  merge em develop
 2. Você, no Actions     →  Release > Run workflow > patch/minor/major
                                       │
                            ┌──────────┴──────────┐
 3. job "release"           │  versão + tag + release no GitHub
 4. job "Publish npm"       │  build + npm publish
                            └──────────┬──────────┘
 5. Pronto               →  versão no NPM, develop atualizada
```

Você só faz os passos 1 e 2. Do 3 em diante é o workflow.

---

## Passo 1 — Merge em `develop`

O Release publica o que está em `develop`. Mudança em PR aberto não entra na versão.

Confira se o **CI** de `develop` está verde — ele roda `npm ci`, `eslint` e
`rollup`. Se estiver vermelho, o Release vai quebrar no mesmo ponto.

---

## Passo 2 — Dispare o Release

Aba **Actions** → menu da esquerda, workflow **Release** → botão **`Run workflow`**:

| Campo | Valor |
| --- | --- |
| **Use workflow from** | `Branch: develop` |
| **Tipo de release (bump da versão)** | `patch`, `minor` ou `major` |

Clique em **`Run workflow`** (verde). O run aparece na lista em alguns segundos.

> Não confunda **Release** com **Publish** no menu da esquerda — os dois têm
> `Run workflow`. Para publicar uma versão nova é sempre o **Release**.
> O Publish é exceção, ver [Se o publish falhar](#se-o-publish-falhar).

### Escolhendo `patch`, `minor` ou `major`

**Quem usa a lib precisa mudar o código dele para atualizar?**

| Resposta | Opção | De `5.18.0` vira | Exemplos |
| --- | --- | --- | --- |
| Não, só está mais correto | `patch` | `5.18.1` | Correção de bug, ajuste de CI/build, bump de dependência |
| Não, mas ganha algo novo | `minor` | `5.19.0` | Novo helper/função, novo parâmetro **opcional** |
| **Sim** | `major` | `6.0.0` | Função removida/renomeada, assinatura alterada, parâmetro que virou obrigatório |

- Na dúvida entre `patch` e `minor`, escolha `minor`.
- `major` **não se decide sozinho** — alinhe com o time antes.

---

## Passos 3 e 4 — O que o workflow faz

Abra o run para acompanhar. São **dois jobs em sequência**; o segundo só começa
se o primeiro terminar bem.

**Job `release`** — sobe a versão em `package.json` e `package-lock.json`, fecha o
`CHANGELOG.md` (injeta versão/data e descarta as seções deixadas em `N/A.`),
faz merge em `main`, cria a tag `vX.Y.Z` e a Release no GitHub, e devolve para
`develop` a versão nova mais um bloco de changelog em branco para o próximo ciclo.

**Job `Publish npm`** — faz checkout da `main` já mergeada, `npm ci`, `npx rollup -c`
e `npm publish` autenticando com o secret `NPM_TOKEN`.

> **Por que o publish roda aqui dentro?** O push do job de release usa token de
> GitHub App, que não dispara eventos de `push`/`tag` — um workflow separado com
> `on: push tags` nunca acordaria.

---

## Passo 5 — Confirme

Os dois jobs verdes já indicam sucesso. Para checar no registry:

```bash
npm view automacao-core-playwright version   # leva ~1 min para propagar
```

E para consumir em outro projeto:

```bash
npm install automacao-core-playwright@latest
```

---

## Se o publish falhar

Cenário: **o job `release` passou (a tag existe no GitHub), mas o `Publish npm`
falhou** e o NPM continua na versão anterior.

**Não redispare o Release** — isso queimaria mais um número de versão. Use o
workflow **Publish**, que só publica:

Actions → **Publish** → `Run workflow` → campo **`Tag ou branch a publicar`**:
informe a tag exata (ex. `v5.18.0`) → `Run workflow`.

> O campo vem preenchido com `main`. Prefira a tag: ela é imutável e garante que
> você publica exatamente o que foi liberado.

---

## Problemas comuns

| Sintoma | O que fazer |
| --- | --- |
| Botão `Run workflow` não aparece | Falta permissão de escrita no repo. Ver [CODEOWNERS](CODEOWNERS) |
| Job `release` falhou no lint/build | Mesma causa de CI vermelho. Corrija em `develop` e dispare de novo — nenhuma versão foi perdida |
| `npm publish` falhou com `403` | Secret `NPM_TOKEN` expirado ou sem permissão. Renove e rode o Publish na tag |
| `cannot publish over the previously published version` | Já está publicada. Confira com `npm view`; se estiver lá, nada a fazer |
| Release saiu com "Nenhuma alteração informada" | O `CHANGELOG.md` não foi preenchido antes do merge — não impede a publicação. Se quiser a nota, edite a descrição da Release no GitHub |
| Publiquei o tipo errado (`patch` em vez de `minor`) | Não desfaça. Dispare novo Release com o tipo certo — versão no NPM é imutável e número pulado não causa problema |

---

## Os workflows do repositório

| Workflow | Quando roda | Para quê |
| --- | --- | --- |
| [CI](workflows/ci.yaml) | Automático, em push/PR de `develop` e `main` | `npm ci` + `eslint` + `rollup` |
| [Release](workflows/release.yaml) | Manual | Sobe versão, cria tag/release e **publica no NPM** |
| [Publish](workflows/publish.yaml) | Manual | Só publica. Exceção, ver [acima](#se-o-publish-falhar) |
