On Book

Appearance

Contributing Guide ​

How to contribute to On Book Pro.

Welcome! ​

Thank you for your interest in contributing! This guide will help you:

  • Set up your development environment
  • Understand our workflow
  • Submit high-quality pull requests

Getting Started ​

1. Fork and Clone ​

bash
# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/your-username/on-book-pro.git
cd on-book-pro

2. Install Dependencies ​

bash
npm install

3. Set Up Environment ​

bash
cp .env.example .env
# Add your Firebase credentials

4. Start Development Server ​

bash
npm run dev

Opens at http://localhost:5174

Branch Strategy ​

Main Branches ​

  • main — Production-ready code
  • testing — Pre-merge verification branch

Feature Branches ​

Create a new branch for your work:

bash
git checkout -b feature/your-feature-name

Naming conventions:

  • feature/ — New features
  • fix/ — Bug fixes
  • docs/ — Documentation updates
  • refactor/ — Code refactoring

Code Standards ​

TypeScript ​

  • Strict mode enabled — No implicit any
  • Explicit return types for public functions
  • Use branded types for IDs

Components ​

  • Use primitives from src/components/common/
  • No raw HTML elements (<button>, <input>, <select>)
  • Compose with Tailwind utilities

State Management ​

  • Use Immer syntax for Zustand updates
  • Focused selectors — Only subscribe to what you need

See full Style Guide

Testing ​

Run Tests ​

bash
npm test

# With UI
npm run test:ui

Writing Tests ​

typescript
// tests/features/cast.test.ts
import { describe, it, expect } from 'vitest';
import { renderHook, act } from '@testing-library/react';
import { useStore } from '@/store';

describe('CastSlice', () => {
  it('should add an actor', () => {
    const { result } = renderHook(() => useStore());
    
    act(() => {
      result.current.addActor({
        name: 'John Doe',
        email: 'john@example.com',
      });
    });
    
    expect(result.current.cast.actors).toHaveLength(1);
    expect(result.current.cast.actors[0].name).toBe('John Doe');
  });
});

Pull Request Process ​

1. Create PR ​

Push your branch and create a pull request on GitHub:

bash
git push origin feature/your-feature-name

Title format: feat: add blocking path visibility toggle

2. PR Checklist ​

Ensure your PR includes:

  • [ ] Tests pass (npm test)
  • [ ] E2E tests pass (npx playwright test)
  • [ ] No lint errors (npm run lint)
  • [ ] Code follows style guide
  • [ ] Documentation updated (if user-facing)
  • [ ] No console warnings in dev
  • [ ] Tested in browser (Chrome, Firefox, Safari)

3. Description Template ​

markdown
## Description
Brief summary of what this PR does.

## Changes
- Added X feature
- Fixed Y bug
- Refactored Z component

## Screenshots (if UI changes)
[Add screenshots]

## Testing
How to test this PR:
1. Step 1
2. Step 2

## Related Issues
Fixes #123

4. Review Process ​

  • Code review: Maintainer will review within 48 hours
  • Address feedback: Make requested changes
  • Merge: Once approved, maintainer will merge

Commit Messages ​

Follow Conventional Commits:

Format ​

<type>(<scope>): <subject>

<body (optional)>

Types ​

  • feat — New feature
  • fix — Bug fix
  • docs — Documentation only
  • refactor — Code refactoring
  • test — Adding tests
  • chore — Build/config changes

Examples ​

bash
feat(scheduler): add AEA compliance warnings
fix(blocking): resolve path rendering on mobile
docs(readme): update installation instructions
refactor(cast): extract actor form to separate component

Documentation ​

When to Update Docs ​

Update documentation if your PR:

  • Adds a new user-facing feature
  • Changes existing behavior
  • Adds/modifies an API endpoint
  • Introduces new developer patterns

Where to Add Docs ​

Change TypeDocumentation Location
User featuredocs/user/features/
Architecturedocs/dev/architecture/
API endpointdocs/dev/api/
Code patterndocs/dev/guides/ or docs/dev/style-guide.md

Development Tips ​

Hot Reloading ​

Changes auto-reload in dev server. If issues occur:

bash
# Clear cache and restart
rm -rf node_modules/.vite
npm run dev

Firebase Emulators ​

Test cloud functions locally:

bash
firebase emulators:start

Debugging ​

  • Use React DevTools for component inspection
  • Use Redux DevTools for Zustand state
  • Check browser console for errors

Community ​

Getting Help ​

  • Questions? Open a GitHub Discussion
  • Bug report? Open a GitHub Issue
  • Feature request? Open a GitHub Issue with enhancement label

Code of Conduct ​

Be respectful, inclusive, and collaborative. We follow the Contributor Covenant.

Recognition ​

All contributors are valued and appreciated!

Thank you for contributing to On Book Pro!