# Contributing Guidelines

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

## Code of Conduct

Be respectful and constructive. Treat all contributors with courtesy.

## Getting Started

### Prerequisites

- Node.js 20+
- npm 10+
- Gitleaks (for secret scanning)

### Setup

1. Fork the repository
2. Clone your fork
3. Install dependencies:

```bash
npm install
cd backend && npm install && cd ..
```

4. Install Gitleaks (for pre-commit hooks):

```bash
# macOS
brew install gitleaks

# Linux
curl -sSfL https://github.com/gitleaks/gitleaks/releases/latest/download/gitleaks_linux_x64.tar.gz | tar -xz
sudo mv gitleaks /usr/local/bin/
```

## Development Workflow

### Branch Naming

- `feat/feature-name` - New features
- `fix/bug-name` - Bug fixes
- `docs/topic` - Documentation changes
- `refactor/component` - Code refactoring
- `test/test-name` - Test additions/changes

### Commit Guidelines

This project uses [Conventional Commits](https://www.conventionalcommits.org/):

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

[optional body]

[optional footer]
```

#### Types

| Type | Description | Version Impact |
|------|-------------|----------------|
| `feat` | New feature | Minor |
| `fix` | Bug fix | Patch |
| `perf` | Performance improvement | Patch |
| `revert` | Revert previous commit | Patch |
| `docs` | Documentation only | None |
| `style` | Code style (formatting) | None |
| `refactor` | Code refactoring | None |
| `test` | Adding/updating tests | None |
| `build` | Build system changes | None |
| `ci` | CI/CD changes | None |
| `chore` | Maintenance tasks | None |

#### Scopes

| Scope | Description |
|-------|-------------|
| `admin` | Admin panel components |
| `api` | Backend API |
| `ui` | Frontend UI components |
| `docker` | Docker configuration |
| `ci` | CI/CD workflows |
| `deps` | Dependencies |
| `release` | Release configuration |
| `auth` | Authentication |

#### Examples

```bash
feat(admin): add export to PDF functionality
fix(api): resolve JWT token expiration issue
docs(readme): update installation instructions
ci(workflow): add staging deployment
```

### Pre-commit Hooks

The project uses Husky for git hooks:

- **pre-commit**: Runs ESLint and Gitleaks secret scanning
- **commit-msg**: Validates commit message format with commitlint

### Code Style

- ESLint configuration is enforced
- Run `npm run lint` before committing
- Fix issues with `npm run lint -- --fix`

### Testing

Run tests before submitting:

```bash
# Unit tests
npm run test:run

# Integration tests
npm run test:integration

# E2E tests (requires running server)
npm run test:e2e

# All tests with coverage
npm run test:coverage
```

## Pull Request Process

1. Create a feature branch from `master`
2. Make your changes following the guidelines above
3. Ensure all tests pass
4. Ensure lint passes (`npm run lint`)
5. Ensure build succeeds (`npm run build`)
6. Push to your fork and create a pull request
7. Fill out the PR template completely
8. Wait for review

### PR Checklist

- [ ] Follows contributing guidelines
- [ ] Commit messages follow conventional commits
- [ ] Lint passes (`npm run lint`)
- [ ] Tests pass (`npm run test:run`)
- [ ] Build succeeds (`npm run build`)
- [ ] Documentation updated if needed

## Release Process

Releases are automated via semantic-release:

1. Merge PR to `master`
2. CI runs tests and build
3. semantic-release analyzes commits
4. Version bumped, changelog updated
5. Git tag and release created

No manual release steps required.

## Questions?

Open an issue for questions or discussions about contributions.