Skip to main content

Contributing to Open Wearables

Thank you for your interest in contributing to Open Wearables! This project provides a unified API for health and wearable data aggregation.
Before jumping into a PR, check Discord to confirm no one else is working on the same feature and to validate your approach aligns with the project roadmap.

Before You Start

1

Search existing work

Check existing PRs and issues to avoid duplicating work.
2

Join the discussion

Connect with the team on Discord to discuss your proposed changes.
3

Set up your environment

Follow the Local Setup Guide to get your development environment running.

Development Workflow

1. Fork and Clone

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/open-wearables.git
cd open-wearables

# Add upstream remote
git remote add upstream https://github.com/yocxy2/open-wearables.git

2. Create a Feature Branch

# Create a descriptive branch name
git checkout -b feature/add-whoop-provider
# or
git checkout -b fix/user-authentication-bug
Use prefixes like feature/, fix/, docs/, or refactor/ to categorize your changes.

3. Make Your Changes

Follow the coding standards and patterns established in the codebase:

Backend Patterns

See backend/AGENTS.md for Python/FastAPI conventions.

Frontend Patterns

See frontend/AGENTS.md for React/TypeScript patterns.

4. Test Your Changes

Backend Tests:
cd backend

# Run all tests
uv run pytest

# Run specific test file
uv run pytest tests/api/v1/test_users.py

# Run with coverage
uv run pytest --cov=app --cov-report=html
Frontend Tests:
cd frontend

# Run all tests
pnpm test

# Watch mode for development
pnpm test:watch
All tests must pass before submitting a PR. New features should include tests.

Code Quality

Pre-commit Hooks

The project uses pre-commit hooks to ensure code quality:
# Install pre-commit hooks (first time setup)
uv sync --group code-quality
uv run pre-commit install

# Run all checks manually
uv run pre-commit run --all-files
This automatically runs:
  • Ruff linter and formatter (Python)
  • ty type checker (Python)
  • oxlint (TypeScript/React)
  • Prettier formatter (TypeScript/React)
  • Trailing whitespace and end-of-file fixers

Backend (Python)

cd backend
uv run ruff check . --fix && uv run ruff format .
Style Requirements:
  • Line length: 120 characters
  • Type hints required on all function parameters and return types
  • Imports sorted automatically by Ruff
  • All imports at module level (never inside functions)
  • PEP 8 naming conventions

Frontend (TypeScript/React)

cd frontend
pnpm run lint:fix && pnpm run format
Style Requirements:
  • Line width: 80 characters
  • Single quotes, semicolons always
  • 2-space indentation
  • TypeScript strict mode enabled

Pull Request Guidelines

Before Submitting

1

Run all quality checks

# Backend
cd backend && uv run pre-commit run --all-files

# Frontend
cd frontend && pnpm run lint:fix && pnpm run format
2

Ensure tests pass

# Backend tests
make test

# Frontend tests
cd frontend && pnpm test
3

Update documentation

If you changed APIs or added features, update relevant documentation.
4

Commit your changes

git add .
git commit -m "feat: add Whoop provider integration"
Use conventional commits format:
  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • refactor: - Code refactoring
  • test: - Adding tests
  • chore: - Maintenance tasks

Submitting Your PR

1

Push to your fork

git push origin feature/add-whoop-provider
2

Create Pull Request

Go to GitHub and create a PR from your fork to the main repository.
3

Write a clear PR description

Include:
  • What: Brief description of changes
  • Why: Problem being solved or feature rationale
  • How: Implementation approach (if complex)
  • Testing: How you tested the changes
  • Screenshots/videos for UI changes

PR Template Example

## Summary
Adds Whoop provider integration with OAuth 2.0 and workout sync.

## Changes
- Implemented WhoopStrategy, WhoopOAuth, and WhoopWorkouts
- Added workout type mappings for Whoop activities
- Registered provider in ProviderFactory
- Added tests for OAuth flow and workout normalization

## Testing
- [x] All existing tests pass
- [x] Added unit tests for Whoop normalization
- [x] Manually tested OAuth flow end-to-end
- [x] Verified workouts sync correctly

## Screenshots
[Include screenshots if UI changes]

## Related Issues
Closes #123

Testing Requirements

When to Write Tests

New Features

All new features must include tests demonstrating functionality.

Bug Fixes

Include a test that would have caught the bug.

Refactoring

Ensure existing tests still pass, add new ones if behavior changes.

API Changes

Test all endpoints, status codes, and error cases.

Backend Testing Patterns

Backend tests use pytest with pytest-asyncio:
import pytest
from httpx import AsyncClient
from app.database import DbSession

@pytest.mark.asyncio
async def test_create_user(client: AsyncClient, db: DbSession):
    """Test user creation endpoint."""
    response = await client.post(
        "/api/v1/users",
        json={"email": "[email protected]", "first_name": "Test"}
    )
    assert response.status_code == 201
    data = response.json()
    assert data["email"] == "[email protected]"
    assert "id" in data
Tests use transaction rollback for isolation - each test runs in its own transaction that is rolled back after completion.

Frontend Testing Patterns

Frontend tests use Vitest with React Testing Library:
import { render, screen, fireEvent } from '@testing-library/react';
import { describe, it, expect } from 'vitest';
import { LoginForm } from './LoginForm';

describe('LoginForm', () => {
  it('submits form with valid credentials', async () => {
    const onSubmit = vi.fn();
    render(<LoginForm onSubmit={onSubmit} />);
    
    fireEvent.change(screen.getByLabelText('Email'), {
      target: { value: '[email protected]' },
    });
    fireEvent.change(screen.getByLabelText('Password'), {
      target: { value: 'password123' },
    });
    
    fireEvent.click(screen.getByRole('button', { name: 'Sign In' }));
    
    expect(onSubmit).toHaveBeenCalledWith({
      email: '[email protected]',
      password: 'password123',
    });
  });
});

Security Guidelines

Never commit secrets, API keys, or credentials to the repository.
1

Use environment variables

Store sensitive data in .env files (never committed to git).
2

Review before committing

Check for accidentally committed secrets:
git diff --cached
3

Use .gitignore

Ensure .env, *.key, credentials.json are in .gitignore.

Database Migrations

When changing database models:
1

Create migration

make create_migration m="Add user preferences table"
2

Review migration file

Check generated migration in backend/migrations/versions/ for correctness.
3

Apply migration

make migrate
4

Test rollback

make downgrade
make migrate
Migrations should be reversible. Always implement both upgrade() and downgrade() functions.

Documentation Standards

When updating documentation in the docs/ directory:

Code Examples

  • Include complete, runnable examples
  • Show proper error handling
  • Use realistic data (not placeholders)
  • Include expected outputs
  • Never include real API keys
# Good: Complete, runnable example
from app.services.providers.factory import ProviderFactory

factory = ProviderFactory()
provider = factory.get_provider("garmin")

# Bad: Incomplete example with placeholders
provider = get_provider("YOUR_PROVIDER_HERE")  # Don't do this

API Documentation

  • Document all parameters including optional ones
  • Show both success and error response examples
  • Include rate limiting information
  • Explain all HTTP status codes

CI/CD Pipeline

The CI pipeline automatically runs on every PR: Backend Checks:
  • uv run ruff check - Linting
  • uv run ruff format --check - Formatting
  • uv run ty check - Type checking
  • uv run pytest - Test suite
Frontend Checks:
  • pnpm run lint - Linting
  • pnpm run format:check - Formatting
  • pnpm run build - Build verification
  • pnpm test - Test suite
All checks must pass before a PR can be merged.

Getting Help

Discord Community

Join our Discord for real-time help and discussions.

GitHub Issues

Report bugs or request features.

GitHub Discussions

Ask questions or share ideas.

Documentation

Review existing docs for patterns and guidelines.

Recognition

Contributors are recognized in:
  • The project README
  • Release notes for their contributions
  • GitHub contributor graphs
Thank you for making Open Wearables better!

Build docs developers (and LLMs) love