Contributing to Helix

Thanks for your interest in contributing! Helix is a quick-start boilerplate for custom development, open source under the MIT licence. This guide explains how to set up your environment, make changes and get them merged.

What to contribute

Contributions should make the boilerplate itself more useful to everyone who forks it:

New or improved baseline capabilities (reusable, not business-specific)
Bug fixes and hardening
Documentation and tests

Changes that encode one particular organisation's custom rules are usually better kept in your own fork. If you are not sure whether something belongs in the boilerplate, open an issue first and ask.

Getting started

Fork the repository and clone your fork.
Install the prerequisites:
- Backend: JDK 21 and the Gradle wrapper (bundled in server/)
- Frontend: Node.js 22+ and pnpm
- Optional: Docker + Docker Compose for the full-stack run
Follow the 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. 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:

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.

2.8 KiB Raw Permalink Blame History