Skip to content

Contribuir

PedroVMota edited this page Nov 13, 2026 · 1 revision

Contribuir

Antes de começar

  1. Leia a Arquitetura — em particular o modelo de threads e o replay de edições (Edit).
  2. Compile e corra os testes: Instalação e compilação.
  3. Tenha presentes as duas prioridades do projeto: desempenho (a UI nunca engasga) e segurança (sem unsafe, ficheiros = entrada hostil, sem rede).

Estilo de código

Regra Onde está definida
Rust stable, edição 2024 rust-toolchain.toml, Cargo.toml
rustfmt com max_width = 120 e use_small_heuristics = "Max" rustfmt.toml
Clippy pedantic como aviso e -D warnings no make lint Cargo.toml, Makefile
unwrap() / expect() só nos testes Cargo.toml (unwrap_used, expect_used), clippy.toml
#![forbid(unsafe_code)] em todos os crates cada lib.rs / main.rs
#[allow(...)] com reason = "..." quando é mesmo preciso convenção do código existente
Comentários e documentação do código em inglês; o README.md e esta wiki em português convenção do repositório

Princípios que o código segue:

  • Modelo validado: bw-core mantém as invariantes na construção, em cada edição e na desserialização. Uma edição nova deve ser um Edit aplicado por Circuit::apply, que valida tudo antes de mudar algo e devolve o que tocou (Applied), e tem de ser determinística (a UI e o simulador aplicam-na às suas cópias).
  • Nada de trabalho O(n) por frame ou por edição quando é evitável: atualize slots, redes e adjacências tocadas, não o circuito inteiro.
  • Entrada hostil: qualquer parser novo tem limites explícitos (tamanho, contagens, profundidade), não usa recursão sem limite, não reserva memória antes de verificar os bytes disponíveis e tem testes com dados malformados (e, idealmente, um alvo de fuzzing).
  • Nada da rede, nada executado. Dependências novas têm de passar a política do deny.toml (licenças permissivas, só crates.io).
  • Compatibilidade de ficheiros: mudar o formato implica subir a versão, manter a leitura das anteriores e gravar fixtures da versão antiga com o código anterior antes da mudança (ver Formato de ficheiros).
  • A biblioteca incluída e examples/macros-demo.bitwerk são gerados: altere o gerador em crates/bw-sim/tests/library.rs e regenere com BITWERK_REGEN_LIBRARY=1 cargo test -p bw-sim --test library.

Verificações antes de cada commit

make fmt          # formata
make lint         # clippy pedantic, -D warnings
make test         # todos os testes
make fuzz-check   # se mexeu em bw-io ou nos alvos de fuzzing
make audit        # se mexeu em dependências (requer cargo-deny)

Ou tudo de uma vez: make check-all (fmt-check + lint + test + audit).

Se a alteração toca no renderizador, no simulador ou na cena, meça também:

make bench
make sweep        # com o ecrã desbloqueado e a janela visível

e compare com os números de Desempenho. Uma corrida INVALID RUN não conta.

Mensagens de commit

O histórico usa mensagens curtas em inglês, no imperativo, a descrever a funcionalidade (por exemplo "Add macros, hierarchy navigation and the Parts Centre").

Repositório público

Não inclua caminhos absolutos da sua máquina, endereços de email ou outros dados pessoais em código, testes, fixtures ou documentação; use caminhos relativos ao repositório. Ficheiros de terceiros (como as fixtures do Digital Works) só entram sem alterações e com a licença num NOTICE.

Clone this wiki locally