# Contributing to The Order

Thank you for your interest in contributing to The Order! This document provides guidelines and instructions for contributing.

## Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.

## Getting Started

1. Fork the repository
2. Clone your fork: `git clone https://github.com/your-username/the-order.git`
3. Create a branch: `git checkout -b feature/your-feature-name`
4. Install dependencies: `pnpm install`
5. Make your changes
6. Test your changes: `pnpm test && pnpm lint`
7. Commit your changes (see [Commit Guidelines](#commit-guidelines))
8. Push to your fork: `git push origin feature/your-feature-name`
9. Open a Pull Request

## Development Setup

### Prerequisites

- Node.js >= 18.0.0
- pnpm >= 8.0.0
- Docker (for local services)
- Git

### Local Development

```bash
# Install dependencies
pnpm install

# Start development servers
pnpm dev

# Run tests
pnpm test

# Run linting
pnpm lint

# Type check
pnpm type-check
```

### Environment Setup

1. Copy `.env.example` to `.env.local` in the workspace you're working on
2. Configure required environment variables
3. For secrets, use SOPS (see [Security Policy](SECURITY.md))

## Commit Guidelines

We use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages:

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

<body>

<footer>
```

### Types

- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting, etc.)
- `refactor`: Code refactoring
- `test`: Test additions or changes
- `chore`: Build process or auxiliary tool changes
- `perf`: Performance improvements
- `ci`: CI/CD changes
- `revert`: Revert a previous commit

### Examples

```
feat(auth): add OIDC provider support

Implement OAuth2/OIDC flow with support for multiple providers.
Adds configuration for eIDAS integration.

Closes #123
```

```
fix(intake): resolve OCR parsing issue with PDFs

Fixes character encoding problems when processing multi-page PDFs.
Adds proper error handling for corrupted documents.

Fixes #456
```

## Pull Request Process

1. **Update Documentation**: Update relevant documentation for your changes
2. **Add Tests**: Include tests for new features or bug fixes
3. **Update Changelog**: Add entry to CHANGELOG.md (if applicable)
4. **Ensure Tests Pass**: All CI checks must pass
5. **Request Review**: Request review from relevant code owners (see CODEOWNERS)

### PR Title Format

Use the same format as commit messages:

```
feat(scope): brief description
```

### PR Description Template

```markdown
## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
How was this tested?

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] All tests pass
- [ ] No new warnings
```

## Code Style

### TypeScript

- Use strict TypeScript configuration
- Prefer type over interface for unions/intersections
- Use explicit return types for public functions
- Avoid `any` type

### Formatting

- Use Prettier for code formatting
- Run `pnpm format` before committing
- ESLint rules must pass

### Naming Conventions

- Variables: `camelCase`
- Functions: `camelCase`
- Classes: `PascalCase`
- Constants: `UPPER_SNAKE_CASE`
- Files: `kebab-case` for utilities, `PascalCase` for components

## Testing

### Unit Tests

- Write unit tests for all new features
- Aim for >80% code coverage
- Use descriptive test names
- Follow AAA pattern (Arrange, Act, Assert)

### Integration Tests

- Write integration tests for API endpoints
- Test error cases and edge cases
- Use test fixtures from `packages/test-utils`

### E2E Tests

- E2E tests for critical user flows
- Use Playwright or similar framework
- Run in CI/CD pipeline

## Documentation

### Code Documentation

- Document all public APIs
- Use JSDoc for functions and classes
- Include examples for complex usage

### Architecture Documentation

- Update ADRs for significant architectural decisions
- Document new services in `docs/architecture/`
- Update data flow diagrams if applicable

## Code Review

### For Authors

- Keep PRs focused and small
- Respond to feedback promptly
- Be open to suggestions
- Update PR based on feedback

### For Reviewers

- Be constructive and respectful
- Focus on code, not the person
- Suggest improvements, don't just point out issues
- Approve when satisfied

## Release Process

1. Create release branch from `main`
2. Update version numbers
3. Update CHANGELOG.md
4. Create release PR
5. After approval, tag release
6. CI/CD automatically deploys

## Questions?

- Open an issue for questions
- Check existing documentation
- Ask in discussions

## Additional Resources

- [Architecture Documentation](docs/architecture/README.md)
- [Security Policy](SECURITY.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)

