> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soundchecklive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> Guidelines for contributing to Soundcheck

This guide covers how to contribute to the Soundcheck project.

## Getting Started

**1. Fork the repository**

Create a fork of the repository on GitHub.

**2. Clone your fork**

```bash theme={null}
git clone https://github.com/YOUR_USERNAME/soundcheck-mobile-app
cd soundcheck-mobile-app
```

**3. Set up upstream**

```bash theme={null}
git remote add upstream https://github.com/soundchecklive/soundcheck-mobile-app
```

**4. Install dependencies**

```bash theme={null}
npm install
```

***

## Branching Strategy

### Branch Naming

| Prefix | Purpose | Example |
| - | - | - |
| `feature/` | New features | `feature/add-setlist-export` |
| `fix/` | Bug fixes | `fix/login-redirect` |
| `refactor/` | Code refactoring | `refactor/event-service` |
| `docs/` | Documentation | `docs/api-guide` |

### Branch Flow

```
feature/your-feature
     │
     └──► dev ──► qa ──► main (prod)
```

***

## Development Workflow

**1. Create a feature branch**

```bash theme={null}
git checkout dev
git pull upstream dev
git checkout -b feature/your-feature
```

**2. Make your changes**

Write code following the project conventions.

**3. Run quality checks**

```bash theme={null}
npm run check-all
```

**4. Commit your changes**

```bash theme={null}
git add .
git commit -m "feat: add your feature description"
```

**5. Push and create PR**

```bash theme={null}
git push origin feature/your-feature
```

Open a pull request targeting `dev`.

***

## Commit Messages

Follow [Conventional Commits](https://www.conventionalcommits.org/):

| Type | Description |
| - | - |
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation only |
| `style` | Formatting, no code change |
| `refactor` | Code change that neither fixes nor adds |
| `test` | Adding tests |
| `chore` | Maintenance tasks |

### Examples

```bash theme={null}
feat: add Apple Sign In to login screen
fix: resolve OAuth redirect issue on Android
docs: update API authentication guide
refactor: extract event validation to separate module
```

***

## Code Style

### TypeScript

* Strong typing required (avoid `any`)
* Use interfaces for object shapes
* Use types for unions and utilities

### React

* Functional components with hooks
* Memoize expensive computations
* Keep components focused and small

### Imports

Group imports in order:

```tsx theme={null}
// 1. External libraries
import React, { useState } from 'react';
import { View } from 'react-native';

// 2. Internal aliases (@/)
import { Button } from '@/components/ui';
import { useAuth } from '@/lib/context/AuthContext';

// 3. Relative imports
import { MyComponent } from './MyComponent';
```

***

## Pre-Commit Hooks

Husky runs automatically on `git commit`:

* **TypeScript** type checking
* **oxlint** on staged files
* **oxfmt** on staged files
* **Whitespace** error detection
* **TypeScript checks** on staged files (mobile, web, api-events, mcp-ts, …)

To bypass in emergencies:

```bash theme={null}
git commit --no-verify
```

***

## Pull Request Guidelines

### PR Title

* Use conventional commit format
* Keep under 72 characters
* Be descriptive

### PR Description

Include:

* What changes were made
* Why the changes were made
* How to test the changes
* Screenshots for UI changes

### Review Process

1. Open PR targeting `dev`
2. Wait for CI checks to pass
3. Request review from team members
4. Address feedback
5. Merge when approved

***

## Testing

### Mobile

```bash theme={null}
npm run type-check
npm run lint
```

### Web

```bash theme={null}
cd web
npm run typecheck
npm run lint
npm test
```

### API (api-events)

```bash theme={null}
cd api-events
npm run checks   # typecheck + lint + test:coverage
npm test         # unit tests only
```

### MCP server (mcp-ts)

```bash theme={null}
cd mcp-ts
npm run typecheck
npm test
```

***

## Documentation

* Update docs when adding features
* Keep README files current
* Add JSDoc comments for complex functions

***

## Need Help?

* Create an issue for bugs or questions
* Check existing issues before creating new ones
* Join team discussions for architectural decisions


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.