Contributing to CAIRL

Thank you for your interest in contributing to CAIRL!

Before You Start

  1. Read Engineering Principles
  2. Review Git Workflow
  3. Understand Code Style Guide

Development Setup

Prerequisites

  • Node.js 20+
  • npm or pnpm
  • PostgreSQL (via Supabase)
  • Git

Installation

# Clone repository
git clone https://github.com/reAPPlicate/cairl.git
cd cairl

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env.local

# Fill in your environment variables
# See docs/setup/ENVIRONMENT_VARIABLES.md

# Run database migrations
npm run db:push

# Start development server
npm run dev

Visit http://localhost:3000

Development Process

1. Create a Branch

git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

2. Make Changes

  • Follow code style guidelines
  • Write meaningful commit messages
  • Add tests for new features
  • Update documentation

3. Test Your Changes

# Lint
npm run lint

# Type check
npm run type-check

# Format
npm run format

# Test (when available)
npm test

4. Commit

git add .
git commit -m "feat(scope): description"

Husky will automatically:

  • Validate commit message format
  • Run linting
  • Run type checking

5. Push and Create PR

git push -u origin feature/your-feature-name

Then create PR on GitHub following the PR template.

Code Style

TypeScript

  • Use strict TypeScript
  • Explicit return types for functions
  • No any types (use unknown if needed)
  • Prefer interfaces over types for objects

React Components

  • Functional components only
  • Use hooks (no class components)
  • Props destructuring
  • Explicit prop types

File Naming

  • Components: UserCard.tsx (PascalCase)
  • Utilities: formatDate.ts (camelCase)
  • API routes: route.ts (Next.js convention)
  • Types: types.ts or user.types.ts

Code Organization

src/
├── app/              # Next.js App Router
├── components/       # React components
│   ├── ui/          # Reusable UI components
│   └── features/    # Feature-specific components
├── lib/             # Utilities and business logic
├── db/              # Database schema and client
└── types/           # TypeScript type definitions

Commit Message Guidelines

Format

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

<body>

<footer>

Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • style: Formatting, no code change
  • refactor: Code refactoring
  • perf: Performance improvement
  • test: Adding tests
  • chore: Maintenance
  • ci: CI/CD changes

Examples

feat(auth): add two-factor authentication

Implements TOTP-based 2FA using otpauth library.
Users can enable 2FA in account settings.

Closes #123

---

fix(api): resolve race condition in token validation

The token validation endpoint was not properly handling
concurrent requests, leading to duplicate token usage.

Added mutex lock around token checking and updating.

Pull Request Process

Before Creating PR

  • Code follows style guidelines
  • All tests pass
  • No linting errors
  • No TypeScript errors
  • Documentation updated (if needed)
  • Commits follow conventional format

PR Requirements

  1. Title: Clear, descriptive (follows commit format)
  2. Description: Fill out PR template completely
  3. Tests: Include test results or testing steps
  4. Screenshots: For UI changes
  5. Breaking Changes: Clearly documented

Review Process

  1. CI checks must pass (lint, type-check, build)
  2. At least 1 approval required (for main branch)
  3. All conversations must be resolved
  4. Vercel preview deployment must work

After Merge

  • Delete your feature branch
  • Pull latest from develop
  • Start next feature

Testing

Unit Tests (coming soon)

npm test

Integration Tests (coming soon)

npm run test:integration

E2E Tests (coming soon)

npm run test:e2e

Documentation

When to Update Docs

  • Adding new features
  • Changing APIs
  • Modifying workflows
  • Fixing bugs that affect usage

Documentation Types

  • API Docs: docs/api/
  • User Guides: docs/guides/
  • Architecture: docs/architecture/
  • ADRs: docs/adr/

Questions?

  • Check documentation first
  • Review existing PRs
  • Ask in discussions
  • Open an issue

Code of Conduct

Be respectful, professional, and collaborative.

License

By contributing, you agree that your contributions will be licensed under the project's license.