Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
273 lines (197 loc) · 5.22 KB

CONTRIBUTING.md

File metadata and controls

273 lines (197 loc) · 5.22 KB

Contribuindo para SQLBridge

Obrigado por considerar contribuir para o SQLBridge! 🎉

Como Contribuir

1. Reportar Bugs

Abra uma issue com:

  • Descrição clara do problema
  • Passos para reproduzir
  • Comportamento esperado vs atual
  • Versão do Python e banco de dados
  • Código de exemplo

2. Sugerir Features

Abra uma issue descrevendo:

  • O problema que a feature resolve
  • Como você imagina a solução
  • Exemplos de uso

3. Contribuir com Código

Setup do Ambiente

# Clone o repositório
git clone https://github.com/thespamer/sqlbridge.git
cd sqlbridge

# Crie um ambiente virtual
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Instale em modo desenvolvimento
pip install -e ".[dev]"

Workflow

  1. Fork o projeto

  2. Crie uma branch para sua feature:

    git checkout -b feature/minha-feature

  3. Faça suas alterações seguindo o estilo do código

  4. Execute os testes:

    pytest tests/ -v

  5. Verifique a cobertura:

    pytest --cov=sqlbridge tests/

  6. Formate o código:

    black sqlbridge tests examples
isort sqlbridge tests examples
flake8 sqlbridge

  7. Commit suas mudanças:

    git commit -m "feat: adiciona suporte para X"

  8. Push para seu fork:

    git push origin feature/minha-feature

  9. Abra um Pull Request

Padrões de Código

Estilo

  • Seguimos PEP 8
  • Usamos Black para formatação (line-length=100)
  • Usamos isort para ordenar imports
  • Docstrings em formato Google

Exemplo de Docstring

def translate(self, sql: str) -> str:
    """
    Traduz SQL padrão para o dialeto específico.
    
    Args:
        sql: SQL padrão a ser traduzido
        
    Returns:
        SQL traduzido para o dialeto
        
    Raises:
        ValueError: Se o SQL for inválido
        
    Example:
        >>> dialect = MySQLDialect()
        >>> dialect.translate("SELECT * FROM users LIMIT 10")
        'SELECT * FROM users LIMIT 10'
    """

Commits

Seguimos Conventional Commits:

  • feat: Nova feature
  • fix: Correção de bug
  • docs: Mudanças na documentação
  • style: Formatação, sem mudança de código
  • refactor: Refatoração de código
  • test: Adição ou correção de testes
  • chore: Manutenção geral

Exemplos:

feat: adiciona suporte para MariaDB
fix: corrige tradução de LIMIT no Oracle
docs: atualiza README com exemplos de DB2
test: adiciona testes para InformixDialect

Testes

Estrutura

tests/
├── test_core.py          # Testes da classe SQLBridge
├── test_dialects.py      # Testes dos dialetos
├── test_detector.py      # Testes do detector
└── test_integration.py   # Testes de integração

Escrevendo Testes

import pytest
from sqlbridge.dialects import MySQLDialect

class TestMySQLDialect:
    def setup_method(self):
        self.dialect = MySQLDialect()
    
    def test_auto_increment(self):
        sql = "CREATE TABLE test (id INTEGER AUTO_INCREMENT)"
        result = self.dialect.translate(sql)
        assert "AUTO_INCREMENT" in result

Executar Testes

# Todos os testes
pytest

# Testes específicos
pytest tests/test_dialects.py

# Com cobertura
pytest --cov=sqlbridge --cov-report=html

# Modo verbose
pytest -v

# Parar no primeiro erro
pytest -x

Adicionando Suporte para Novo Banco

1. Criar Dialeto

Crie sqlbridge/dialects/meudb.py:

from .base import BaseDialect

class MeuDBDialect(BaseDialect):
    name = "meudb"
    
    type_mappings = {
        "INTEGER": "INT",
        "BOOLEAN": "BIT",
    }
    
    def _translate_auto_increment(self, sql: str) -> str:
        # Implementar tradução
        return sql

2. Registrar Dialeto

Em sqlbridge/dialects/__init__.py:

from .meudb import MeuDBDialect

DIALECT_MAP = {
    # ...
    "meudb": MeuDBDialect,
}

3. Adicionar Detecção

Em sqlbridge/detector.py:

def detect_dialect(connection):
    # ...
    if "meudb" in module_name:
        return "meudb"

4. Escrever Testes

Em tests/test_dialects.py:

class TestMeuDBDialect:
    def setup_method(self):
        self.dialect = MeuDBDialect()
    
    def test_auto_increment(self):
        # Seus testes aqui
        pass

5. Documentar

Atualize:

  • README.md - adicione na lista de bancos suportados
  • QUICKSTART.md - adicione exemplo de uso
  • examples/ - adicione exemplo prático

Checklist do Pull Request

  • Código segue o estilo do projeto
  • Testes adicionados/atualizados
  • Todos os testes passam
  • Documentação atualizada
  • CHANGELOG.md atualizado
  • Commit messages seguem padrão
  • Branch atualizada com main

Código de Conduta

  • Seja respeitoso e inclusivo
  • Aceite críticas construtivas
  • Foque no que é melhor para a comunidade
  • Mostre empatia com outros membros

Dúvidas?

Licença

Ao contribuir, você concorda que suas contribuições serão licenciadas sob a MIT License.

Obrigado por contribuir! 🚀