From dff980647fa3eca44ea75ece4419f66ebc3cfbb6 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 14 Apr 2026 07:36:44 +0000 Subject: [PATCH 1/3] Integrate automattic/jetpack-changelogger for changelog management Adds the WooCommerce/Automattic changelogger workflow so contributors submit individual change files per PR instead of editing a shared CHANGELOG.md, avoiding merge conflicts at release time. - Add `automattic/jetpack-changelogger ^6.0` to require-dev - Configure changelogger in composer.json extra (keepachangelog format, semver versioning, GitHub compare link template) - Add composer scripts: changelog:add, changelog:validate, changelog:write - Create changelog/ directory (with .gitkeep) for per-PR change files - Create initial CHANGELOG.md seeded at v2.9 - Add .github/workflows/changelog-check.yml to validate entries on PRs - Add .github/PULL_REQUEST_TEMPLATE.md with changelog checklist reminder Developer workflow: composer changelog:add # interactive wizard per PR composer changelog:validate # run in CI composer changelog:write # collapse entries at release time https://claude.ai/code/session_01P1DDnvRKzHdx7jepeTf3ju --- .github/PULL_REQUEST_TEMPLATE.md | 19 +++++++++++ .github/workflows/changelog-check.yml | 49 +++++++++++++++++++++++++++ CHANGELOG.md | 9 +++++ changelog/.gitkeep | 0 composer.json | 26 +++++++++++++- 5 files changed, 102 insertions(+), 1 deletion(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/workflows/changelog-check.yml create mode 100644 CHANGELOG.md create mode 100644 changelog/.gitkeep diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..a7265bdeb --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,19 @@ +## Description + + + +## Related Issues + + + +## Testing + + + +## 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` + + diff --git a/.github/workflows/changelog-check.yml b/.github/workflows/changelog-check.yml new file mode 100644 index 000000000..4073a01b5 --- /dev/null +++ b/.github/workflows/changelog-check.yml @@ -0,0 +1,49 @@ +name: Changelog Check + +on: + pull_request: + branches: + - master + - 'release/**' + paths-ignore: + - 'changelog/**' + - 'CHANGELOG.md' + - '**.md' + - '**.txt' + +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 diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 000000000..90f430b94 --- /dev/null +++ b/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 diff --git a/changelog/.gitkeep b/changelog/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/composer.json b/composer.json index fbb8b19b0..422878fc7 100644 --- a/composer.json +++ b/composer.json @@ -54,6 +54,30 @@ "wp-coding-standards/wpcs": "^2.3", "phpcompatibility/phpcompatibility-wp": "^2.1.4", "slope-it/clock-mock": "^0.4.0", - "phpunit/php-code-coverage": "^7.0.15" + "phpunit/php-code-coverage": "^7.0.15", + "automattic/jetpack-changelogger": "^6.0" + }, + "scripts": { + "changelogger": "changelogger", + "changelog:add": "changelogger add", + "changelog:validate": "changelogger validate", + "changelog:write": "changelogger write" + }, + "extra": { + "changelogger": { + "changelog": "CHANGELOG.md", + "changes-dir": "changelog", + "link-template": "https://github.com/datengraben/commonsbooking/compare/v${old}...v${new}", + "versioning": "semver", + "formatter": "keepachangelog", + "types": { + "added": "Added", + "changed": "Changed", + "deprecated": "Deprecated", + "removed": "Removed", + "fixed": "Fixed", + "security": "Security" + } + } } } From 5cc4f3ad9e4fd1bd99b109819bf8ba09f4d62e1c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 14 Apr 2026 07:47:30 +0000 Subject: [PATCH 2/3] Improve changelogger GitHub release integration and paths-ignore scope MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - release.yml: run changelog:write on publish, extract the new version's notes from CHANGELOG.md, and backfill the GitHub release body via `gh release edit`; also commit the updated CHANGELOG.md back to the branch so the repo stays in sync - changelog-check.yml: expand paths-ignore so PRs that only touch tests, CI config, tooling (composer.json, Gruntfile, etc.) or language files are not required to include a changelog entry — only user-facing src/ template/asset changes trigger the requirement https://claude.ai/code/session_01P1DDnvRKzHdx7jepeTf3ju --- .github/workflows/changelog-check.yml | 17 ++++++++++++ .github/workflows/release.yml | 39 +++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) diff --git a/.github/workflows/changelog-check.yml b/.github/workflows/changelog-check.yml index 4073a01b5..62562705d 100644 --- a/.github/workflows/changelog-check.yml +++ b/.github/workflows/changelog-check.yml @@ -6,10 +6,27 @@ on: - 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: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 94449b658..3f32700d3 100644 --- a/.github/workflows/release.yml +++ b/.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 From 6158c7e8f2ff254061a6233bb5ffdfc61640ea85 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 14 Apr 2026 07:57:57 +0000 Subject: [PATCH 3/3] Improve contributor experience and local dev workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a comprehensive CONTRIBUTING.md and fixes several friction points that made it harder for new contributors to set up, test, and submit changes. CONTRIBUTING.md (new): - Prerequisites table (PHP, Composer, Node, Docker) - Quick start with wp-env credentials (admin/password) - Correct step-by-step PHP unit test setup (DB port discovery → composer test) - E2E test workflow - Code standards section (composer lint / lint:fix) - Changelog entry guide with significance/type table - Branch naming, pre-PR checklist, and CI overview composer.json: - Add `lint` script (phpcs via .phpcs.xml.dist) - Add `lint:fix` script (phpcbf) - Add `test` script (dump-autoload + phpunit) package.json: - Fix `start` script to use `npm ci --legacy-peer-deps` (matches CI) - Add `lint:php`, `lint:php:fix`, `test:php` proxy scripts into composer Readme.md: - Remove "only works with manually downloaded phar" outdated note - Replace manual PHPUnit invocation with `composer test` - Add wp-env login credentials - Add `composer lint` to the development section - Link to CONTRIBUTING.md from the Contribute section .github/actions/build-plugin/action.yml: - Upgrade actions/cache v3 → v4 - Upgrade actions/setup-node v3 → v4 (matches all other workflows) https://claude.ai/code/session_01P1DDnvRKzHdx7jepeTf3ju --- .github/actions/build-plugin/action.yml | 4 +- CONTRIBUTING.md | 217 ++++++++++++++++++++++++ Readme.md | 49 +++--- composer.json | 6 + package.json | 7 +- 5 files changed, 255 insertions(+), 28 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/.github/actions/build-plugin/action.yml b/.github/actions/build-plugin/action.yml index 6c206c59e..4df6d5df0 100644 --- a/.github/actions/build-plugin/action.yml +++ b/.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' diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..4d5b4746a --- /dev/null +++ b/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: 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`. diff --git a/Readme.md b/Readme.md index 28631f48e..8d764bc22 100644 --- a/Readme.md +++ b/Readme.md @@ -59,55 +59,56 @@ CommonsBooking is a plugin for the management and booking of common goods. This Either through translating WordPress into your native tongue ([see the already existing WordPress Plugin Translations](https://translate.wordpress.org/projects/wp-plugins/commonsbooking/)) or through developing and testing new versions of the application. +See [CONTRIBUTING.md](CONTRIBUTING.md) for the full developer guide, including local setup, running tests, code standards, and how to submit a pull request. + ## Development ### Run plugin -First, we have to install the necessary dependencies and packages, we can do this by using the +Install all dependencies and build assets: ``` npm run start ``` -command. -The most easy way to start hacking WordPress plugins in general (if you have no other development environment set up) is using [wp-env](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/). Install it and it's dependencies (mainly Docker) and run this to start the enviroment: +The easiest way to start hacking WordPress plugins (if you have no other development environment set up) is using [wp-env](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/). Install it and its dependencies (mainly Docker) and run: ``` npm run env:start ``` -The provided `.wp-env.json` should be sufficient for normal development, for details see the [documentation of wp-env config](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/#wp-env-json). [You can create](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/#wp-env-override-json) a `.wp-env.override.json` for a custom configuration you don't want to check in. -For testing, you can activate the [kasimir theme](github.com/flegfleg/kasimir-theme) via [wp cli](https://make.wordpress.org/cli/handbook/) inside the wp-env docker container: +WordPress will be available at **http://localhost:1000** (credentials: `admin` / `password`). + +The provided `.wp-env.json` is sufficient for normal development. See the [wp-env config docs](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/#wp-env-json) for details. Create a `.wp-env.override.json` for local overrides you don't want to check in. + +To activate the [Kasimir theme](https://github.com/flegfleg/kasimir-theme) via WP-CLI: ``` npm run env run cli wp theme activate kasimir-theme ``` ### Test plugin -To test the code you first run the [preparation scripts](https://github.com/wp-cli/scaffold-command#wp-scaffold-plugin-tests) to load the wordpress core and configure database connection via `wp-config.php`. The following line can vary on your system, use the appropriate credentials, databse port and version of wordpress. The appropriate database port is printed out by `npm run env:start`: -``` -bash bin/install-wp-tests.sh wordpress root password 127.0.0.1:49153 latest -``` - -Testing the plugin code via `phpunit`. At the moment it works only with a manually downloaded phar. We are using PHPUnit 9 and PHP7.4 for the automated tests. The tests might fail if you are using a different version. +First set up the test database. The database port is printed when you run `npm run env:start`: ``` -php ~/phpunit.phar --bootstrap tests/php/bootstrap.php +bash bin/install-wp-tests.sh wordpress root '' 127.0.0.1: latest ``` -E2E (end to end) tests are written in [cypress](https://www.cypress.io/). To run them you need to install cypress and start the wordpress environment: +Then run the PHP unit tests: ```bash -npm run env:start -``` -Now, install the test data needed for the tests: -```bash -npm run cypress:setup +composer test ``` -Then you can run the tests: +E2E (end to end) tests are written in [Cypress](https://www.cypress.io/). To run them: ```bash -npm run cypress:run +npm run env:start # environment must be running +npm run cypress:setup # import test fixture data (once per environment) +npm run cypress:run # run headlessly +npm run cypress:open # open the interactive Cypress UI ``` -Or open Cypress using + +### Code standards + ```bash -npm run cypress:open +composer lint # check for violations +composer lint:fix # auto-fix fixable violations ``` ### Update translations @@ -115,11 +116,11 @@ npm run cypress:open Currently, we only manage German and English translations as po files in the repository, so they are available at build time. See the [WordPress plugin translation page](https://translate.wordpress.org/projects/wp-plugins/commonsbooking/) for other languages available at runtime. -Create a new .pot file using the +Create a new .pot file using: ``` wp i18n make-pot . languages/commonsbooking.pot ``` -command in the plugin directory. Make sure that all of your strings use the `__` function with the domain `commonsbooking`. Then you can use `poedit` to open the `commonsbooking-de_DE.po` and update the strings from the `pot` file. +Make sure that all of your strings use the `__` function with the domain `commonsbooking`. Then you can use `poedit` to open `commonsbooking-de_DE.po` and update the strings from the `pot` file. ### Build plugin zip diff --git a/composer.json b/composer.json index 422878fc7..221a56597 100644 --- a/composer.json +++ b/composer.json @@ -58,6 +58,12 @@ "automattic/jetpack-changelogger": "^6.0" }, "scripts": { + "lint": "phpcs", + "lint:fix": "phpcbf", + "test": [ + "@composer dump-autoload -o", + "phpunit" + ], "changelogger": "changelogger", "changelog:add": "changelogger add", "changelog:validate": "changelogger validate", diff --git a/package.json b/package.json index cf4ef157d..36e31a934 100644 --- a/package.json +++ b/package.json @@ -28,7 +28,7 @@ "sass": "^1.66.1" }, "scripts": { - "start": "composer install --ignore-platform-reqs && npm install && npm run dist", + "start": "composer install --ignore-platform-reqs && npm ci --legacy-peer-deps && npm run dist", "env": "wp-env", "env:install-tests-cli": "./bin/install-wp-cli.sh tests-wordpress", "env:start": "wp-env start && npm run env:install-tests-cli", @@ -36,7 +36,10 @@ "cypress:setup": "./bin/setup-cypress-env.sh", "cypress:open": "cypress open --config-file tests/cypress/cypress.config.js", "cypress:run": "cypress run --config-file tests/cypress/cypress.config.js", - "dist": "grunt dist" + "dist": "grunt dist", + "lint:php": "composer lint", + "lint:php:fix": "composer lint:fix", + "test:php": "composer test" }, "dependencies": { "@commonsbooking/frontend": "^0.1.0-beta.6",