Contributing Guide¶

Thank you for contributing to the Coaching App! This guide will help you understand our development workflow and standards.

Table of Contents¶

Code of Conduct
Getting Started
Development Workflow
Code Style
Commit Conventions
Pull Request Process
Testing Requirements
Documentation Updates

Code of Conduct¶

Be respectful and professional in all interactions
Provide constructive feedback during code reviews
Focus on the code, not the person
Help onboard new team members

Getting Started¶

Complete the onboarding checklist
Ensure your development environment is set up correctly
Familiarize yourself with the architecture
Read through existing code to understand patterns and conventions

Development Workflow¶

Create a branch from main using the naming convention:
Feature: feature/short-description
Bug fix: fix/short-description
Hotfix: hotfix/short-description
Documentation: docs/short-description
Make your changes
Keep commits focused and atomic
Write tests for new functionality
Update documentation when changing architecture or workflows
Ensure linters pass locally
Test thoroughly
Run unit tests: yarn test
Run linters: yarn lint
Check type safety: yarn type-check
Verify code coverage meets 80% threshold
Document your changes
Update relevant documentation in docs/
Add JSDoc comments for new functions/classes
Update README if adding new features or changing setup

Code Style¶

We use automated tools to enforce consistent code style:

TypeScript/JavaScript¶

ESLint: Enforces code quality rules
Prettier: Enforces code formatting
TypeScript: Strict mode enabled

Run formatting and linting:

yarn format        # Auto-format all files
yarn lint          # Check for linting issues
yarn lint:fix      # Auto-fix linting issues
yarn type-check    # Verify TypeScript types

Key Conventions¶

Naming:
Variables/functions: camelCase
Components: PascalCase
Constants: UPPER_SNAKE_CASE
Files: kebab-case.ts or PascalCase.tsx for components
TypeScript:
Always define types explicitly (avoid any)
Use interfaces for object shapes
Use type aliases for unions/intersections
Prefer const assertions where appropriate
Imports:
Group imports: external libraries → internal modules → relative imports
Use absolute imports via Yarn workspace for shared packages
Comments:
Write self-documenting code
Add comments for complex logic or non-obvious decisions
Use JSDoc for public APIs

Commit Conventions¶

We follow Conventional Commits specification:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types¶

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, missing semicolons, etc.)
refactor: Code refactoring without changing functionality
test: Adding or updating tests
chore: Maintenance tasks, dependency updates
schema: Database schema changes (migrations)

Scopes¶

backend: Hono API server changes
frontend: Expo web frontend changes
mobile: React Native mobile app changes
shared: Shared package changes
docker: Docker configuration changes
ci: CI/CD changes

Examples¶

feat(backend): add user profile endpoint
fix(mobile): resolve login button tap issue
docs(development): update Docker setup instructions
refactor(shared): simplify user type definitions
test(frontend): add coach dashboard unit tests
chore(deps): upgrade drizzle-orm to latest

Pull Request Process¶

Before Creating a PR¶

CI/CD Status Checks¶

All pull requests automatically trigger GitHub Actions workflows:

Test Job - Runs all tests with coverage reporting
Must achieve minimum 70% coverage across all metrics
Uploads coverage reports to Codecov (if configured)
Type Check Job - Validates TypeScript types
Runs pnpm type-check across all workspaces
Must pass without errors
Lint Job - Checks code style and formatting
Runs ESLint on all TypeScript/JavaScript files
Verifies Prettier formatting
Must pass without errors

All status checks must pass before merging. If checks fail, review the CI logs and fix issues locally before pushing again.

Creating a PR¶

Title: Use conventional commit format

feat(backend): add coaching session endpoints

Description: Include:
What: Summary of changes
Why: Motivation and context
How: Technical approach (if complex)
Testing: How you tested the changes
Screenshots: For UI changes
Related Issues: Link to issues using Closes #123
Template Example:

## What

Adds new endpoints for managing coaching sessions.

## Why

Users need to schedule and manage coaching sessions.

## How

- Created Hono router in `backend/src/routes/sessions/sessions.router.ts`
- Added session types to `shared/types/Session.ts`
- Implemented validation and authorization

## Testing

- Added unit tests for endpoint logic (95% coverage)
- Tested manually via Postman
- Verified mobile app can fetch sessions

## Related Issues

Closes #42

Code Review Checklist¶

Reviewers should verify:

Merging¶

Requires at least 1 approval from team member
All CI checks must pass
Merge using squash and merge to keep history clean
Delete branch after merging

Testing Requirements¶

All code contributions must include tests:

Coverage Requirements¶

Minimum: 80% coverage for statements, branches, functions, and lines
Run yarn test:coverage to check coverage
CI will fail if coverage drops below threshold

Test Types¶

Unit Tests: Test individual functions/components in isolation
Integration Tests: Test interactions between modules
E2E Tests: (Planned - see ROADMAP.md)

Writing Tests¶

// Example unit test
describe('calculateSessionPrice', () => {
  it('should calculate correct price for standard session', () => {
    const price = calculateSessionPrice({ duration: 60, type: 'standard' });
    expect(price).toBe(100);
  });

  it('should apply discount for premium members', () => {
    const price = calculateSessionPrice({
      duration: 60,
      type: 'standard',
      memberTier: 'premium',
    });
    expect(price).toBe(80);
  });
});

Documentation Updates¶

Documentation is code. When making changes that affect workflows, architecture, or setup:

When to Update Documentation¶

Adding new features or endpoints
Changing environment variables
Modifying Docker configuration
Updating dependencies with breaking changes
Changing development workflows
Adding new npm scripts
Modifying API contracts
Adding or modifying database schema (requires Drizzle migration)
Changing role-based access control rules

Documentation Maintenance Process¶

Identify affected docs: Check docs/ folder for related files
Update inline: Make documentation changes in the same PR as code changes
Add to PR description: Note which docs were updated
Review for accuracy: Ensure instructions still work after your changes
Update diagrams: Regenerate Mermaid diagrams if architecture changes

Documentation Standards¶

Keep docs concise and actionable
Use code examples where helpful
Update table of contents if adding sections
Test instructions in a clean environment
Use proper Markdown formatting
Include links to related documentation

Questions?¶

If you're unsure about anything:

Check existing documentation in docs/
Look at recent PRs for similar changes
Ask in team chat or create a discussion
Reach out to project maintainers

Thank you for contributing! 🎉