LaunchPad — 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
Code formatting	Prettier	npm run format
Branch Policy	GitHub Actions	Automatic

⚠️ npm run format is a separate CI job (Frontend Check (format)), not part of npm run lint. Lint and stylelint can both be green while the format gate is red — it has happened. Run all three.

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 && npm run format

Debug logging

src/ never calls console.* directly — everything goes through src/utils/logger.js, which is the app's single console boundary.

logger.warn and logger.error always print. logger.debug is silent by default, because the tracing it carries used to run on every dashboard load in production. Turn it on from the browser console:

localStorage.setItem('launchpad:debug', '1')   // then reload
localStorage.removeItem('launchpad:debug')     // back to quiet

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