# Contributing to Helix

Thanks for your interest in contributing! Helix is open source under the
[MIT licence](LICENCE). This guide explains how to set up your environment,
make changes and get them merged.

## Getting started

1. Fork the repository and clone your fork.
2. Install the prerequisites:
   - Backend: JDK 21 and the Gradle wrapper (bundled in `server/`)
   - Frontend: Node.js 22+ and [pnpm](https://pnpm.io/)
   - Optional: Docker + Docker Compose for the full-stack run
3. Follow the [Quick start](README.md#quick-start) in the README to run the app
   locally.

## Development workflow

- Create a feature branch from `main`, using a short prefix for clarity:
  `feat/`, `fix/`, `refactor/`, `chore/` or `docs/` (e.g. `feat/role-audit-log`).
- Keep pull requests small and focused on a single concern.
- Write or update tests for the code you touch.
- Open a pull request against `main` and describe what changed and why.

## Code style

The full conventions are documented in [AGENTS.md](AGENTS.md). The essentials:

**Backend (`server/`)**

- Follow the `Controller → Service → Manager → Repository` layering.
- Use the custom validation framework for input validation.
- Throw `BizException` with a `MessageName` constant and add the message key to
  every bundle under `src/main/resources/i18n`.
- Add Flyway migrations for schema changes under `src/main/resources/db/migrations/`.
- Run `./gradlew build` before opening a PR.

**Frontend (`web/`)**

- Use ESLint and Prettier formatting; run `pnpm lint`.
- Keep API clients in `src/api` and state in Redux Toolkit slices.
- Never commit local `.env` files.

## Commit messages

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

```
feat: support TOTP multi-factor authentication
fix: resolve department name uniqueness check
refactor: extract build cookie
docs: update deployment guide
chore(deps): upgrade spring boot to 3.5.4
```

## Reporting issues

When opening an issue, include:

- What you expected to happen and what actually happened
- Steps to reproduce
- Environment details (OS, Java/Node versions, deployment mode)

Security issues: please report them privately to the maintainers rather than
opening a public issue.

## License

By contributing, you agree that your contributions are licensed under the
[MIT licence](LICENCE).