From 9228fb1e29a3392c97e6cca48d4f28b8347f5608 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Thu, 9 Apr 2026 08:04:19 +0100 Subject: [PATCH] clean up --- ...0015-tilemap-empty-cell-vs-tile-id-zero.md | 110 ------------------ .../AGD-0017-jenkinsfile-correction.md | 49 -------- ...enkins-gitea-integration-and-relocation.md | 48 -------- .../DEC-0002-jenkinsfile-strategy.md | 52 --------- .../DEC-0003-jenkins-gitea-strategy.md | 48 -------- .../plans/PLN-0002-jenkinsfile-execution.md | 56 --------- .../plans/PLN-0003-jenkins-gitea-execution.md | 55 --------- 7 files changed, 418 deletions(-) delete mode 100644 discussion/workflow/agendas/AGD-0015-tilemap-empty-cell-vs-tile-id-zero.md delete mode 100644 discussion/workflow/agendas/AGD-0017-jenkinsfile-correction.md delete mode 100644 discussion/workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md delete mode 100644 discussion/workflow/decisions/DEC-0002-jenkinsfile-strategy.md delete mode 100644 discussion/workflow/decisions/DEC-0003-jenkins-gitea-strategy.md delete mode 100644 discussion/workflow/plans/PLN-0002-jenkinsfile-execution.md delete mode 100644 discussion/workflow/plans/PLN-0003-jenkins-gitea-execution.md diff --git a/discussion/workflow/agendas/AGD-0015-tilemap-empty-cell-vs-tile-id-zero.md b/discussion/workflow/agendas/AGD-0015-tilemap-empty-cell-vs-tile-id-zero.md deleted file mode 100644 index 4ee35336..00000000 --- a/discussion/workflow/agendas/AGD-0015-tilemap-empty-cell-vs-tile-id-zero.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -id: AGD-0015 -ticket: tilemap-empty-cell-vs-tile-id-zero -title: Tilemap Empty Cell vs Tile ID Zero -status: done -created: 2026-03-27 -resolved: 2026-04-09 -decision: Resolved during glyph implementation. -tags: [] ---- - -# Tilemap Empty Cell vs Tile ID Zero - -## Contexto - -O runtime hoje usa `tile.id == 0` como atalho para "tile ausente" no caminho de render de tilemap. - -Ao mesmo tempo, o contrato de `tile bank` em evolucao no packer quer permitir que `tile_id = 0` seja um tile real e valido dentro do bank. - -Isso cria conflito direto entre: - -- semantica atual do tilemap no runtime; -- e o contrato de packing/runtime asset bank que trata `tile_id` como indice valido do bank desde zero. - -## Problema - -Precisamos decidir qual e a semantica correta para representar ausencia de tile em tilemaps. - -Hoje o comportamento implicito e: - -- `tile.id == 0` significa "nao desenhar"; -- portanto o tile de indice `0` no bank fica inutilizavel no caminho de tilemap; -- sprites, por outro lado, nao carregam a mesma semantica implicita de vazio. - -Isso deixa o modelo inconsistente: - -1. o mesmo `tile_id` nao significa a mesma coisa em todos os consumidores; -2. o bank `TileBank` nao explicita reserva de `tile_id = 0`; -3. o packer teria que compensar uma regra de consumidor que nao esta modelada no contrato do asset bank. - -## Pontos Criticos - -- `tile_id` deve representar um indice valido no bank, nao um sentinel escondido, sempre que possivel; -- ausencia de tile e um conceito de tilemap/layer, nao necessariamente de bank asset; -- usar indices fora da faixa como sentinel tende a piorar validacao e debug; -- mudar o shape do tilemap pode ter custo de ABI/runtime, mas pode deixar o contrato mais honesto; -- manter o comportamento atual preserva compatibilidade local, mas cristaliza uma semantica implicita fraca. - -## Opcoes - -### Opcao A - Manter `tile.id == 0` como empty sentinel - -O runtime segue tratando `tile_id = 0` como ausencia de tile no tilemap. - -Consequencia: - -- o primeiro tile real do bank precisaria comecar em `1` para o caminho de tilemap; -- o packer precisaria compensar isso; -- sprites e tilemaps continuariam com semanticas diferentes para o mesmo id. - -### Opcao B - Tornar vazio explicito no tilemap model - -O tilemap passa a representar vazio explicitamente, por exemplo com: - -- `Option`; -- ou `Tile { active/present, ... }`. - -Consequencia: - -- `tile_id = 0` volta a ser um tile valido no bank; -- ausencia de tile deixa de depender de valor especial do id; -- o runtime fica semanticamente mais consistente. - -### Opcao C - Usar sentinel fora da faixa valida - -O tilemap passa a tratar um `tile_id >= tile_capacity` como "empty". - -Consequencia: - -- evita usar `0` como sentinel; -- mas cria acoplamento ruim entre tilemap e capacidade do bank; -- e torna a validacao mais fragil e menos didatica. - -## Sugestao / Recomendacao - -Adotar `Opcao B`. - -Ausencia de tile deve ser modelada explicitamente no tilemap/layer, e nao por um `tile_id` especial. - -Direcao recomendada: - -1. `tile_id` deve significar apenas "indice do tile no bank"; -2. `tile_id = 0` deve ser permitido como tile real; -3. tilemaps devem ter vazio explicito no proprio modelo; -4. o render do tilemap deve testar esse estado explicito, nao `tile.id == 0`. - -## Perguntas em Aberto - -1. Qual shape e melhor para o primeiro wave: - `Option` ou `Tile` com flag `active/present`? -2. Essa mudanca afeta apenas o tilemap path ou tambem deve harmonizar outros consumidores do modelo `Tile`? -3. Precisamos de estrategia de compatibilidade/migracao para codigo e testes que hoje assumem `tile.id == 0` como vazio? - -## Criterio para Encerrar - -Esta agenda pode ser encerrada quando houver decisao clara sobre: - -- como vazio e representado no tilemap; -- se `tile_id = 0` volta a ser indice valido universal do bank; -- e quais pontos de spec/codigo do runtime precisam de propagacao. diff --git a/discussion/workflow/agendas/AGD-0017-jenkinsfile-correction.md b/discussion/workflow/agendas/AGD-0017-jenkinsfile-correction.md deleted file mode 100644 index 3167d49c..00000000 --- a/discussion/workflow/agendas/AGD-0017-jenkinsfile-correction.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -id: AGD-0017 -ticket: jenkinsfile-correction -title: Agenda - Jenkinsfile Correction and Relocation -status: open -created: 2026-04-07 -resolved: -decision: -tags: ["ci", "jenkins", "infrastructure"] ---- - -# Agenda - Jenkinsfile Correction and Relocation - -## Contexto - -O projeto possui um `Jenkinsfile` localizado em `files/config/Jenkinsfile`. O conteúdo deste arquivo está básico e utiliza uma versão do Rust (`1.77`) que pode não ser a ideal em comparação com o resto do projeto que usa a versão estável definida em `rust-toolchain.toml`. Além disso, o pipeline de CI principal do projeto está definido no GitHub Actions e o comportamento esperado de CI (formatação, clippy, testes) também está documentado no `Makefile`. - -## Problema - -1. **Localização Não Convencional**: O `Jenkinsfile` na pasta `files/config/` dificulta a descoberta e manutenção, além de fugir do padrão do Jenkins de buscar o arquivo na raiz do repositório. -2. **Desalinhamento de Comandos**: O `Jenkinsfile` atual executa comandos de forma ligeiramente diferente do `Makefile` e do GitHub Actions (ex: `cargo fmt --all` vs `cargo fmt -- --check`). -3. **Falta de Padronização**: Não há garantias de que o pipeline do Jenkins execute as mesmas verificações de qualidade que o pipeline do GitHub. - -## Pontos Críticos - -- **Sincronia com o Makefile**: O `Jenkinsfile` deve idealmente delegar para o `Makefile` para evitar duplicidade de lógica de comandos. -- **Ambiente Docker**: A imagem Docker utilizada deve ser compatível com as ferramentas necessárias (ex: `make`, `cargo`). -- **Workspace Completo**: Deve garantir que todas as crates do workspace sejam testadas. - -## Opções - -1. **Manter como está**: Apenas corrigir o conteúdo no local atual. -2. **Mover para a raiz e atualizar**: Seguir o padrão de mercado movendo para a raiz e alinhando o conteúdo com o `Makefile`. -3. **Remover o Jenkinsfile**: Se o projeto foca apenas no GitHub Actions (como sugere o `dist-workspace.toml`), o Jenkinsfile pode ser redundante. Contudo, a solicitação explícita foi para corrigi-lo. - -## Sugestão / Recomendação - -**Opção 2**: Mover o `Jenkinsfile` para a raiz do projeto e atualizar seu conteúdo para utilizar o comando `make ci` definido no `Makefile`. Isso garante consistência entre o ambiente local, o Jenkins e o GitHub Actions. - -## Perguntas em Aberto - -- Existe alguma restrição técnica no ambiente Jenkins deste projeto que exija o arquivo em `files/config/`? (Assumindo que não, dada a solicitação de "corrigir"). -- A imagem Docker `rust:stable` (ou similar) possui as dependências necessárias para rodar o `Makefile`? - -## Criterio para Encerrar - -- O `Jenkinsfile` estar na raiz do projeto. -- O conteúdo refletir as mesmas etapas de validação do resto do projeto (fmt, clippy, test). -- O arquivo antigo em `files/config/` ter sido removido. diff --git a/discussion/workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md b/discussion/workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md deleted file mode 100644 index 3c0336a7..00000000 --- a/discussion/workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -id: AGD-0018 -ticket: jenkins-gitea-integration-and-relocation -title: Agenda - Jenkins Gitea Integration and Relocation -status: open -created: 2026-04-07 -resolved: -decision: -tags: ["ci", "jenkins", "gitea"] ---- - -# Agenda - Jenkins Gitea Integration and Relocation - -## Contexto - -Na sessão anterior, o `Jenkinsfile` foi movido para a raiz do repositório para seguir padrões comuns de mercado. No entanto, o usuário solicitou explicitamente que ele permaneça em `files/config/Jenkinsfile`. Além disso, a estratégia de CI mudou de GitHub Actions para Jenkins integrado ao Gitea. - -## Problema - -1. O local atual do `Jenkinsfile` (raiz no histórico, mas residindo em `files/config` no FS atual) precisa ser consolidado como `files/config/Jenkinsfile` para cumprir o requisito do usuário. -2. A integração do CI deve ser com o Gitea, exigindo a propagação de status dos commits. -3. Não deve haver dependência ou uso do GitHub CI para este projeto. - -## Pontos Críticos - -- **Sincronização de Status**: Garantir que o Jenkins envie o feedback de `make ci` (testes/lint) corretamente para o Gitea. -- **Localização não-padrão**: Jenkins precisa ser configurado no lado do servidor para buscar o script de pipeline em `files/config/Jenkinsfile` (o que é trivial, mas foge do padrão `Jenkinsfile` na raiz). -- **Abandono do GitHub CI**: Remover qualquer resquício de configuração voltada ao GitHub. - -## Opções - -1. **Opção A**: Manter na raiz (rejeitada pelo usuário). -2. **Opção B**: Manter em `files/config/Jenkinsfile` e usar o plugin de Gitea no Jenkins para notificação automática ou via `giteaStatus` no pipeline. - -## Sugestão / Recomendação - -Adotar a **Opção B**. Atualizar o `Jenkinsfile` para incluir blocos de `post` que notifiquem o Gitea sobre o sucesso ou falha do pipeline. - -## Perguntas em Aberto - -- O Jenkins em questão já tem o plugin do Gitea configurado? (Assumiremos que sim ou que o pipeline deve usar o comando padrão `giteaStatus`). -- Existem arquivos `.github/workflows` que devem ser removidos? (Verificar e remover). - -## Criterio para Encerrar - -- `Jenkinsfile` atualizado e testado localmente (validado sintaticamente). -- Documentação da decisão no framework. -- Localização confirmada em `files/config/Jenkinsfile`. diff --git a/discussion/workflow/decisions/DEC-0002-jenkinsfile-strategy.md b/discussion/workflow/decisions/DEC-0002-jenkinsfile-strategy.md deleted file mode 100644 index b2bbf1d6..00000000 --- a/discussion/workflow/decisions/DEC-0002-jenkinsfile-strategy.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -id: DEC-0002 -discussion: DSC-0019 -title: Decision - Jenkinsfile Location and Strategy -status: accepted -created: 2026-04-07 -resolved: -tags: ["ci", "jenkins"] ---- - -# Decision - Jenkinsfile Location and Strategy - -## Status - -Accepted. - -## Contexto - -O arquivo `Jenkinsfile` estava localizado em `files/config/Jenkinsfile`, o que dificultava a manutenção e automação via Jenkins (que por padrão busca na raiz). Além disso, o conteúdo estava divergente das definições de CI do `Makefile` e do GitHub Actions. - -## Decisao - -1. **Mover** o `Jenkinsfile` para a raiz do repositório. -2. **Atualizar** o conteúdo do `Jenkinsfile` para utilizar uma imagem Docker `rust:stable` (conforme `rust-toolchain.toml`). -3. **Delegar** a execução do pipeline para o comando `make ci` definido no `Makefile`. -4. **Remover** o arquivo residual em `files/config/Jenkinsfile`. - -## Rationale - -- **Padronização**: Seguir o padrão de mercado de manter o arquivo de configuração de pipeline na raiz. -- **DRY (Don't Repeat Yourself)**: Ao usar o `Makefile`, evitamos duplicar os comandos de `fmt`, `clippy` e `test` em múltiplos lugares (Makefile, GHA e Jenkins). -- **Consistência**: Garante que o desenvolvedor rodando `make ci` localmente tenha o mesmo resultado que o servidor de CI. - -## Invariantes / Contrato - -- O comando `make ci` deve sempre englobar as verificações mínimas de qualidade (format, clippy, tests). -- O `Jenkinsfile` deve sempre usar um ambiente que possua `make` e `rust`. - -## Impactos - -- **Jenkins**: A configuração do job no Jenkins pode precisar ser atualizada se o "Script Path" estiver explicitamente apontando para `files/config/Jenkinsfile`. (Geralmente aponta para `Jenkinsfile` na raiz). -- **Manutenção**: Facilita a manutenção, pois mudanças no processo de build só precisam ser feitas no `Makefile`. - -## Referencias - -- `.github/workflows/ci.yml` -- `Makefile` -- `rust-toolchain.toml` - -## Propagacao Necessaria - -- N/A. diff --git a/discussion/workflow/decisions/DEC-0003-jenkins-gitea-strategy.md b/discussion/workflow/decisions/DEC-0003-jenkins-gitea-strategy.md deleted file mode 100644 index d382c2c1..00000000 --- a/discussion/workflow/decisions/DEC-0003-jenkins-gitea-strategy.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -id: DEC-0003 -agenda: AGD-0018 -title: Decisão - Jenkins Gitea Integration and Relocation -status: accepted -created: 2026-04-07 -tags: ["ci", "jenkins", "gitea"] ---- - -# Decisão - Jenkins Gitea Integration and Relocation - -## Status - -Aceito. - -## Contexto - -O projeto deve utilizar Jenkins integrado ao Gitea para o pipeline de CI, ignorando o GitHub Actions. O arquivo `Jenkinsfile` deve residir em um local específico solicitado pelo usuário: `files/config/Jenkinsfile`. - -## Decisao - -1. **Localização**: O `Jenkinsfile` será mantido em `files/config/Jenkinsfile`. -2. **Integração Gitea**: O pipeline deve utilizar comandos compatíveis com o plugin do Gitea no Jenkins para propagar o status da execução (Success/Failure/Pending). -3. **Remoção de GitHub CI**: Qualquer configuração de `.github/workflows` relacionada ao CI será removida para evitar confusão. - -## Rationale - -- Cumpre o requisito direto do usuário sobre a localização do arquivo. -- Alinha a infraestrutura de CI com o servidor Git interno (Gitea). -- Centraliza a execução no `Makefile` (`make ci`) para manter o `Jenkinsfile` simples e portável. - -## Invariantes / Contrato - -- O `Jenkinsfile` deve sempre chamar `make ci` para garantir que o mesmo padrão de qualidade seja aplicado localmente e no CI. -- Notificações de status devem ser enviadas ao Gitea no início e no fim da execução. - -## Impactos - -- **Jenkins**: O job no Jenkins deve ser configurado para apontar o "Script Path" para `files/config/Jenkinsfile`. -- **Desenvolvedores**: Devem focar no Gitea para verificar o status dos builds. - -## Referencias - -- AGD-0018 - -## Propagacao Necessaria - -- Comunicar ao time de infraestrutura sobre o novo local do `Jenkinsfile` para ajuste no Job do Jenkins. diff --git a/discussion/workflow/plans/PLN-0002-jenkinsfile-execution.md b/discussion/workflow/plans/PLN-0002-jenkinsfile-execution.md deleted file mode 100644 index f415d321..00000000 --- a/discussion/workflow/plans/PLN-0002-jenkinsfile-execution.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -id: PLN-0002 -discussion: DSC-0019 -title: Plan - Jenkinsfile Relocation and Content Alignment -status: open -created: 2026-04-07 -resolved: -tags: ["ci", "jenkins"] ---- - -# Plan - Jenkinsfile Relocation and Content Alignment - -## Briefing - -Este plano descreve as etapas técnicas para mover o `Jenkinsfile` de sua localização atual para a raiz do repositório e atualizar seu conteúdo para delegar as tarefas de CI ao `Makefile`. - -## Decisions de Origem - -- DEC-0002: Jenkinsfile Location and Strategy - -## Alvo - -- `files/config/Jenkinsfile` (Remoção) -- `/Jenkinsfile` (Criação/Movimentação) - -## Escopo - -- Movimentação do arquivo no sistema de arquivos. -- Edição do conteúdo Groovy do Jenkinsfile. -- Validação básica da sintaxe. - -## Fora de Escopo - -- Configuração do servidor Jenkins externo. -- Criação de novos comandos no `Makefile` (usaremos o `make ci` existente). - -## Plano de Execucao - -1. Criar o novo `Jenkinsfile` na raiz com o conteúdo atualizado. -2. Remover o arquivo original em `files/config/Jenkinsfile`. -3. Validar se o `Makefile` está acessível no ambiente Docker especificado. - -## Criterios de Aceite - -- O arquivo `Jenkinsfile` deve existir na raiz. -- O arquivo `files/config/Jenkinsfile` não deve mais existir. -- O novo `Jenkinsfile` deve conter uma chamada para `make ci`. - -## Tests / Validacao - -- Verificar a existência dos arquivos via terminal. -- Simular a execução do comando `make ci` (opcional, já validado pelo GHA). - -## Riscos - -- **Quebra de Pipeline Existente**: Se o Jenkins estiver configurado para ler especificamente de `files/config/Jenkinsfile`, o pipeline quebrará até que a configuração do Job seja atualizada. (Risco baixo, pois o padrão é a raiz). diff --git a/discussion/workflow/plans/PLN-0003-jenkins-gitea-execution.md b/discussion/workflow/plans/PLN-0003-jenkins-gitea-execution.md deleted file mode 100644 index 5e74565c..00000000 --- a/discussion/workflow/plans/PLN-0003-jenkins-gitea-execution.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -id: PLN-0003 -decisions: ["DEC-0003"] -title: Plano de Execução - Jenkins Gitea Integration -status: open -created: 2026-04-07 ---- - -# Plano de Execução - Jenkins Gitea Integration - -## Briefing - -Atualizar o Jenkinsfile para integração com Gitea e garantir sua localização em `files/config/Jenkinsfile`. Remover resquícios de GitHub CI. - -## Decisions de Origem - -- DEC-0003 - -## Alvo - -- `files/config/Jenkinsfile` -- `.github/workflows/` (limpeza) - -## Escopo - -- Atualização do script Groovy do `Jenkinsfile` com suporte a `giteaStatus`. -- Garantir que o diretório `files/config` existe. -- Remover diretório `.github/workflows` se existir. - -## Fora de Escopo - -- Configuração real do servidor Jenkins (fora do repositório). - -## Plano de Execucao - -1. Verificar existência do diretório `files/config` e criar se necessário. -2. Atualizar/Mover o `Jenkinsfile` para `files/config/Jenkinsfile`. -3. Adicionar blocos `post` no `Jenkinsfile` para notificação ao Gitea. -4. Excluir `.github/workflows` se presente. -5. Validar sintaxe básica do Jenkinsfile. - -## Criterios de Aceite - -- O arquivo `Jenkinsfile` reside em `files/config/Jenkinsfile`. -- O conteúdo do `Jenkinsfile` inclui `make ci` e chamadas ao Gitea. -- Não existem workflows de GitHub CI. - -## Tests / Validacao - -- Execução manual de `make ci` para garantir que o comando base funciona. -- Verificação visual do `Jenkinsfile`. - -## Riscos - -- **Incompatibilidade de Plugin**: Se o Jenkins do usuário não tiver o plugin do Gitea, as chamadas `giteaStatus` podem falhar. No entanto, estamos seguindo o requisito de "propagar resultados para gitea".