Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/davidG97/qa-flow/llms.txt

Use this file to discover all available pages before exploring further.

QA Flow welcomes contributions of all kinds — from bug reports and feature ideas to documentation improvements and code changes. This page explains the branching strategy, commit message format, pull request process, and how releases are created. Reading it before opening your first PR will help your contribution land smoothly.

​
Ways to Contribute

Report a Bug

Open an issue using the Bug Report template. Check existing issues first to avoid duplicates, and include steps to reproduce, expected behaviour, and actual behaviour.

Request a Feature

Open an issue using the Feature Request template. Describe your use case and the behaviour you’d expect — this helps collaborators understand the value before implementation begins.

Submit Code

Find an open issue (or create one), comment to claim it, then follow the PR process below. All code contributions target the main branch.

​
Git Flow

QA Flow uses a simplified fork-based flow where collaborators control all releases. Merging to main does not automatically trigger a release — all releases are created manually. 
CONTRIBUTORS
  Fork → feature/* → PR to main → Review → Merge
                                     ↓
COLLABORATORS
  Review PRs → Merge to main → Manual Release (when ready)
                                     ↓
                     ┌───────────────┴───────────────┐
                     ▼                               ▼
              STABLE (v1.2.0)               BETA (v1.3.0-beta)
              :latest tag                   :beta tag
If you are a first-time contributor, comment on the issue you’d like to work on before starting. This prevents duplicate work and gives collaborators a chance to share any context that might affect your approach.

​
Conventional Commits

QA Flow follows the Conventional Commits specification. Every commit message must start with a type and an optional scope, followed by a short description: 
<type>(<scope>): <description>

[optional body]

[optional footer(s)]

​
Commit Types

TypeDescription
featA new feature
fixA bug fix
docsDocumentation only changes
styleCode style changes (formatting, semicolons, etc.)
refactorCode change that neither fixes a bug nor adds a feature
perfPerformance improvement
testAdding or updating tests
choreMaintenance tasks
ciCI/CD changes

​
Examples

feat(nodes): add new "Scroll" node type
fix(executor): handle timeout errors gracefully
docs(readme): update installation instructions
refactor(api): simplify authentication middleware
Keep the description in the imperative mood (“add feature”, not “added feature”) and under 72 characters. If the change needs more explanation, add a body after a blank line.

​
Pull Request Process

1

Create a branch from main

Always branch from an up-to-date main. Pull the latest changes from upstream before creating your branch to minimise merge conflicts later.
git checkout main
git pull upstream main
git checkout -b feat/your-feature-name
Branch names should follow the pattern <type>/<short-description>, for example feat/scroll-node, fix/timeout-handling, or docs/docker-guide.
2

Make commits using the conventional format

Make small, focused commits as you work. Each commit should represent one logical change and use the conventional commit format described above.
git add .
git commit -m "feat(nodes): add scroll node with direction and distance config"
3

Push to your fork

Push your branch to your fork on GitHub. If you’ve been working for a while, rebase against upstream main first to keep your branch clean.
git push origin feat/your-feature-name
4

Open a Pull Request targeting main

Open a PR from your fork’s branch to davidG97/qa-flow:main. Fill in the PR template completely — describe what changed, why, and how to test it. Link any related issues using GitHub keywords (Closes #123, Fixes #456).
5

Address review feedback and wait for merge

Collaborators will review your PR and may request changes. Push additional commits to your branch to address the feedback — do not force-push after review has started, as it makes the review history harder to follow. Once all feedback is addressed and CI passes, a collaborator will merge the PR.

​
PR Requirements Checklist

Before marking your PR as ready for review, confirm that all of the following are true:
  • All CI checks pass
  • Code follows the style guidelines below
  • Tests have been added or updated where applicable
  • Documentation has been updated if the change affects user-facing behaviour
  • There are no merge conflicts with main

​
Release Process

The release workflow is for collaborators with repository write access only. Merging a PR to main does not automatically publish a release. All releases are triggered manually.
Releases are created through GitHub Actions. Collaborators navigate to Actions → Release → Run workflow and choose two parameters:
1

Go to Actions → Release → Run workflow

2

Select the version bump type

Choose patch, minor, or major based on the nature of changes since the last release (see the version guide below).
3

Leave 'Create as beta' unchecked

4

Click Run workflow

This publishes:
  • A GitHub Release with an auto-generated changelog
  • A Docker image tagged as latest and X.Y.Z
  • An npm package at version X.Y.Z

​
Version Bump Guide

TypeWhen to useExample
patchBug fixes and small changes with no new features1.0.0 → 1.0.1
minorNew features that are backwards compatible1.0.1 → 1.1.0
majorBreaking changes to existing behaviour or APIs1.1.0 → 2.0.0

​
Style Guidelines

Consistent code style makes the codebase easier to read and review. The following conventions are enforced or expected across the project:
  • Use TypeScript for all new code — no plain .js files in src/ or server/src/
  • Enable and respect strict mode ("strict": true in tsconfig.json)
  • Prefer interface over type for describing object shapes
  • Use meaningful, self-documenting variable names — avoid abbreviations
  • Use .js extensions on local imports in the backend (NodeNext module resolution requires this even for .ts source files)
  • Use functional components with hooks — no class components
  • Wrap node components in memo() to prevent unnecessary React Flow re-renders
  • Keep components small and focused on a single responsibility
  • Extract reusable stateful logic into custom hooks in src/hooks/
  • Avoid prop drilling — use context or custom hooks for cross-component state
  • Follow the existing controller → service pattern: controllers handle HTTP parsing and response, services contain business logic
  • Export singleton service objects rather than classes that callers must instantiate
  • Keep route files thin — only router.get(...) and router.post(...) calls, no logic
  • Use CSS variables for all colours and spacing values — avoid hardcoded hex codes or pixel values
  • Follow BEM-like naming conventions for class names (.block__element--modifier)
  • Keep styles in module-level files co-located with their component

​
Code of Conduct

This project is governed by the Contributor Covenant Code of Conduct. All participants are expected to maintain a welcoming, respectful, and inclusive environment. Harassment, personal attacks, and discriminatory language are not tolerated in any community space — issues, PRs, discussions, or otherwise.

Build docs developers (and LLMs) love

Get started for freeTalk to us