Thematiq — 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
Stylelint	Stylelint	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 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 or later, with npm, for npm ci and npm run build
• Node.js 22.14 or later, or 24, for the test and lint tooling (Vitest, ESLint) — the versions package.json declares under engines

Setup

# Install PHP dependencies
composer install

# Install frontend dependencies
npm ci

# Build the fonts, the icons and the code editor
npm run build

The code editor bundle

Almost everything under js/ is hand-written and served as it is, without a build step. The one exception is the code editor of the playground's "Your components" tab: the HTML and CSS fields are CnJsonViewer, the CodeMirror editor from @conduction/nextcloud-vue. A browser cannot load that Vue component from node_modules, so npm run build:code-editor (part of npm run build) bundles src/codeEditor.js with webpack, as the other Conduction apps build, into js/vendor/codeEditor.js.

• The release workflow runs npm ci and npm run build, so every release and App Store package contains the bundle.
• js/vendor/ is gitignored. In a git checkout the bundle exists only after you built it. Without it the admin page still works: the two fields are plain text areas.
• Run npm run build:code-editor again after updating @conduction/nextcloud-vue. A language the installed CnJsonViewer supports is highlighted from then on; one it does not support yet is shown as plain text.

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