← Back to Table of Contents

Contributing Guide

Thank you for your interest in contributing to the Open Source Site Tracking platform! This guide will help you get started with contributing to our project.

Getting Started Development Workflow Coding Standards Testing Documentation Submitting Changes Community

Getting Started

Prerequisites

Setup Your Development Environment

1. Fork the Repository

# Fork the repository on GitHub
git clone https://github.com/YOUR_USERNAME/Opensource-Site-Tracking.git
cd opensource-site-tracking

2. Set Up Development Environment

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
# Install backend dependencies
cd backend
pip install -r requirements.txt
pip install -r requirements-dev.txt
# Install frontend dependencies
cd ../frontend
npm install

3. Start Development Servers

# Start backend (in backend directory)
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
# Start frontend (in frontend directory)
npm run dev

Development Workflow

Branch Strategy

Development Process

  1. Create Issue: Create an issue for your contribution
  2. Create Branch: Create a feature branch from develop
  3. Develop: Implement your changes
  4. Test: Write and run tests
  5. Document: Update documentation
  6. Submit PR: Create pull request
  7. Review: Address feedback
  8. Merge: Merge into develop branch

Git Workflow Commands

# Update your fork
git fetch upstream
git checkout develop
git merge upstream/develop
# Create feature branch
git checkout -b feature/your-feature-name
# Make changes
git add .
git commit -m "feat: add your feature"
# Push to your fork
git push origin feature/your-feature-name

Coding Standards

Python Standards

JavaScript/TypeScript Standards

Code Formatting

Python Formatting

# Format code
black backend/
isort backend/
# Check formatting
black --check backend/
isort --check-only backend/
# Lint code
flake8 backend/
mypy backend/

JavaScript Formatting

# Format code
npm run lint
npm run format
# Check formatting
npm run lint:fix
npm run format:check

Testing

Backend Testing

Frontend Testing

Running Tests

Backend Tests

# Run all tests
pytest
# Run with coverage
pytest --cov=app
# Run specific test
pytest tests/test_analytics.py
# Run with verbose output
pytest -v

Frontend Tests

# Run all tests
npm test
# Run with coverage
npm run test:coverage
# Run specific test
npm test -- --testNamePattern="Analytics"
# Run in watch mode
npm run test:watch

Writing Tests

# Backend test example
import pytest
from app.services.analytics import AnalyticsService
class TestAnalyticsService:
    def test_calculate_page_views(self):
        service = AnalyticsService()
        result = service.calculate_page_views([1, 2, 3, 4, 5])
        assert result == 5
    
    def test_calculate_unique_visitors(self):
        service = AnalyticsService()
        result = service.calculate_unique_visitors(['user1', 'user2', 'user1'])
        assert result == 2

Documentation

Documentation Types

Documentation Standards

Writing Documentation

# Documentation example
## Analytics Overview
The analytics system provides comprehensive insights into user behavior and system performance.
### Features
- **Real-time Analytics**: Live data processing and visualization
- **Custom Reports**: Generate custom analytics reports
- **Data Export**: Export analytics data in various formats
### Usage
```python
from app.services.analytics import AnalyticsService
service = AnalyticsService()
analytics = service.get_analytics(project_id)
```

Submitting Changes

Pull Request Process

  1. Create Pull Request: Create PR from your branch to develop
  2. Description: Provide clear description of changes
  3. Testing: Ensure all tests pass
  4. Documentation: Update relevant documentation
  5. Review: Address review feedback
  6. Approval: Get approval from maintainers
  7. Merge: Merge into develop branch

Pull Request Template

## Description
Brief description of changes
## Type
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
## Testing
- [ ] All tests pass
- [ ] New tests added
- [ ] Manual testing completed
## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review of the code
- [ ] Documentation updated
- [ ] No breaking changes (or documented)

Code Review Guidelines

Community

Ways to Contribute

Communication Channels

Community Guidelines

Our Community Values

  • Inclusive: Welcome contributors from all backgrounds
  • Respectful: Treat everyone with respect and kindness
  • Collaborative: Work together to achieve common goals
  • Helpful: Help others learn and contribute
  • Patient: Be patient with newcomers and questions

Getting Help

Important Notes

  • License: All contributions are under the MIT license
  • CLA: Contributors must sign the Contributor License Agreement
  • Security: Report security vulnerabilities privately
  • Patience: Review process may take time
  • Learning: We're here to help you learn and grow

Recognition

Thank You!

We appreciate your interest in contributing to the Open Source Site Tracking platform. Your contributions help make this project better for everyone!

If you have any questions about contributing, please don't hesitate to ask in our GitHub Discussions or Discord community.

Happy contributing! 🚀