Contributor Guide

Developer Guidelines

This guide describes best practices for collaborating with Orion Framework and keeping the codebase consistent, testable and easy to evolve.

Guia de Contribuição

Developer Guidelines

Este guia descreve as práticas recomendadas para colaborar com o Orion Framework e manter a base de código consistente, testável e fácil de evoluir.

Prerequisites

Read the complete documentation.
Set up the environment as per the Quick Start Guide.
Use Python 3.10+ with updated pip.

Architecture Standards

The project follows Clean Architecture and SOLID principles.

Core (core/): Only entities and interfaces, no external dependencies.
Application (application/): Use cases, services and CLI; depends only on contracts.
Infrastructure (infrastructure/): Concrete implementations (connectors, logging, persistence).

Code Style

Use complete type hints and from __future__ import annotations when necessary.
Prefer pure and composable functions in pipelines.
Descriptive names: Portuguese for documentation, English for code.
Do not wrap imports in try/except blocks.
Functions up to ~40 lines, extracting auxiliary responsibilities.

Pull Request Checklist

Add tests for the change.
Run pytest locally.
Update relevant documentation.
Clearly describe the PR context (with screenshots when necessary).
Request review before merging.

Pré-requisitos

Ler a documentação completa.
Configurar o ambiente conforme o Guia Rápido.
Utilizar Python 3.10+ com pip atualizado.

Padrões de Arquitetura

O projeto segue Clean Architecture e princípios SOLID.

Core (core/): Somente entidades e interfaces, sem dependências externas.
Application (application/): Casos de uso, serviços e CLI; depende apenas de contratos.
Infrastructure (infrastructure/): Implementações concretas (conectores, logging, persistência).

Estilo de Código

Use type hints completos e from __future__ import annotations quando necessário.
Priorize funções puras e componíveis nas pipelines.
Nomes descritivos: português para documentação, inglês para código.
Não envolva imports em blocos try/except.
Funções até ~40 linhas, extraindo responsabilidades auxiliares.

Checklist de Pull Request

Adicione testes para a mudança.
Execute pytest localmente.
Atualize a documentação relevante.
Descreva claramente o contexto da PR (com screenshots quando necessário).
Solicite review antes do merge.