From de9512815dacb54ad62cf2ed194c2470a36b2176 Mon Sep 17 00:00:00 2001 From: magdev Date: Mon, 2 Feb 2026 22:49:38 +0100 Subject: [PATCH] docs: Add critical instruction to never build local releases CI/CD pipeline handles all release building - local builds can corrupt the development environment. Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 39 +++++++++++++++++++-------------------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 52f42c6..f2c98c2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -79,28 +79,27 @@ for po in languages/*.po; do msgfmt -o "${po%.po}.mo" "$po"; done ### Create releases +**CRITICAL: NEVER build release packages locally! All releases are built automatically by the CI/CD pipeline (Gitea Actions) when a tag is pushed. Local builds can corrupt the development environment and create inconsistent packages.** + +To create a release: + +1. Update version in `wp-fedistream.php` (both header and constant) +2. Update `CHANGELOG.md` with release notes +3. Commit changes to `main` branch +4. Create annotated tag: `git tag -a v0.6.0 -m "Release v0.6.0"` +5. Push: `git push origin main --tags` +6. CI/CD will automatically build and publish the release + +#### CI/CD Build Details (for reference only) + +The following details describe what the CI/CD pipeline does - DO NOT run these locally: + - The `vendor/` directory MUST be included in releases (Dependencies required for runtime) -- **Don't create any release files until version 0.1.x and up!** -- **CRITICAL**: Build `vendor/` for the MINIMUM supported PHP version, not the development version - - Use `composer config platform.php 8.3.0` before building release packages - - Run `composer update --no-dev --optimize-autoloader` to rebuild dependencies -- **CRITICAL**: WordPress requires plugins in a subdirectory structure - - Run zip from the `plugins/` parent directory, NOT from within the plugin directory - - Package must extract to `wp-fedistream/` subdirectory with main file at `wp-fedistream/wp-fedistream.php` - - Correct command: `cd /wp-content/plugins/ && zip -r wp-fedistream/releases/wp-fedistream-x.x.x.zip wp-fedistream ...` - - Wrong: Running zip from inside the plugin directory creates files at root level -- **CRITICAL**: Exclude symlinks explicitly - zip follows symlinks by default - - Always use `-x "wp-fedistream/wp-core" -x "wp-fedistream/wp-core/*" -x "wp-fedistream/wp-plugins" -x "wp-fedistream/wp-plugins/*"` to exclude development symlinks - - Otherwise the entire linked directory contents will be included in the package -- Exclusion patterns must match the relative path structure used in zip command -- Always verify the package structure with `unzip -l` before distribution - - Check all files are prefixed with `wp-fedistream/` - - Verify main file is at `wp-fedistream/wp-fedistream.php` - - Check for duplicate entries (indicates multiple builds in same archive) -- Test installation on the minimum supported PHP version before final deployment +- Build `vendor/` for the MINIMUM supported PHP version (8.3.0) +- WordPress requires plugins in a subdirectory structure +- Symlinks are excluded from packages - Releases are stored in `releases/` including checksums -- Track release changes in a single `CHANGELOG.md` file -- Bump the version number to either bugfix release versions or on new features minor release versions + - **CRITICAL**: WordPress reads version from TWO places - BOTH must be updated: 1. Plugin header comment `Version: x.x.x` (line ~6 in wc-licensed-product.php) - WordPress uses THIS for admin display 2. PHP constant `WP_FEDISTREAM_VERSION` (line ~28) - Used internally by the plugin