dev/ajustments-asset-entry #12
@ -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<Tile>`;
|
||||
- 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<Tile>` 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.
|
||||
@ -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.
|
||||
@ -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`.
|
||||
@ -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.
|
||||
@ -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.
|
||||
@ -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).
|
||||
@ -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".
|
||||
Loading…
x
Reference in New Issue
Block a user