Contributing to Travel Recommendation System

Thank you for your interest in contributing to this project!

📋 Table of Contents

• Code of Conduct
• Getting Started
• Development Workflow
• Coding Standards
• Commit Guidelines
• Pull Request Process

🤝 Code of Conduct

• Be respectful and inclusive
• Provide constructive feedback
• Focus on what is best for the project
• Show empathy towards other contributors

🚀 Getting Started

1. Fork the repository

2. Clone your fork

   git clone https://github.com/YOUR_USERNAME/Travel-Recommend.git
   cd Travel-Recommend

3. Set up development environment

   python -m venv venv
   source venv/bin/activate  # Windows: venv\Scripts\activate
   pip install -r requirements.txt

4. Configure secrets

   • Copy .streamlit/secrets.toml.example to .streamlit/secrets.toml
   • Add your credentials

🔄 Development Workflow

Branching Strategy

• main - Production-ready code
• develop - Integration branch
• feature/* - New features
• fix/* - Bug fixes
• docs/* - Documentation updates

Creating a Feature Branch

git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

Making Changes

1. Make your changes
2. Test thoroughly
3. Update documentation if needed
4. Commit with descriptive messages

📝 Coding Standards

Python Style Guide

• Follow PEP 8
• Use type hints where applicable
• Maximum line length: 100 characters
• Use docstrings for all functions and classes

Example

def calculate_distance(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
    """
    Calculate distance between two points using Haversine formula.
    
    Args:
        lat1: Latitude of first point
        lon1: Longitude of first point
        lat2: Latitude of second point
        lon2: Longitude of second point
    
    Returns:
        Distance in miles
    """
    # Implementation here
    pass

File Organization

• Pages: Streamlit pages in pages/
• Core Logic: Business logic in src/
• Utilities: Helper functions in utils/
• Tests: Test files in tests/
• SQL: Database scripts in sql/
• Config: Configuration in config/
• Docs: Documentation in docs/

💬 Commit Guidelines

Commit Message Format

<type>: <subject>

<body>

<footer>

Types

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Examples

feat: Add spatial proximity query support

- Implement point.distance() for Neo4j queries
- Add "near" keyword detection
- Update LLM prompts with spatial examples

Closes #123

fix: Resolve indentation error in Smart Recommendations

- Fixed expander indentation
- Updated rec_tab1, rec_tab2, rec_tab3 blocks
- All syntax errors resolved

🔍 Pull Request Process

Before Submitting

• Code follows style guidelines
• All tests pass
• Documentation is updated
• No merge conflicts with develop
• Commits are clean and descriptive

Submitting a PR

1. Push your branch

   git push origin feature/your-feature-name

2. Create Pull Request on GitHub

   • Base: develop
   • Compare: feature/your-feature-name
   • Fill in the PR template

3. PR Template

   ## Description
   Brief description of changes
   
   ## Type of Change
   - [ ] Bug fix
   - [ ] New feature
   - [ ] Documentation update
   - [ ] Refactoring
   
   ## Testing
   - [ ] Tested locally
   - [ ] All pages work correctly
   - [ ] No console errors
   
   ## Screenshots (if applicable)
   Add screenshots here
   
   ## Checklist
   - [ ] Code follows style guidelines
   - [ ] Documentation updated
   - [ ] Tests added/updated

Code Review

• All PRs require 1 approval
• Hotragn is the primary reviewer
• Address review comments promptly
• Be open to feedback

After Approval

git checkout develop
git pull origin develop
git merge feature/your-feature-name
git push origin develop
git branch -d feature/your-feature-name

🧪 Testing

Running Tests

# Run all tests
python -m pytest tests/

# Run specific test
python -m pytest tests/test_auth.py

# Run with coverage
python -m pytest --cov=src tests/

Writing Tests

• Place tests in tests/ directory
• Name test files test_*.py
• Use descriptive test names

def test_user_authentication_success():
    """Test successful user login"""
    result = authenticate_user("testuser", "password123")
    assert result is not None
    assert result['username'] == "testuser"

📚 Documentation

Updating Documentation

• Update README.md for major changes
• Update relevant docs in docs/ folder
• Add docstrings to new functions
• Update TECHNICAL_DOCUMENTATION.md for architecture changes

Documentation Standards

• Use Markdown for all documentation
• Include code examples where helpful
• Add diagrams for complex concepts (Mermaid)
• Keep documentation up-to-date

🐛 Reporting Bugs

Bug Report Template

**Describe the bug**
Clear description of the bug

**To Reproduce**
Steps to reproduce:
1. Go to '...'
2. Click on '...'
3. See error

**Expected behavior**
What you expected to happen

**Screenshots**
If applicable

**Environment**
- OS: [e.g., Windows 11]
- Python version: [e.g., 3.14]
- Browser: [e.g., Chrome 120]

💡 Feature Requests

Feature Request Template

**Feature Description**
Clear description of the feature

**Use Case**
Why is this feature needed?

**Proposed Solution**
How should it work?

**Alternatives Considered**
Other approaches you've thought about

🎯 Project Priorities

Current focus areas:

1. Performance optimization
2. Enhanced AI features
3. Multi-state support
4. Mobile responsiveness
5. Additional visualizations

📞 Getting Help

• Email: pettugani.h@northeastern.edu
• GitHub Issues: For bugs and features
• GitHub Discussions: For questions

🙏 Thank You!

Your contributions make this project better. We appreciate your time and effort!

---

Project Team: Hotragn, Tirdesh, Amantha
Last Updated: December 2025