Skip to content

Contributing Guide

Thank you for your interest in contributing to Macumba Travel! This guide will help you get started with contributing to our AI-powered travel planning platform.

🚀 Getting Started

Prerequisites

  • Node.js 18+ (for frontend)
  • Python 3.9+ (for backend)
  • Docker and Docker Compose
  • Git for version control

Development Environment Setup

  1. Clone the repositories: 

    git clone https://github.com/MacumbaTravel/fastapi-backend.git
git clone https://github.com/MacumbaTravel/frontend.git
git clone https://github.com/MacumbaTravel/macumba-docs.git

  2. Backend setup: 

    cd fastapi-backend
cp .env.example .env
# Configure your environment variables
docker-compose up -d

  3. Frontend setup: 

    cd frontend
npm install
npm run dev

  4. Documentation setup: 

    cd macumba-docs
pip install mkdocs-material
mkdocs serve

📋 Code Standards

Python (Backend)

  • PEP 8 compliance
  • Type hints required for all functions
  • Async/await for I/O operations
  • Comprehensive docstrings

Example: 

async def get_recommendations(
    budget: float,
    duration: int,
    departure_city: str,
    preferences: List[str]
) -> List[SimpleRecommendation]:
    """
    Generate travel recommendations based on user preferences.

    Args:
        budget: Total budget for the trip
        duration: Trip duration in days
        departure_city: City to depart from
        preferences: List of user preferences

    Returns:
        List of simple recommendations
    """

JavaScript/Vue.js (Frontend)

  • ESLint and Prettier configuration
  • Composition API preferred
  • TypeScript where applicable
  • Component naming: PascalCase

Example: 

<script setup>
import { ref, computed } from 'vue'
import { useRecommendations } from '@/composables/useRecommendations'

const budget = ref(1000)
const { recommendations, loading, error } = useRecommendations(budget)
</script>

Documentation

  • Markdown for all documentation
  • Clear headings and structure
  • Code examples for all features
  • Screenshots where helpful

🔄 Development Workflow

1. Issue Creation

  • Check existing issues first
  • Use appropriate issue templates
  • Provide clear reproduction steps
  • Include system information

2. Branch Strategy

  • Main branch: main - Production ready
  • Development branch: development - Integration branch
  • Feature branches: feature/description
  • Bug fixes: fix/description

3. Pull Request Process

  1. Create feature branch: 

    git checkout -b feature/your-feature-name

  2. Make changes and commit: 

    git add .
git commit -m "feat: add travel recommendation caching"

  3. Push and create PR: 

    git push origin feature/your-feature-name

  4. Fill out PR template:

  5. Clear description of changes
  6. Link to related issues
  7. Screenshots for UI changes
  8. Test coverage information

4. Code Review Process

  • All PRs require at least one review
  • Address feedback promptly
  • Ensure CI passes
  • Update documentation as needed

🧪 Testing

Backend Testing

# Run all tests
docker-compose exec backend pytest

# Run with coverage
docker-compose exec backend pytest --cov=app tests/

# Run specific test file
docker-compose exec backend pytest tests/api/test_recommendations.py

Frontend Testing

# Run unit tests
npm run test:unit

# Run e2e tests
npm run test:e2e

# Run with coverage
npm run test:coverage

Test Requirements

  • Unit tests for all new functions
  • Integration tests for API endpoints
  • E2E tests for user workflows
  • Minimum 80% coverage for new code

📝 Commit Message Convention

We use conventional commits:

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • style: - Code style changes
  • refactor: - Code refactoring
  • test: - Test additions/modifications
  • chore: - Maintenance tasks

Examples: 

feat: add budget-based recommendation filtering
fix: resolve cache expiration issue
docs: update API documentation for new endpoints
test: add integration tests for recommendation service

🚨 Common Issues and Solutions

Environment Issues

  • Port conflicts: Check if ports 8000/3000 are available
  • Database connection: Ensure PostgreSQL is running
  • Environment variables: Double-check .env configuration

Docker Issues

  • Container won't start: Check logs with docker-compose logs
  • Permission issues: Ensure Docker has proper permissions
  • Build failures: Clear cache with docker-compose build --no-cache

AI Service Issues

  • API key errors: Verify Gemini/Claude API keys
  • Rate limiting: Check API usage limits
  • Response timeouts: Increase timeout values in configuration

📚 Resources

Documentation

Project-Specific

🤝 Community

Communication

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: General questions and ideas
  • Code Reviews: Technical discussions on PRs

Getting Help

  1. Check documentation first
  2. Search existing issues
  3. Ask in GitHub Discussions
  4. Create detailed issue if needed

📈 Contribution Ideas

Good First Issues

  • Documentation improvements
  • UI/UX enhancements
  • Test coverage improvements
  • Code style fixes

Advanced Contributions

  • AI prompt optimization
  • Performance improvements
  • New feature implementation
  • Infrastructure enhancements

Areas Needing Help

  • Frontend: Vue.js components and styling
  • Backend: API endpoints and optimization
  • Documentation: User guides and tutorials
  • Testing: Test coverage and automation
  • DevOps: CI/CD and deployment improvements

🏆 Recognition

Contributors are recognized through: - GitHub Contributors page - Release notes mentions - Community highlights - Maintainer recommendations

Thank you for contributing to Macumba Travel! Together, we're making travel planning more accessible and intelligent for everyone. 🌍✈️