diff --git a/.gitignore b/.gitignore index d63f107b95..952c3383a5 100644 --- a/.gitignore +++ b/.gitignore @@ -173,4 +173,6 @@ packages/sysutils/open-vm-tools/ #other docs/* +!docs/improvements.md +!docs/release-policy.md bench-results/config/mipi-generator/__pycache__/ diff --git a/docs/improvements.md b/docs/improvements.md new file mode 100644 index 0000000000..4594b4564b --- /dev/null +++ b/docs/improvements.md @@ -0,0 +1,144 @@ +# Melhorias e modernização + +Documento vivo. Lista componentes do ArchR que se beneficiam de modernização incremental: qualidade de código, integração com hardware atual (RK3326 / Mali-G31), manutenibilidade. Reescritas do zero ficam fora deste documento; quando o veredito for "vale reescrever", abrir doc próprio em `docs/rewrite-.md`. + +**Convenção de status:** +- `[ ]` não iniciado +- `[~]` em progresso +- `[x]` concluído +- `[?]` investigação aberta, decisão pendente + +**Convenção de esforço:** S (horas), M (dias), L (semanas), XL (mês ou mais). + +--- + +## 1. EmulationStation (emulationstation-next) + +**Repo:** `/media/disco-local/ArchR/emulationstation-next` +**Linguagem:** C++17, CMake 3.10+, SDL2. +**Hardware alvo primário:** R36S e clones (RK3326, Mali-G31, 1 GB DDR3L). + +**Veredito de reescrita:** descartado em 2026-06-23 (sessão dga.teles + Claude). 15+ anos de trabalho cumulativo, ecossistema de temas, scraper, gamelist XML, integração PortMaster e RetroAchievements: o custo de paridade básica supera de longe o ganho. Modernização incremental é o caminho. + +### 1.1. Qualidade de código + +- [ ] **Auditoria de C++17 vs C++20** S. Já estamos em C++17 via CMake. Avaliar bump para C++20 (concepts, ranges, designated initializers, span) ou ficar no 17. Decisão depende do gcc do toolchain do ArchR. +- [ ] **Substituir loops manuais por algoritmos da STL** M. Varredura em `es-core/src/utils/` e `es-app/src/views/`, onde `for` com índice ainda predomina. +- [ ] **Smart pointers consistentes** M. Há mistura de `new`/`delete` cru com `unique_ptr`/`shared_ptr`. Padronizar e remover `delete` manual onde possível. +- [ ] **`constexpr` e `noexcept` em utilitários puros** S. Funções de path, parsing, math em `es-core/utils/`. +- [ ] **Análise estática regular** S. Rodar `clang-tidy` com perfil mínimo (`modernize-*`, `performance-*`, `readability-*`) e arquivar relatório em `docs/es-clang-tidy-.txt`. +- [ ] **Remoção de código morto** S. O commit `563e1057f` (PackGamelists/BuildMultiDiskContentCache) sugere que ainda há referências obsoletas; varredura completa. + +### 1.2. Compatibilidade RK3326 / Mali-G31 + +- [ ] **Paths de renderização Panfrost vs libmali** M. Quando o seletor de GPU driver voltar (atualmente oculto, ver `project_panfrost_selector_disabled`), o ES precisa dar caminhos de fallback diferentes para texture upload e shader cache. Hoje assume libmali. +- [ ] **BO labelling** S. Os patches `0007..0010` do kernel 6.12-LTS habilitam labels em BOs do panfrost. ES pode anotar suas texturas e ajudar `panfrost_gem_show` no debug. Baixa prioridade, mas é literalmente uma chamada IOCTL. +- [ ] **CMA 96 MB awareness** M. Pré-alocação de texture pool consciente do limite (R36S tem 96 MB de CMA reservado). Logar quando se aproxima do limite e degradar graciosamente em vez de OOM. +- [ ] **Shader cache persistente** M. Mesa 26.1.3 já tem `MESA_SHADER_CACHE_DIR`. Garantir que o ES aponte para `/storage/.cache/mesa` (não `/tmp`, que é tmpfs) e que a pasta sobreviva ao boot. +- [ ] **CPU governor durante navegação de menu** S. Hoje subimos governor para `performance` antes de lançar emulador. Avaliar manter `schedutil` durante navegação para reduzir consumo passivo e calor. + +### 1.3. Performance percebida + +- [ ] **Profiling de boot time** M. Medir `ExecMainStart` até primeira tela interativa. Identificar onde os ~5 a 8 segundos de boot do ES vão (XML parse, texture load, scraper init). O commit `a2181ff44` já paralelizou parte; rever o gap restante. +- [ ] **Async load de capas e screenshots** M. Verificar se o load atual já é não-bloqueante e se não, paralelizar via ThreadPool (já existe no repo, ver commit `268ebb394`). +- [ ] **Decoding incremental de imagens grandes** S. Sistemas com gamelists pesadas (capas a 2K) pagam decoding síncrono na entrada. Stream + downscale on-the-fly. +- [ ] **Transições de view** S. Frame pacing nas transições com Mali-G31 às vezes engasga; checar se há frame drop em transições de carousel. + +### 1.4. Funcionalidades + +- [ ] **GPU governor menu** S. Já implementado em `4c3cb8af3` e `b9cb6b821`. Validar UX e documentar opções. +- [ ] **Integração com overlay generator** M. Botão dentro do ES que abre `arch-r.io/overlay-generator/` ou rode local. Reduz fricção para clones não catalogados. +- [ ] **Integração com Flasher para atualizar painel** M. Quando o usuário troca o cartão de painel, oferecer dentro do ES "atualizar overlay" sem reflash da SD. +- [ ] **Modo party / split-screen UI** L. Discutido informalmente; especificar antes. +- [ ] **Indicador de modo de gravação MIPI/SPKO** S. Para boards Soysauce, mostrar qual variant de áudio está ativo (debug útil). + +### 1.5. Build e dependências + +- [ ] **CMake 3.10 → 3.20+** S. Bump do mínimo. Toolchain do ArchR já está bem além. +- [ ] **Substituir FetchContent por submodules ou pkg-config** S. Predição: builds reproduzíveis e cache friendly. +- [ ] **SDL2 → SDL3** XL. SDL3 estável em 2025/2026. Migração não é blocker, mas vale levantar custo. Investigação aberta. +- [ ] **CI no GitHub Actions** M. Build matrix (debug + release, gcc + clang) por PR; hoje só roda local. +- [ ] **clang-format obrigatório** S. Adicionar `.clang-format` no repo e rodar via pre-commit hook. + +### 1.6. i18n e theming + +- [ ] **Auditoria de strings hardcoded** S. Garantir que tudo passa por `_("...")` ou equivalente. +- [ ] **Suporte a novo formato de tema** L. Avaliar adoção do tema engine do batocera-emulationstation ou ES-DE para herdar ecossistema maior. Investigação aberta. + +--- + +## 2. Arch-ificação da distro + +**Objetivo estratégico:** mover ArchR progressivamente para a filosofia Arch Linux (rolling, pacman-centric, FHS rigoroso, KISS) e deixar de ser uma variação ROCKNIX/LibreELEC. Nenhuma mudança aqui pode quebrar a experiência atual; tudo é incremental, com fallback para o caminho LibreELEC enquanto a paridade não estiver garantida. + +**Decisão arquitetural registrada (2026-06-23):** o modelo de boot herdado de LibreELEC (rootfs squashfs read-only + overlay `/storage` read-write + image-based atomic updates) **é decisão por design, não dívida técnica**. Não substituir. Motivos: +1. Sobrevive a power-loss arbitrário (criança puxando da tomada no meio do jogo), que é cenário diário em handheld. +2. Update atômico via swap de imagem é matematicamente impossível de deixar o sistema half-broken; pacman incremental, por design, pode. +3. `/storage` como overlay garante que upgrade de sistema nunca come saves nem configurações de emulador. +4. **Precedente validado:** SteamOS adotou exatamente esse modelo (rootfs read-only via OSTree, overlay `/home`, updates atômicos) e ainda assim é Arch Linux oficial com pacman e PKGBUILD plenamente funcionais. A arquitetura não define identidade de SO; userland, ferramentas e filosofia definem. + +Identidade Arch vem dos 7 itens desta seção (pacman, PKGBUILD, FHS, rolling, KISS, ArchWiki, branding), não da forma como o boot acontece. + +**Estado atual auditado (2026-06-23):** +- `pacman 7.0.0` já compilado em `projects/ArchR/packages/sysutils/pacman/` mas não está conectado ao fluxo de update do usuário final. +- `archr-keyring` já criado, populado com chaves Arch Linux ARM. +- `archr-update` ainda faz HTTP POST para `update.arch-r.io` e baixa imagem inteira (estilo LibreELEC overlay). +- 189 referências hardcoded a paths `/storage/...` em scripts (modelo overlay LibreELEC). FHS-puro seria `/etc`, `/var/lib`, `/home`. +- 809 arquivos com refs a `libreelec` (maioria headers de copyright; legítimo manter, ver 2.7). +- 8 arquivos com refs a `rocknix` em projects/ArchR: maioria é URL upstream ou crédito (legítimo); só 1 ou 2 são cosméticos. + +### 2.1. Wirar pacman como mecanismo de update real + +- [ ] **Subir mirror `repo.arch-r.io`** L. Hospedar `archr-core` (sistema base) e `archr-extra` (emuladores, temas, scrapers) como repos pacman. Sync via CI quando build de release sai. +- [ ] **Construir packages `.pkg.tar.zst` no pipeline de release** M. Hoje cuspimos `.img.gz`; passar a também produzir um pacote pacman por componente quando o build do package.mk concluir. Permite atualização granular. +- [ ] **Substituir `archr-update` por wrapper de `pacman -Syu`** M. Apenas para upgrades incrementais. Reservar image-based para upgrades grandes (kernel, mudança de major version) com migração assistida. +- [ ] **Suporte a `pacman -S `** M. Quando 2.1.1 e 2.1.2 estiverem ativos, o usuário pode instalar emuladores opcionais sem reflash. Reduz tamanho da imagem base. +- [ ] **Rollback via pacman cache** S. `/storage/.pacman/cache` já está reservado no package.mk; só falta UI no settings menu para "voltar para a release anterior". + +### 2.2. Aproximar do FHS + +- [ ] **Auditoria das 189 refs a `/storage/`** M. Categorizar: config de usuário, state runtime, save games, cache. Mapear cada categoria para o lugar FHS correto (`/home//.config`, `/var/lib`, `/var/cache`). +- [ ] **Symlinks de compatibilidade** S. Para cada migração, manter symlink `/storage/.config/` → caminho FHS por uma release, com warning no log, e remover depois. +- [ ] **Documentar o "porquê /storage"** S. Antes de mover, escrever página explicando que era herança LibreELEC overlay e o caminho atual. Vai para `docs/arch-migration.md`. + +### 2.3. Aceitar PKGBUILD da comunidade + +- [ ] **Diretório `archr-aur/` num repo separado** L. Espelho do AUR do Arch, mas com PKGBUILDs validados em RK3326. Build local via `makepkg` + chroot. +- [ ] **`makepkg.conf` próprio com flags do RK3326** S. Cortex-A35 não tem NEON 2.0 nem SVE; o flag set padrão do Arch ARM precisa de ajuste. Já temos `makepkg.conf` no package.mk do pacman; revisar conteúdo. +- [ ] **CI que builda PRs de PKGBUILD** M. GitHub Actions roda `makepkg --check --noconfirm` em PR; só merge se passa. + +### 2.4. Rolling release oficial + +- [x] **Decidir e documentar política de release** S. Definido em `docs/release-policy.md`: semver-RC mantido até v2.0 final, snapshots mensais `YYYY.MM.PATCH` a partir de v2.0. Canais `stable`/`next`/`dev` mapeiam direto para a variável `updates.branch` que `archr-update` já entende. +- [ ] **Servidor `update.arch-r.io` interpretando `BRANCH=stable|next|dev`** M. Cliente já manda; falta o backend retornar build correto por canal. +- [ ] **Versionamento `YYYY.MM.PATCH` ativado pós-v2.0** S. Tag git `vYYYY.MM.PATCH`. Mexer só depois que a v2.0 final sair. +- [ ] **GitHub Releases com tags `[Action Required]` / `[Action Recommended]` / `[News]`** S. Convenção documentada em `release-policy.md`. Tooling consumidor (Flasher, archr-update) pode parsear depois. + +### 2.5. KISS e remoção de inertia + +- [ ] **Auditoria de quirks de hardware mortas** M. `quirks.d/` herdou items de JELOS/ROCKNIX para devices que não suportamos. Marcar com `[ARCHIR-PRUNE-CANDIDATE]` e revisar em batch. +- [ ] **Splash + UX padrão** S. Splash atual ainda chama `rocknix-splash` antes do rename. Já corrigido no `archr-splash/package.mk` linha 13-14; validar e remover sed quando o upstream `rocknix-splash` virar fork puro. +- [ ] **Simplificar `runemu.sh`** L. 1500+ linhas com if/else de 30 emuladores. Refatorar em plugins (um arquivo por emulador). Item caro mas paga em manutenibilidade. + +### 2.6. Documentação no estilo ArchWiki + +- [ ] **Wiki em `wiki.arch-r.io`** L. Páginas no padrão ArchWiki: Installation guide, Troubleshooting, Beginner's guide. Markdown estático, sem PHP. +- [ ] **`man archr` na imagem** S. Página `man(7)` curta explicando os comandos próprios (`archr-update`, `archr-flasher`, scripts em `/usr/bin/archr-*`). +- [ ] **`/etc/archr-release`** S. Arquivo padrão Arch (`/etc/arch-release` na original) para que ferramentas de detecção de OS reconheçam ArchR como família Arch. + +### 2.7. Branding e copyright cleanup + +- [ ] **Copyright headers** S. Onde o arquivo é 100% nosso, header só "ArchR". Onde herdou de LibreELEC/JELOS/ROCKNIX, manter o credit upstream + "Modified for ArchR (2026-present)". Patch em batch. +- [ ] **`os-release` `ID=archr` e `ID_LIKE=arch`** S. Para que terceiros detectem como Arch family. Hoje `ID=archr` está OK, falta `ID_LIKE`. +- [ ] **Refs upstream legítimas** N/A. Manter como estão: URLs de fork (`rocknix/rockchip-wlroots`), copyright headers herdados, comentários explicativos. Não-issue. + +--- + +## Slots reservados (a preencher) + +- `## 3. archr-joypad` +- `## 4. archr-flasher` +- `## 5. archr-website` +- `## 6. Kernel + drivers (mali_kbase, mali-bifrost, mipi-generator)` + +Cada um ganha sua seção quando começarmos a auditoria. diff --git a/docs/release-policy.md b/docs/release-policy.md new file mode 100644 index 0000000000..6e46c07b5e --- /dev/null +++ b/docs/release-policy.md @@ -0,0 +1,82 @@ +# Política de release do ArchR + +Decisão registrada em 2026-06-23. Substituir este documento por edição direta quando a política mudar; nunca duplicar. + +## Resumo + +| Fase | Versionamento | Cadência | Quando muda | +|------|---------------|----------|-------------| +| Atual: pré-v2.0 | `vMAJOR.MINOR-rcN` (semver-RC) | sob demanda | RC5 vira 2.0 final | +| Pós-v2.0 | `YYYY.MM.patch` (Arch-style) | snapshot mensal | a partir de 2.0 | + +## Por que mudar só depois de 2.0 + +A v2.0 é um marco de identidade: nova arquitetura (`new-arch` branch), Arch-ificação inicial (`ID_LIKE=arch`, archr-release, archr(7), Mesa 26.1.3, kernel 6.12.94), Flasher v1.3.2 estável, catálogo de 44 painéis. Mudar versionamento *durante* o ciclo RC quebraria a expectativa de quem está acompanhando a sequência RC1..RC5 e tornaria a release final indistinguível de um snapshot de manutenção. + +Após 2.0, a v2.0 vira sentinel histórico e o sistema passa a ser efetivamente rolling. Versionar por data (Arch usa o mesmo modelo desde 2015) reflete melhor a realidade: cada snapshot é "o ArchR de junho de 2026", não "ArchR 2.1.7". + +## Canais de release + +| Canal | Conteúdo | Quem usa | +|-------|----------|----------| +| `stable` | snapshots mensais validados no R36S físico | usuário final | +| `next` | builds da branch `new-arch` (ou equivalente) após CI passar | testers, contribuidores | +| `dev` | builds noturnos de qualquer feature branch | mantenedores | + +A variável `updates.branch` em `system.cfg` já existe (ver `archr-update`) e mapeia diretamente para esses canais. O endpoint `update.arch-r.io` deve passar a entender esses três valores e devolver imagem correspondente. + +## Esquema de versionamento pós-v2.0 + +`YYYY.MM.PATCH` onde: + +- `YYYY.MM`: ano e mês do snapshot (zero-pad no mês, `2026.07` e não `2026.7`) +- `PATCH`: contador de hotfix dentro do mesmo mês, começando em `01`. Snapshot regular é sempre `.01`. Hotfix urgente (CVE, regressão crítica) vira `.02`, `.03` etc. + +Exemplos: +- `2026.07.01`: snapshot regular de julho. +- `2026.07.02`: hotfix dentro de julho. +- `2026.08.01`: próximo snapshot regular. + +Tag git `vYYYY.MM.PATCH` (com `v` prefixo, consistente com nossa convenção atual `v2.0-rc4`). + +## Cadência + +Snapshot regular **uma vez por mês**, alvo: primeiro fim de semana. Justificativa: + +- Mesa, kernel LTS e libretro cores liberam atualizações em ritmo mensal. +- Permite acumular testes do canal `next` antes de promover ao `stable`. +- Não sobrecarrega usuário com reflash semanal. +- Janela suficiente pra contribuidor testar uma feature antes de estabilizar. + +Hotfix sai quando necessário, sem cadência fixa. + +## archr-announce + +Lista pública de anúncios obrigatórios. Mecanismo de entrega: **GitHub Releases body + RSS público + canal pinned no Discord da comunidade**. Sem mailing list SMTP (custo de manutenção alto, baixo retorno na escala atual). + +### Convenção de tag no título da release + +Cada release no GitHub tem tag obrigatória no início do body: + +- `[Action Required]` exige passos manuais do usuário pós-update (ex.: re-pareamento de Bluetooth, migração de saves). +- `[Action Recommended]` é recomendação não-bloqueante (ex.: limpar cache antigo de shader). +- `[News]` é só anúncio, nenhuma ação. + +Tooling consumidor (Flasher, archr-update) pode parsear essa tag e mostrar banner correspondente. + +## Fluxo aprovado para subir um snapshot ao `stable` + +1. Build noturno do `dev` passa em CI por 7 dias consecutivos sem regressão. +2. Promove para `next`: anúncio na release com tag `[News]`, instala em pelo menos 3 devices físicos diferentes (R36S original + 1 clone + 1 Soysauce). +3. Permanece em `next` por no mínimo 7 dias com feedback dos testers. +4. Promove para `stable`: anúncio com tag apropriada (Action Required se houver migração). + +## Compatibilidade com `archr-update` existente + +`archr-update` atual já aceita `BRANCH` como variável de canal e faz POST para `update.arch-r.io`. Nenhuma mudança no cliente é necessária. O servidor precisa entender: + +- `BRANCH=stable` (default): retorna último `YYYY.MM.PATCH` validado. +- `BRANCH=next`: retorna último build da branch principal. +- `BRANCH=dev`: retorna último build noturno (com warning de instabilidade). + +Quando 2.1 (pacman como update real) estiver implementado, os canais migram naturalmente para repos pacman separados (`archr-core-stable`, `archr-core-next`, `archr-core-dev`).