Desenvolvimento

Documentação · English

Encontre a camada responsável

Leia a arquitetura e o mapa do código antes de alterar fluxos entre domínios. Os arquivos services.py concentram autorização, validação e persistência. Views traduzem requisições/respostas HTTP; consumers WebSocket traduzem mensagens recebidas, enquanto o despacho em tempo real publica alterações confirmadas. Mantenha regras nos serviços para que entradas Python e do navegador compartilhem as verificações.

Use a API pública ao integrar com o núcleo. Um contexto Python identifica o chamador, mas não concede autorização. Escritas diretas no ORM servem para migrações/fixtures controladas; no fluxo normal podem ignorar permissões, revisões, limpeza de arquivos e notificações dos serviços.

Em mutações, confira as convenções de transação, ID de requisição e versão esperada. Preserve o comportamento de repetição e publique estado confirmado. Snapshots para jogadores e transmissão devem excluir dados ocultos no servidor, sem depender apenas de escondê-los no DOM.

Fluxo comum

uv sync --locked
uv run --locked python main.py

Edite o serviço responsável e suas views/templates/frontend conforme necessário. Crie teste de regressão para a regra ou o limite alterado e execute as suítes pertinentes. Alterações apenas documentais geralmente precisam de revisão de links/exemplos e verificações focadas, sem novos testes que repitam o texto.

Para mudanças de modelos:

uv run --locked python manage.py makemigrations
uv run --locked python manage.py migrate
uv run --locked python manage.py makemigrations --check --dry-run

Revise migrações geradas antes de aplicá-las a dados importantes. Labels de apps e nomes de modelos também participam dos arquivos portáveis de campanha. Uma mudança de esquema pode exigir testes de importação/exportação e snapshots além dos testes de modelos.

Contratos e recursos do navegador

O registro do navegador é gerado de gravewright/modules/contracts/frontend.json:

uv run --locked python scripts/generate_frontend_api.py

Inclua no mesmo commit o contrato-fonte e gravewright/modules/static/gravewright_modules/frontend-contract.js. O contrato separado do SDK usa contracts/registry.json, contracts/api.json e os arquivos de contracts/schemas/, inclusive manifest.json. Veja módulos e frontend antes de alterá-los.

O frontend usa módulos JavaScript nativos. Deixe explícita a limpeza de listeners, timers, objetos de renderização e tarefas assíncronas. Alguns bundles de terceiros têm metadados próprios de build; reconstruí-los é separado de iniciar o Django. Preserve avisos de licença e atualize os avisos de terceiros ao trocar um bundle.

Convenções da documentação

Os guias em inglês ficam em docs/en/; os portugueses usam o mesmo nome em docs/pt-BR/. Cada guia aponta para o índice e sua tradução. Use links relativos para funcionar em forks e cópias baixadas. Não inclua caminhos absolutos de um desenvolvedor nem presuma uma URL de repositório não configurada.

Explique por que o código existe, suas responsabilidades e restrições. Mantenha comentários próximos do limite explicado. Em funções públicas importantes, documente identificadores/payloads aceitos, retornos, efeitos colaterais e erros do domínio. Preserve explicações úteis; não adicione comentário redundante a cada atribuição.

Os documentos da gramática de dados são mantidos junto à implementação. Os novos guias devem apontar para essas referências sem duplicar regras de sintaxe que possam divergir.

Identificadores da versão

A release atual é 0.3.1. Os manifests da aplicação usam estes identificadores, seguindo os formatos exigidos por cada ferramenta:

pyproject.toml é a fonte da versão instalada. gravewright/version.py deriva o identificador público e o rótulo; mantenha os metadados do pacote frontend alinhados ao alterá-la. Versões dos contratos de API/SDK e de módulos de terceiros têm ciclos independentes.

A release 0.3.1 segue a convenção stable de descoberta para identificadores numéricos; o projeto permanece em Alpha. Administração mostra o nome completo da versão, sem seletor de canal. Preferências de canal existentes e compatibilidade da API são preservadas. Veja as notas da 0.3.1 para mudanças e instruções de atualização.

Gerar o pacote de uma release

Alinhe pyproject.toml, uv.lock, o package.json do frontend e seu lockfile; adicione notas bilíngues em docs/releases/VERSÃO.md e atualize os índices e READMEs nos dois idiomas. Compile o frontend com node gravewright/maps/scripts/build.cjs e execute as verificações de testes, incluindo instalação nova e atualização.

Inclua no índice Git os novos fontes, migrações, testes e documentos antes de empacotar:

uv run --locked python scripts/build_release.py --check
uv run --locked python scripts/build_release.py

O gerador seleciona arquivos públicos rastreados pelo Git, verifica versões e arquivos obrigatórios e grava dist/Gravewright-VERSÃO-django.zip e seu SHA-256. Ele usa o conteúdo da árvore de trabalho; publique a partir do código revisado e commitado. --include-untracked permite revisar um pacote antes do commit; arquivos ignorados continuam excluídos. Extensões instaladas, dados locais, segredos, dependências e launchers específicos da máquina são excluídos nos dois modos. Use SOURCE_DATE_EPOCH com um timestamp Unix fixo para gerar timestamps reproduzíveis no ZIP.

Teste uma cópia extraída do ZIP final com armazenamento descartável. Publique o commit correspondente como vVERSÃO, com ZIP, checksum e notas bilíngues. Confira o digest do arquivo publicado e os workflows de CI pertinentes; gerar o pacote sozinho não valida o funcionamento da aplicação nem publica uma release.

Antes de enviar

Siga CONTRIBUTING.pt-BR.md. Confira traduções, registro gerado, migrações e avisos de licença conforme o escopo. Descreva a validação exata e eventuais falhas. Não inclua .env, dados de execução, uploads privados ou credenciais de navegador de uma implantação real.