Dossiq: 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

npm ci registers the l10n merge driver for you. In a clone that already installed, register it by hand:

git config merge.l10n.name 'l10n catalogue key-wise merge'
git config merge.l10n.driver 'node tools/merge-l10n.js %O %A %B %P'

Without it, l10n/en.json and l10n/nl.json merge line by line and every branch that adds a string conflicts with every other one. See the merge driver page.

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