Contributing to Helix

Thank you for your interest in contributing to Helix! Our project is driven by community collaboration, high code quality, and clear documentation. Whether you're fixing bugs, introducing new features, or improving our docs, your contributions make Helix stronger.

Below you'll find guidelines on our Git Flow branching model, commit conventions, pull request workflow, release process, and automated tooling. Please review each section carefully. If you have any questions or need assistance, feel free to join our Discord server or open an issue in our GitHub repo.

Git Flow Branching Model

We follow the standard Git Flow model to organize our work:

• develop: Main integration branch for ongoing work
• master: Stable production branch (releases are tagged here)
• feature/*: New features branched off develop
• bugfix/*: Non-critical fixes branched off develop
• hotfix/*: Critical production fixes branched off master
• docs/*: Documentation updates branched off develop

Legend & Notes

• feature/*: code for new features; branch off develop
• bugfix/*: fixes for non-critical issues; branch off develop
• hotfix/*: urgent fixes; branch off master
• docs/*: documentation improvements; branch off develop

Commit Conventions & Prefixes

We enforce Conventional Commits via CI to maintain a clear changelog:

Allowed Types: feat | fix | docs | style | refactor | perf | test | build | ci | chore | revert | merge

Branch Prefixes:
  feature/*
  bugfix/*
  hotfix/*
  docs/*

Conventional Commits enforced via CI with @commitlint/config-conventional.

Pull Request Process

1. Branch Creation: From develop, create a branch following the prefix guidelines (feature/*, bugfix/*, docs/*).
2. Work and Commit: Make atomic commits with clear messages following Conventional Commits. Run local tests and lint before pushing.
3. Open PR: Open a Pull Request targeting develop. Fill out the PR template, linking relevant issue numbers and providing screenshots or recordings for UI changes.
4. Automated Checks: Ensure all GitHub Actions checks (tests, lint, type checks) pass. CI will enforce commitlint rules and run the test suite.
5. Code Review: Reviewers (automatically assigned) and GitHub Copilot suggestions will provide feedback. Address review comments, push follow-up commits, and await approvals.
6. Merge Strategy: Once approved and all checks pass, squash-and-merge the PR to maintain a clean history. Add a descriptive merge commit message if needed.
7. Post-Merge: After merging, delete the branch in GitHub. The PR will be linked to changelog and future releases via semantic-release.
8. Release Monitoring: Verify the new changes in the develop environment. Prepare any additional hotfix branches from master if urgent issues arise.

Release & Versioning

• No release/* branches: versioning is fully automated.
• semantic-release analyzes merged commits on master to determine the next version according to Conventional Commit types.
• Changesets allow manual release notes and version control for multi-package repos; changeset files are committed alongside features.
• On merge to master, CI pipeline runs semantic-release which publishes to npm, creates GitHub releases, and updates the changelog.
• Tags (vX.Y.Z) are generated automatically and pushed to GitHub, triggering any downstream deployments.
• develop remains the integration branch; hotfixes branched off master are merged back to both develop and master as needed.
• Ensure commit messages on PRs are accurate and descriptive for reliable release notes and changelog entries.

Automated Dependency, Linting & Commit Tooling

• Renovate - automates dependency updates. Groups PRs by major/minor, applies your schedule, and can auto-merge safe upgrades.
• Dependabot - GitHub's built-in security scanner. Generates PRs for vulnerability fixes and keeps your lockfiles up to date.
• Husky + Lint-Staged - pre-commit Git hooks run on staged files to:
  • Run eslint --fix and prettier --write
  • Catch formatting issues before you push
• ESLint - enforces static code analysis rules. We use a shared config plus custom rules to keep code consistent.
• Prettier - code formatting. Plugins sort Tailwind classes, enforce semis, single quotes, print width, etc.
• Commitlint - validates Conventional Commits via @commitlint/config-conventional. Enforced in CI to guarantee a clean, machine-readable changelog.
• TypeScript (strict mode) - full type-safety. No @ts-expect-error allowed without justification.