Pipelinq: Developer Guide

Branching Strategy

This project follows a strict promotion-based branching model. Code flows upward through environments, and each branch has rules about which source branches it accepts.

feature/* → development → beta → main
hotfix/*  → (any branch)

Branch Roles

Branch	Purpose	Accepts PRs from
main	Production-ready releases	beta, hotfix/*
beta	Pre-release testing and stabilisation	development, hotfix/*
development	Integration of completed features	feature/*, hotfix/*
feature/*	Individual feature work	Created from development
hotfix/*	Urgent production fixes	Created from main, merged into any branch

Flow Diagram

Branch Policy Enforcement

A Branch Policy Check runs on every PR to main, beta, and development. It automatically blocks PRs from unauthorised source branches:

• PR to main from feature/x → blocked
• PR to main from beta → allowed
• PR to beta from feature/x → blocked
• PR to beta from development → allowed
• PR to development from some-random-branch → blocked
• PR to development from feature/x → allowed
• PR to any branch from hotfix/x → always allowed

Working with Hotfixes

Hotfixes bypass the normal promotion flow for urgent production issues:

1. Create hotfix/description from main
2. Implement and test the fix
3. Open PRs to main, beta, and development (to keep all branches in sync)

Quality Checks

All PRs to main, beta, and development must pass these blocking checks before merge:

Check	Tool	Command
PHP Lint	php -l	composer lint
PHP Coding Standards	PHPCS (Conduction standard)	composer phpcs
PHP Mess Detection	PHPMD	composer phpmd
PHP Code Metrics	phpmetrics (informational)	composer phpmetrics
ESLint + Stylelint	ESLint + Stylelint	npm run lint && npm run stylelint
Branch Policy	GitHub Actions	Automatic

Running Quality Checks Locally

Before pushing, run all checks locally to catch issues early:

# PHP checks
composer phpcs          # Coding standards (auto-fix: composer cs:fix)
composer phpmd          # Mess detection
composer phpmetrics     # Code metrics report

# Frontend checks
npm run lint && npm run stylelint

Auto-fixing

PHPCS can automatically fix many coding standard violations:

composer cs:fix         # Auto-fix what PHPCBF can handle (~60% of issues)

Getting Started

Prerequisites

• PHP 8.1+
• Composer 2.x
• Node.js 20+
• npm

Setup

# Install PHP dependencies
composer install

# Install frontend dependencies
npm ci

# Run the app in development mode
npm run dev

Creating a New Feature

# Start from development
git checkout development
git pull origin development

# Create your feature branch
git checkout -b feature/my-feature

# ... implement, commit, push ...
git push -u origin feature/my-feature

# Open a PR to development

Local Mail Integration (Greenmail)

Pipelinq's workflow triggers and notifications can be demoed locally against the Greenmail container that ships with the OpenRegister dev stack.

Seed test data:

bash ../openregister/docker/mail/seed-mail.sh

This sends 11 realistic Dutch case-management emails (omgevingsvergunning, kapvergunning, welstandsadvies, klachten, deadline-herinneringen) across 5 auto-created accounts, all explicitly tagged as procest/pipelinq-relevant scenarios.

Configure the Nextcloud Mail app (Settings → Mail → Add account → Manual):

Setting	Value
IMAP host	greenmail (from container) or localhost (from host)
IMAP port	3143
SMTP host	same as IMAP
SMTP port	3025
Security	None
Username	email address (e.g. behandelaar@test.local)
Password	same as username

Accounts created by the seed: admin@test.local, behandelaar@test.local, coordinator@test.local, burger@test.local, leverancier@test.local.