Integrate automattic/jetpack-changelogger for changelog management

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Description
+
+<!-- Describe the changes in this PR -->
+
+## Related Issues
+
+<!-- Link any related issues: Fixes #123 -->
+
+## Testing
+
+<!-- Describe how you tested this change -->
+
+## Changelog
+
+- [ ] Added a changelog entry via `composer changelog:add`
+  - **Significance**: `patch` (bug fix) / `minor` (new feature) / `major` (breaking change)
+  - **Type**: `added` / `changed` / `deprecated` / `removed` / `fixed` / `security`
+
+<!-- If this PR does not need a changelog entry (e.g. docs, CI, tests only), the changelog-check workflow will be skipped automatically when only those files are changed. -->

.github/actions/build-plugin/action.yml

@@ -11,7 +11,7 @@ runs:
 
     - name: Cache Composer packages
       id: composer-cache
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       with:
         path: vendor
         key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
@@ -23,7 +23,7 @@ runs:
         composer install --no-dev --prefer-dist --no-progress
       shell: bash
 
-    - uses: actions/setup-node@v3
+    - uses: actions/setup-node@v4
       with:
         node-version-file: '.nvmrc'
         cache: 'npm'

.github/workflows/changelog-check.yml

@@ -0,0 +1,66 @@
+name: Changelog Check
+
+on:
+  pull_request:
+    branches:
+      - master
+      - 'release/**'
+    paths-ignore:
+      # Changelog files themselves
+      - 'changelog/**'
+      - 'CHANGELOG.md'
+      # Documentation
+      - '**.md'
+      - '**.txt'
+      - 'languages/**'
+      # CI / tooling config (no user impact)
+      - '.github/**'
+      - '.editorconfig'
+      - '.gitignore'
+      - '.phpcs.xml.dist'
+      - '.wp-env.json'
+      - 'phpunit.xml.dist'
+      - 'Gruntfile.js'
+      - 'composer.json'
+      - 'composer.lock'
+      - 'package.json'
+      - 'package-lock.json'
+      # Tests
+      - 'tests/**'
+
+jobs:
+  changelog:
+    name: Validate changelog entry
+    runs-on: ubuntu-20.04
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+
+      - name: Cache Composer packages
+        uses: actions/cache@v4
+        with:
+          path: vendor
+          key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-php-
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --ignore-platform-reqs
+
+      - name: Validate changelog entry exists
+        run: |
+          # Check that at least one changelog entry file was added in this PR
+          git fetch origin ${{ github.base_ref }}
+          CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- changelog/)
+          if [ -z "$CHANGED" ]; then
+            echo "::error::No changelog entry found. Please add a changelog entry in the changelog/ directory using:"
+            echo "::error::  composer changelog:add"
+            exit 1
+          fi
+
+      - name: Validate changelog entries
+        run: composer changelog:validate

.github/workflows/release.yml

@@ -8,9 +8,48 @@ jobs:
   publish:
     name: New Release
     runs-on: ubuntu-20.04
+    permissions:
+      contents: write
     steps:
 
     - uses: actions/checkout@v4
+      with:
+        # Full history needed for changelogger to determine the previous tag
+        fetch-depth: 0
+
+    - uses: shivammathur/setup-php@v2
+      with:
+        php-version: '8.2'
+
+    - name: Install Composer dependencies
+      run: composer install --prefer-dist --no-progress --ignore-platform-reqs
+
+    - name: Write changelog
+      # Collapses all changelog/ entry files into CHANGELOG.md for this release
+      run: composer changelog:write -- --yes --default-first-version
+
+    - name: Extract release notes for this version
+      id: release_notes
+      run: |
+        # Pull out the section for the tag that was just published (e.g. "2.9.1")
+        VERSION="${{ github.event.release.tag_name }}"
+        VERSION="${VERSION#v}"   # strip leading 'v' if present
+        NOTES=$(awk "/^## \[${VERSION}\]/{found=1; next} found && /^## \[/{exit} found{print}" CHANGELOG.md)
+        # Write to a temp file to avoid shell quoting issues
+        echo "$NOTES" > /tmp/release_notes.md
+        echo "notes_file=/tmp/release_notes.md" >> "$GITHUB_OUTPUT"
+
+    - name: Update GitHub release body with changelog
+      env:
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: |
+        gh release edit "${{ github.event.release.tag_name }}" \
+          --notes-file "${{ steps.release_notes.outputs.notes_file }}"
+
+    - name: Commit updated CHANGELOG.md
+      uses: elstudio/actions-js-build/commit@v4
+      with:
+        commitMessage: "Update CHANGELOG.md for ${{ github.event.release.tag_name }}"
 
     - uses: ./.github/actions/build-plugin
 

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to Commons Booking will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+[Unreleased]: https://github.com/datengraben/commonsbooking/compare/v2.9...HEAD

CONTRIBUTING.md

@@ -0,0 +1,217 @@
+# Contributing to CommonsBooking
+
+Thank you for taking the time to contribute! This document covers everything you need to go from a fresh clone to a submitted pull request.
+
+---
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Quick Start](#quick-start)
+- [Local Development](#local-development)
+- [Running Tests](#running-tests)
+- [Code Standards](#code-standards)
+- [Changelog Entries](#changelog-entries)
+- [Submitting a Pull Request](#submitting-a-pull-request)
+- [Building the Plugin ZIP](#building-the-plugin-zip)
+
+---
+
+## Prerequisites
+
+| Tool | Minimum version | Notes |
+|---|---|---|
+| PHP | 7.4 | With [uopz](https://www.php.net/manual/en/book.uopz.php) extension for tests |
+| Composer | 2.x | |
+| Node.js | 20.x | Use `nvm use` — version pinned in `.nvmrc` |
+| Docker | Latest stable | Required by `wp-env` |
+| @wordpress/env | bundled | Installed via `npm ci` |
+
+---
+
+## Quick Start
+
+```bash
+# 1. Clone and install all dependencies + build assets
+git clone https://github.com/datengraben/commonsbooking
+cd commonsbooking
+npm run start
+
+# 2. Start the local WordPress environment (requires Docker)
+npm run env:start
+
+# 3. Open WordPress in your browser
+#    Site:  http://localhost:1000   (admin / password)
+#    Tests: http://localhost:1001
+```
+
+The `.wp-env.json` pre-installs several useful development plugins (Query Monitor, WP Crontrol, WP Mail Logging) and activates the Kasimir theme.
+
+> **Custom configuration**: create a `.wp-env.override.json` for local overrides (e.g. a different port or extra plugins). This file is gitignored.
+
+---
+
+## Local Development
+
+### Install dependencies
+
+```bash
+# PHP dependencies
+composer install --ignore-platform-reqs
+
+# Node dependencies (use --legacy-peer-deps to match CI)
+npm ci --legacy-peer-deps
+
+# Compile assets (SCSS → CSS, JS bundles)
+npm run dist
+```
+
+### Start / stop the environment
+
+```bash
+npm run env:start   # starts WordPress at http://localhost:1000
+npm run env:stop    # shuts it down
+```
+
+`env:start` also installs WP-CLI inside the test container, which is needed for E2E test setup.
+
+### Activate the development theme via WP-CLI
+
+```bash
+npm run env run cli wp theme activate kasimir-theme
+```
+
+### Watching assets during development
+
+```bash
+npm run dist        # one-off build
+# (no watch task is wired up yet — contributions welcome!)
+```
+
+---
+
+## Running Tests
+
+### PHP Unit Tests
+
+The test suite requires a WordPress test database. `bin/install-wp-tests.sh` sets it up automatically against the wp-env MySQL container.
+
+**1. Find the database port** — it is printed when you run `npm run env:start`:
+
+```
+ℹ︎ MySQL port: 49153   ← use this in the next step
+```
+
+**2. Set up the test database:**
+
+```bash
+bash bin/install-wp-tests.sh wordpress root '' 127.0.0.1:<PORT> latest
+```
+
+**3. Run the tests:**
+
+```bash
+composer test
+```
+
+This runs `composer dump-autoload -o` then `phpunit` using the `phpunit.xml.dist` configuration. Code coverage reports are written to `build/logs/`.
+
+### E2E Tests (Cypress)
+
+```bash
+# Environment must already be running
+npm run env:start
+
+# Import the test fixture data (only needed once per environment)
+npm run cypress:setup
+
+# Run headlessly
+npm run cypress:run
+
+# Open the interactive Cypress UI
+npm run cypress:open
+```
+
+Screenshots from failed runs are saved to `tests/cypress/screenshots/`.
+
+---
+
+## Code Standards
+
+The project follows [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/). The ruleset is in `.phpcs.xml.dist`.
+
+```bash
+# Check for violations
+composer lint
+
+# Auto-fix fixable violations
+composer lint:fix
+```
+
+Results are cached in `.cache-phpcs-free.cache` (gitignored) so re-runs are fast.
+
+---
+
+## Changelog Entries
+
+Every PR that changes **user-facing behaviour** (new features, bug fixes, UI changes) needs a changelog entry. Pure tooling, test, CI, or documentation PRs are exempt.
+
+```bash
+composer changelog:add
+```
+
+This launches an interactive wizard:
+
+| Prompt | Options |
+|---|---|
+| Significance | `patch` (bug fix), `minor` (new feature), `major` (breaking change) |
+| Type | `added`, `changed`, `deprecated`, `removed`, `fixed`, `security` |
+| Entry | A short sentence describing the change for end users |
+
+The wizard creates a file in `changelog/`. Commit it with your PR. The CI will validate it.
+
+To preview how all pending entries will look when collapsed:
+
+```bash
+composer changelog:write --dry-run
+```
+
+---
+
+## Submitting a Pull Request
+
+1. **Fork** the repository and create a branch from `master`:
+   ```bash
+   git checkout -b fix/description-of-fix
+   # or
+   git checkout -b feature/description-of-feature
+   ```
+
+2. **Make your changes.** Keep PRs focused on one concern.
+
+3. **Run the checks locally** before pushing:
+   ```bash
+   composer lint
+   composer test
+   ```
+
+4. **Add a changelog entry** if your change is user-facing:
+   ```bash
+   composer changelog:add
+   ```
+
+5. **Push and open a PR** against the `master` branch. Fill in the PR template — it has a short checklist to make sure nothing is missed.
+
+The CI will run PHP unit tests (PHP 7.4 + 8.2), E2E tests across multiple WordPress versions, and validate your changelog entry.
+
+---
+
+## Building the Plugin ZIP
+
+To produce a production-ready zip (e.g. for manual upload to a staging site):
+
+```bash
+bin/build-zip.sh
+```
+
+The zip is built into `build/` and excludes development files listed in `.distignore`.