diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..d9530b7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,36 @@ +--- +name: Relato de bug +about: Relate um problema para ajudar a corrigi-lo. +title: "" +--- + +## Descrição + + + +## Como reproduzir + +1. Primeiro passo +2. Segundo passo +3. Terceiro passo + +## Resultado esperado + + + +## Resultado observado + + + +## Ambiente + +- Versão do RetroX: +- Versão do macOS: +- Arquitetura: Apple Silicon ou Intel +- Emulador e versão, se aplicável: + +## Informações adicionais + + + + diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..5d188e1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,23 @@ +--- +name: Sugestão de melhoria +about: Proponha uma funcionalidade ou melhoria para o RetroX. +title: "" +--- + +## Problema ou necessidade + + + +## Solução proposta + + + +## Critérios de aceitação + + + +- [ ] Resultado esperado + +## Alternativas e contexto + + diff --git a/.github/PULL_REQUEST_TEMPLATE/beta_release.md b/.github/PULL_REQUEST_TEMPLATE/beta_release.md new file mode 100644 index 0000000..9fb9e09 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/beta_release.md @@ -0,0 +1,23 @@ +## Beta release + + + +## O que está incluído + + + +## Validação + + + +## Riscos e pendências + + + +## Checklist + +- [ ] A branch de origem é `ci/beta` e o destino é `main`. +- [ ] As alterações foram testadas e os resultados estão registrados acima. +- [ ] O workflow **Testes** está verde. +- [ ] A mensagem do commit de squash segue Conventional Commits e reflete o tipo de release desejado. +- [ ] A mudança foi aprovada por um revisor. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index d9655d5..abc8b39 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,3 +1,5 @@ +> O alvo deste PR deve ser a branch `beta`. + ## O que muda e por quê diff --git a/.github/workflows/ci-release.yml b/.github/workflows/ci-release.yml index b0f2e05..b4a9da9 100644 --- a/.github/workflows/ci-release.yml +++ b/.github/workflows/ci-release.yml @@ -2,7 +2,7 @@ name: Publicar release on: push: - branches: [main] + branches: [main, beta] permissions: contents: read diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 7421d31..cb46fad 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -3,7 +3,7 @@ name: Testes on: pull_request: push: - branches-ignore: [main] + branches-ignore: [main, beta] workflow_dispatch: workflow_call: diff --git a/.releaserc.json b/.releaserc.json index f892bf4..d071145 100644 --- a/.releaserc.json +++ b/.releaserc.json @@ -1,5 +1,5 @@ { - "branches": ["main"], + "branches": ["main", { "name": "beta", "prerelease": true }], "plugins": [ ["@semantic-release/commit-analyzer", { "releaseRules": [ diff --git a/AGENTS.md b/AGENTS.md index 84f95e5..2c527c5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,25 +32,60 @@ application UI from reusable core functionality. ## Git Workflow -The project uses GitHub Flow. `main` is always releasable and protected. +Two long-lived, protected branches: -1. Never commit or push directly to `main`. -2. Branch from an up-to-date `main`. Name branches `/` +- `beta`: where changes land first. Every merge publishes a pre-release + (`1.2.0-beta.1`, `1.2.0-beta.2`, ...). +- `main`: stable. Only receives promotions from `beta` and urgent hotfixes. + Every merge may publish a stable release. + +Rules: + +1. Never commit or push directly to `main` or `beta`. +2. Branch from an up-to-date `beta`. Name branches `/` with the same types as commits: `feat/`, `fix/`, `chore/`, `docs/`, `refactor/`, `test/`, `ci/`. 3. Keep branches short-lived and focused on one change. -4. Open a pull request to `main`. Required: CI (workflow "Testes") green. -5. PRs are merged with **squash merge** only. The PR title becomes the commit - on `main`, so it must be a valid Conventional Commit, in Portuguese: - `feat(biblioteca): detecta capas do Azahar`. +4. Open a pull request to `beta`. Required: CI (workflow "Testes") green. + Contributions from forks follow the same rule. +5. All PRs, including `beta` -> `main`, are merged with **squash merge**. The + PR title becomes the commit, so it must be a valid Conventional Commit, in + Portuguese: `feat(biblioteca): detecta capas do Azahar`. 6. Delete the branch after merge. -7. Never merge without human approval, never force-push `main`, never skip - hooks or CI. +7. Never merge without human approval, never force-push `main` or `beta`, + never skip hooks or CI. + +### Promoting to stable + +A stable release happens when a PR `beta` -> `main` is squash merged, after the +pre-release was tested. Never open it without being asked. + +Because the squash commit is the only commit semantic-release reads on `main`: + +- The title is a Conventional Commit whose **type matches the highest-impact + change** being promoted: `feat` if any feature, otherwise `fix` (or `chore`). + Example: `feat: novo tema Rayo Paradise e capas do Azahar`. +- If any promoted change has a `BREAKING CHANGE`, repeat it as a + `BREAKING CHANGE: ` footer in the PR description, which becomes + the commit body. +- The squash commit message must use "pull request title and description". +- Right after the merge, merge `main` back into `beta`. Without this, the + promoted commits are not ancestors of `main` and the next promotion PR + conflicts or lists them again. + +### Exceptions to go straight to `main` + +- Urgent hotfixes (`fix/`), branched from `main`. +- Changes that do not publish a version and do not touch app behavior + (`docs`, `ci`). + +After any change merged straight into `main`, merge `main` back into `beta` +to keep the branches in sync. ### Commits and versions -semantic-release publishes a release on every merge to `main`, using the -rules in `.releaserc.json`: +semantic-release publishes a release on every merge to `beta` (pre-release) +and `main` (stable), using the rules in `.releaserc.json`: | Commit type | Release | | --- | --- | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3eec4c4..03e9cb9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,28 +42,36 @@ detalhes, e a resposta vem o quanto antes. ### Fluxo de branches -O projeto usa **GitHub Flow**: a `main` está sempre pronta para release e é protegida. Todo trabalho -entra por pull request, vindo de uma branch curta (ou de um fork) criada a partir da `main`. +O projeto tem duas branches protegidas: + +- **`beta`**: onde toda mudança entra primeiro. Cada merge publica uma pré-release + (`1.2.0-beta.1`, `1.2.0-beta.2`…), marcada como *pre-release* no GitHub e fora do link "última versão". +- **`main`**: a versão estável. Só recebe a promoção da `beta` e correções urgentes. + +**Todo pull request, inclusive de forks, vai para a `beta`.** Se você abrir contra a `main` por engano, +o mantenedor muda o alvo. - Nome da branch: `/`, com os mesmos tipos dos commits. -- O PR exige o CI verde e é integrado com **squash merge**. O título do PR vira o commit na `main`, +- O PR exige o CI verde e é integrado com **squash merge**. O título do PR vira o commit na `beta`, então ele precisa seguir o padrão de commits abaixo. -- Cada merge pode publicar uma release (veja [Releases](#releases)); por isso, agrupe mudanças - relacionadas num PR só. - Depois do merge, a branch é apagada. +- A versão estável sai quando o mantenedor integra a `beta` na `main`, também por **squash merge**. O + título desse PR é o commit que define a versão, então usa o tipo da mudança mais relevante + (`feat: novo tema e capas do Azahar`), e um `BREAKING CHANGE:` vai na descrição. Em seguida, a `main` é + integrada de volta na `beta`; o mesmo vale depois de qualquer mudança direto na `main`. ### Enviando código por fork e pull request 1. Faça um **fork** do repositório e clone o seu fork. -2. Crie uma branch a partir da `main`, com um nome que descreva a mudança: +2. Crie uma branch a partir da `beta`, com um nome que descreva a mudança: `feat/dolphin-adapter`, `fix/scan-capas`, `docs/readme`. 3. Faça a mudança (veja as regras abaixo) e rode as verificações. -4. Envie a branch para o seu fork e abra um **pull request** para a `main` deste repositório. +4. Envie a branch para o seu fork e abra um **pull request** para a `beta` deste repositório. 5. Descreva o que mudou e por quê, e ligue a issue relacionada (`Closes #123`). 6. Responda aos comentários da revisão. Se pedirem ajustes, adicione commits à mesma branch. Pull requests de primeira vez passam pelo CI (workflow **Testes**). Ele precisa estar verde para o -merge. Ninguém faz push direto na `main`; todo merge passa por revisão. +merge. Ninguém faz push direto na `main` nem na `beta`; todo merge passa por revisão. ## Ambiente de desenvolvimento @@ -112,8 +120,8 @@ O `!` depois do tipo não é reconhecido. ## Releases -O workflow **Testes** roda em pull requests, em pushes para branches fora de `main` e sob demanda. -O workflow de release reutiliza esses testes no commit enviado a `main`; depois deles, o +O workflow **Testes** roda em pull requests, em pushes para branches fora de `main` e `beta` e sob demanda. +O workflow de release reutiliza esses testes no commit enviado a `main` ou `beta`; depois deles, o semantic-release lê os commits, cria a tag e publica uma GitHub Release com o ZIP do `RetroX.app` (Apple Silicon) e o SHA-256. As regras de versão estão em `.releaserc.json`: diff --git a/docs/DECISOES.md b/docs/DECISOES.md index 72f235a..254e81e 100644 --- a/docs/DECISOES.md +++ b/docs/DECISOES.md @@ -27,7 +27,8 @@ Decisões do usuário e suposições de trabalho que não cabem num ADR. Decisõ | D14 | Abertura animada ao iniciar e transições suaves entre telas, inspiradas na fluidez do iiSU, com identidade própria. | | D15 | Marca do RetroX: a personagem **Rayo** (tile do ícone) e o nome com o "X" na cor de destaque, alinhados pela altura das maiúsculas. Substitui o R geométrico (conceito C). Kit e regras em `docs/design/logo/README.md`, gerados por `scripts/brand-kit.swift`. | | D16 | Código sob GPL-3.0; a marca (Rayo, logo, ícone e os nomes RetroX e Rayo) fica fora da licença, com todos os direitos reservados (2026-10-28). Regras em `BRAND.md`; contribuições por fork e PR em `CONTRIBUTING.md`. | -| D17 | Fluxo de branches: GitHub Flow. `main` protegida e sempre liberável; branches curtas `/`; PR com CI verde e squash merge, cujo título é um Conventional Commit. Cada merge pode publicar uma release (semantic-release, regras em `.releaserc.json`). Sem `develop` nem nightly por ora; canal `next` fica como opção. Regras para agentes em `AGENTS.md`. | +| D17 | Fluxo de branches: duas branches protegidas, `beta` (entrada de todas as mudanças, pré-releases) e `main` (estável). Branches curtas `/`; PR com CI verde e squash merge, cujo título é um Conventional Commit. Sem `develop` nem nightly. Regras para agentes em `AGENTS.md`. | +| D18 | Pré-releases na branch `beta` (semantic-release, `prerelease: true`), versões `X.Y.Z-beta.N`. Todo PR, inclusive de forks, vai para a `beta`; a `main` recebe só a promoção `beta` -> `main` (PR com squash, título com o tipo da mudança mais relevante; depois a `main` é integrada de volta na `beta`) e hotfixes. `docs` e `ci` podem ir direto à `main`, com a `main` integrada de volta na `beta`. Nome `beta` coincide com o sufixo da versão e a convenção do semantic-release. | ## Suposições de trabalho