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
Join the discussion
Connect with the team on Discord to discuss your proposed changes.
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:
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)
Lint and Fix
Type Check
Run Tests
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)
Lint and Format
Check Formatting
Run Tests
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
Run all quality checks
# Backend
cd backend && uv run pre-commit run --all-files
# Frontend
cd frontend && pnpm run lint:fix && pnpm run format
Ensure tests pass
# Backend tests
make test
# Frontend tests
cd frontend && pnpm test
Update documentation
If you changed APIs or added features, update relevant documentation.
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
Push to your fork
git push origin feature/add-whoop-provider
Create Pull Request
Go to GitHub and create a PR from your fork to the main repository.
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.
Use environment variables
Store sensitive data in .env files (never committed to git).
Review before committing
Check for accidentally committed secrets:
Use .gitignore
Ensure .env, *.key, credentials.json are in .gitignore.
Database Migrations
When changing database models:
Create migration
make create_migration m="Add user preferences table"
Review migration file
Check generated migration in backend/migrations/versions/ for correctness.
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!