Pular para conteúdo

Regras do projeto

São estas regras que mantêm o sistema organizado e a documentação viva.

1. Toda mudança vai junto com o que a explica

Em um mesmo commit:

  • [ ] o código;
  • [ ] os testes da regra nova ou alterada;
  • [ ] a documentação afetada (docs/modulos/…, docs/operacao/…);
  • [ ] uma linha no histórico de versões;
  • [ ] se for uma decisão de arquitetura, uma ADR nova em docs/decisoes/.

Mudou um model? Gere a migração e a documentação do modelo:

python manage.py makemigrations
python manage.py gerar_doc_modelo
python manage.py spectacular --file ../docs/referencia/openapi.yaml

2. O CI é o porteiro

A cada envio, o GitHub Actions verifica:

Verificação Falha quando
Estilo (ruff) Código fora do padrão
Migrações Model alterado sem migração
Testes (pytest) Algum teste quebra
Documentação gerada Modelo de dados ou OpenAPI desatualizados
Documentação compila Link quebrado ou página fora do menu

Commit com X vermelho não vai para produção.

3. Versões

  • main sempre funcional.
  • Cada entrega para produção recebe uma tag vMAJOR.MINOR.PATCH (ex.: v0.1.0), com as notas no changelog.

4. Dados

  • Nunca alterar dados direto no banco com SQL: isso passa por fora da auditoria.
  • Credenciais (senhas de OLT, chaves de API) ficam no banco criptografadas ou no .env, nunca no código.

5. Linguagem

Código, banco e documentação em português, exceto termos técnicos consagrados (PON, ONU, OLT, SNMP, etc.) e nomes vindos do Django.

Toda tela em português (pt-BR). Textos de pacotes de terceiros sem tradução ficam em backend/locale/gerar_traducoes.py (ADR 0010).

Depois de atualizar um pacote com telas (Unfold, django-celery-beat), procure textos novos sem tradução:

# na pasta backend/, com o ambiente de desenvolvimento ativo
mkdir -p /tmp/extrair/locale && cp -r "$(python -c 'import unfold,os;print(os.path.dirname(unfold.__file__))')" /tmp/extrair/
cd /tmp/extrair && django-admin makemessages -l pt_BR -e html,py,txt && cd -
# compare /tmp/extrair/locale/pt_BR/LC_MESSAGES/django.po com o que já está traduzido

Acrescente o que faltar em gerar_traducoes.py e rode:

python locale/gerar_traducoes.py
python manage.py compilemessages -l pt_BR

6. Telas

Toda tela nova segue a ADR 0010: tema Claro, Escuro e Sistema (padrão: Sistema) e textos em português.