Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
241 lines (183 loc) · 4.86 KB

CONTRIBUTING.md

File metadata and controls

241 lines (183 loc) · 4.86 KB

Contributing to VELOCE

First off, thank you for considering contributing to VELOCE! 🎉

🌟 How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check existing issues. When creating a bug report, include:

  • Clear title and description
  • Steps to reproduce
  • Expected vs actual behavior
  • Environment details (OS, Docker version, etc.)
  • Screenshots if applicable

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:

  • Use a clear and descriptive title
  • Provide detailed description of the suggested enhancement
  • Explain why this enhancement would be useful
  • List examples of how it would work

Pull Requests

  1. Fork the repo and create your branch from main
  2. Follow the code style (see below)
  3. Add tests if applicable
  4. Update documentation if needed
  5. Ensure tests pass
  6. Create a Pull Request

📝 Code Style

Python (Backend)

  • Follow PEP 8
  • Use type hints
  • Use Ruff for linting
  • Use Black for formatting
  • Maximum line length: 88 characters
# Format code
ruff format .
black .

# Lint
ruff check .
mypy .

TypeScript (Frontend)

  • Follow ESLint rules
  • Use Prettier for formatting
  • Use TypeScript strict mode
# Format code
npm run format

# Lint
npm run lint

Docker

  • Use multi-stage builds
  • Minimize layer count
  • Use specific versions (no latest)
  • Add health checks

🏗️ Project Structure

VELOCE/
├── apps/
│   ├── backend/        # FastAPI backend
│   ├── frontend/       # React frontend
│   ├── mobile/         # React Native mobile
│   ├── ai_agents/      # AI agents system
│   └── ai_microservice/# AI microservice
├── docker/
│   ├── develop/        # Development environment
│   └── production/     # Production environment
├── docs/               # Documentation
└── config/             # Configuration files

🧪 Testing

Backend Tests

cd apps/backend

# Install dependencies with UV
uv pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=app --cov-report=html --cov-report=term

# Run tests in Docker (recommended)
docker exec veloce-api pytest --cov=app --cov-report=term

Test Coverage:

  • 319 total tests
  • 30.54% code coverage
  • Tests run in Docker containers
  • Coverage reports: HTML, XML, terminal

Frontend Tests

cd apps/frontend

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests with coverage
pnpm run test:coverage

📚 Documentation

  • Update README.md for user-facing changes
  • Update docs/ for technical documentation
  • Add JSDoc/docstrings for new functions
  • Update CHANGELOG.md

🔄 Git Workflow

Branch Naming

  • feature/description - New features
  • fix/description - Bug fixes
  • docs/description - Documentation
  • refactor/description - Code refactoring
  • test/description - Tests

Commit Messages

Follow Conventional Commits:

feat: add user authentication
fix: resolve database connection issue
docs: update installation guide
refactor: improve error handling
test: add unit tests for auth module

Pull Request Process

  1. Update your branch with latest main
  2. Ensure all tests pass
  3. Update documentation
  4. Request review from maintainers
  5. Address feedback
  6. Squash commits if requested

🎯 Development Setup

Prerequisites

  • Python 3.12+
  • Node.js 20+
  • Docker & Docker Compose
  • Poetry (Python)
  • Git

Quick Start

# Clone repository
git clone https://github.com/YOUR_USERNAME/VELOCE.git
cd VELOCE

# Start development environment
cd docker/develop
docker compose up -d

# Backend
cd apps/backend
poetry install
poetry run uvicorn app.main:app --reload

# Frontend
cd apps/frontend
npm install
npm run dev

🐛 Debugging

Backend

# Enable debug mode
export DEBUG=true
poetry run uvicorn app.main:app --reload --log-level debug

Frontend

# Enable debug mode
VITE_DEBUG=true npm run dev

Docker

# View logs
docker compose logs -f

# Inspect container
docker exec -it veloce-api sh

📋 Code Review Checklist

  • Code follows project style guidelines
  • Tests added/updated and passing
  • Documentation updated
  • No breaking changes (or documented)
  • Commit messages follow convention
  • PR description is clear
  • No merge conflicts

🤝 Community

📄 License

By contributing, you agree that your contributions will be licensed under the MIT License.

🙏 Thank You!

Your contributions make VELOCE better for everyone!