From d80c9d90f99da0550fda2547622dd63df1f7d0e8 Mon Sep 17 00:00:00 2001 From: magdev Date: Thu, 29 Jan 2026 19:03:54 +0100 Subject: [PATCH] Update documentation for v1.4.0 CI/CD release process - README: Update automated releases section with submodule info - README: Update file structure with .gitea/workflows and submodule - README: Add v1.4.0 changelog entry - CLAUDE.md: Update version to 1.4.0, roadmap to 1.4.1 - CLAUDE.md: Rewrite release process for CI/CD workflow - CLAUDE.md: Add git submodule documentation - CLAUDE.md: Add v1.4.0 session history Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 252 +++++++++++++++++++++++++++++++----------------------- README.md | 41 ++++++--- 2 files changed, 170 insertions(+), 123 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 30d780e..3701409 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,7 +1,7 @@ # WooCommerce Tier and Package Prices - AI Context Document -**Last Updated:** 2026-01-27 -**Current Version:** 1.3.1 +**Last Updated:** 2026-01-29 +**Current Version:** 1.4.0 **Author:** Marco Graetsch **Project Status:** Production-ready WordPress plugin @@ -20,7 +20,7 @@ This project is proudly **"vibe-coded"** using Claude.AI - the entire codebase w **Note for AI Assistants:** Clean this section after the specific features are done or new releases are made. Effective changes are tracked in `CHANGELOG.md`. Do not add completed versions here - document them in the Session History section at the end of this file. Always keep the `Known Bugs` section and create a section with the next bugfix and minor version after a release. -### Version 1.3.2 +### Version 1.4.1 - No planned changes yet @@ -55,6 +55,8 @@ This project is proudly **"vibe-coded"** using Claude.AI - the entire codebase w ```txt wc-tier-and-package-prices/ ├── wc-tier-and-package-prices.php # Main plugin file (entry point) +├── .gitea/workflows/ +│ └── release.yml # CI/CD release pipeline ├── includes/ # PHP classes │ ├── class-wc-tpp-admin.php # Admin settings integration │ ├── class-wc-tpp-settings.php # WooCommerce settings page @@ -81,7 +83,8 @@ wc-tier-and-package-prices/ │ ├── *.pot # Translation template │ ├── *.po # Translation sources │ └── *.mo # Compiled translations -├── vendor/ # Composer dependencies (included in releases) +├── vendor/ # Composer dependencies +│ └── magdev/wc-licensed-product-client/ # License client (git submodule) ├── releases/ # Release packages (not in git) └── *.md # Documentation files @@ -353,136 +356,129 @@ Symptom: Help icon appearing far from label text at container edge ## Release Process -### Version Bumping +### Automated CI/CD Pipeline (Recommended) -Update version in 3 places: +Since v1.4.0, releases are automated via Gitea CI/CD. The pipeline is triggered when a version tag is pushed. -1. `wc-tier-and-package-prices.php` - Plugin header comment (line 7) -2. `wc-tier-and-package-prices.php` - `WC_TPP_VERSION` constant (line 26) -3. `composer.json` - version field (optional, not critical) - -### Creating Release Package - -**CRITICAL:** The zip command must be run from the **parent directory** of the plugin folder to create proper archive structure. +**Workflow:** ```bash -# From parent directory (/home/magdev/workspaces/php) -cd /home/magdev/workspaces/php +# 1. Update version in 3 places +# - wc-tier-and-package-prices.php (header comment, line 7) +# - wc-tier-and-package-prices.php (WC_TPP_VERSION constant) +# - composer.json (version field) -# Create zip excluding dev files - note the correct path structure -zip -r wc-tier-and-package-prices/releases/wc-tier-and-package-prices-X.X.X.zip wc-tier-and-package-prices/ \ - -x 'wc-tier-and-package-prices/.git*' \ - 'wc-tier-and-package-prices/*.log' \ - 'wc-tier-and-package-prices/.claude/*' \ - 'wc-tier-and-package-prices/CLAUDE.md' \ - 'wc-tier-and-package-prices/releases/*' \ - 'wc-tier-and-package-prices/node_modules/*' \ - 'wc-tier-and-package-prices/.DS_Store' \ - 'wc-tier-and-package-prices/Thumbs.db' \ - 'wc-tier-and-package-prices/.vscode/*' \ - 'wc-tier-and-package-prices/.idea/*' \ - 'wc-tier-and-package-prices/*.sublime-*' \ - 'wc-tier-and-package-prices/notes.*' \ - 'wc-tier-and-package-prices/logs/*' \ - 'wc-tier-and-package-prices/templates/cache/*' \ - 'wc-tier-and-package-prices/composer.lock' +# 2. Update CHANGELOG.md with release notes -# Return to project directory -cd wc-tier-and-package-prices +# 3. Commit and push to dev +git add -A && git commit -m "Version X.X.X - [description] -# Generate SHA256 checksum -cd releases -sha256sum wc-tier-and-package-prices-X.X.X.zip > wc-tier-and-package-prices-X.X.X.zip.sha256 -cd .. -``` - -**IMPORTANT NOTES:** - -- The `vendor/` directory MUST be included in releases (Twig dependency required for runtime) -- Running zip from wrong directory creates empty or malformed archives -- Exclusion patterns must match the relative path structure used in zip command -- Always verify the package with `unzip -l` and test extraction before committing - -### Verification Steps - -After creating the release package, always verify: - -```bash -# Check package size (should be ~400-450KB, NOT 8MB+ or near 0) -ls -lh releases/wc-tier-and-package-prices-X.X.X.zip - -# Verify exclusions worked -unzip -l releases/wc-tier-and-package-prices-X.X.X.zip | grep -E "CLAUDE\.md|\.claude/|\.git" && echo "ERROR: Excluded files found!" || echo "OK: No excluded files" - -# Test extraction -cd /tmp && rm -rf test-extract && unzip -q /path/to/releases/wc-tier-and-package-prices-X.X.X.zip -d test-extract && ls -la test-extract/wc-tier-and-package-prices/ - -# Verify version in extracted package -head -30 /tmp/test-extract/wc-tier-and-package-prices/wc-tier-and-package-prices.php | grep -E "Version:|WC_TPP_VERSION" - -# Verify template changes (if applicable) -grep 'class="regular"' /tmp/test-extract/wc-tier-and-package-prices/templates/admin/*.twig -``` - -### Git Workflow for Releases - -**Standard workflow:** Work on `dev` branch → merge to `main` → tag → push - -```bash -# 1. Ensure you're on dev branch with all changes committed -git checkout dev -git add [files] -git commit -m "Release version X.X.X - [description] - -🤖 Generated with [Claude Code](https://claude.com/claude-code) - -Co-Authored-By: Claude Sonnet 4.5 " - -# 2. Merge dev to main -git checkout main -git merge dev --no-edit # Should be fast-forward - -# 3. Create annotated tag -git tag -a vX.X.X -m "Release version X.X.X - [description]" - -# 4. Push everything -git push origin main -git push origin vX.X.X - -# 5. Update dev and push -git checkout dev -git rebase main # Should be up-to-date already +Co-Authored-By: Claude Opus 4.5 " git push origin dev -# 6. If you have uncommitted local changes (like .claude/settings.local.json) -git stash push -m "Local development settings" -# ... do git operations ... -git stash pop +# 4. Merge to main and push +git checkout main && git merge dev --no-edit && git push origin main + +# 5. Create and push tag (triggers CI/CD) +git tag -a vX.X.X -m "Release version X.X.X - [description]" +git push origin vX.X.X + +# 6. Switch back to dev +git checkout dev ``` -**Important Git Notes:** +**What the CI/CD Pipeline Does:** -- Always commit from `dev` branch first -- Tags should use format `vX.X.X` (e.g., `v1.1.22`) -- Use annotated tags (`-a`) not lightweight tags -- Commit messages should follow the established format with Claude Code attribution -- `.claude/settings.local.json` changes are typically local-only (stash before rebasing) +1. Checks out code with git submodules (`submodules: recursive`) +2. Sets up PHP 8.3 with required extensions +3. Validates `composer.json` +4. Installs production Composer dependencies (`--no-dev`) +5. Compiles translation files (.po → .mo) +6. Validates plugin version matches tag version +7. Creates release package with proper exclusions +8. Generates SHA256 checksum +9. Verifies package structure +10. Extracts changelog notes for release description +11. Creates Gitea release with assets + +**Pipeline Location:** `.gitea/workflows/release.yml` + +**Required Secret:** `SRC_GITEA_TOKEN` - Gitea API token for creating releases + +### Git Submodule: wc-licensed-product-client + +The `magdev/wc-licensed-product-client` library is bundled as a git submodule to avoid private repository authentication during CI/CD. + +**Location:** `vendor/magdev/wc-licensed-product-client/` + +**Updating the submodule:** + +```bash +# Update to latest commit +cd vendor/magdev/wc-licensed-product-client +git pull origin main +cd ../../.. +git add vendor/magdev/wc-licensed-product-client +git commit -m "Update wc-licensed-product-client submodule" +``` + +**Composer Configuration:** + +```json +{ + "repositories": [ + { + "type": "path", + "url": "vendor/magdev/wc-licensed-product-client", + "options": { "symlink": false } + } + ], + "require": { + "magdev/wc-licensed-product-client": "@dev" + } +} +``` + +### Manual Release (Legacy) + +For manual releases without CI/CD, run from the **parent directory**: + +```bash +cd /home/magdev/workspaces/php/wordpress/wp-content/plugins + +zip -r wc-tier-and-package-prices/releases/wc-tier-and-package-prices-X.X.X.zip wc-tier-and-package-prices/ \ + -x 'wc-tier-and-package-prices/.git/*' \ + -x 'wc-tier-and-package-prices/.gitea/*' \ + -x 'wc-tier-and-package-prices/.claude/*' \ + -x 'wc-tier-and-package-prices/CLAUDE.md' \ + -x 'wc-tier-and-package-prices/releases/*' \ + -x 'wc-tier-and-package-prices/composer.lock' \ + -x 'wc-tier-and-package-prices/*.log' \ + -x 'wc-tier-and-package-prices/.gitignore' \ + -x 'wc-tier-and-package-prices/.gitmodules' \ + -x 'wc-tier-and-package-prices/vendor/*/.git/*' \ + -x '*.DS_Store' + +cd wc-tier-and-package-prices/releases +sha256sum wc-tier-and-package-prices-X.X.X.zip > wc-tier-and-package-prices-X.X.X.zip.sha256 +``` ### What Gets Released - All plugin source files -- Compiled vendor dependencies +- Compiled vendor dependencies (including submodule) - Translation files (.mo compiled from .po) - Assets (CSS, JS) - Documentation (README, CHANGELOG, etc.) ### What's Excluded -- Git metadata (`.git/`) +- Git metadata (`.git/`, `.gitmodules`) +- CI/CD workflows (`.gitea/`) - Development files (`.vscode/`, `.claude/`, `CLAUDE.md`) - Logs and cache files - Previous releases -- `composer.lock` (but `vendor/` is included) +- `composer.lock` ## Testing Checklist @@ -1227,6 +1223,44 @@ The plugin architecture is solid and well-tested. Most bugs arise from: - Run zip from `/home/magdev/workspaces/php/wordpress/wp-content/plugins/` (NOT `/home/magdev/workspaces/php/`) - Always verify exclusions with: `unzip -l package.zip | grep -E "\.git/|CLAUDE\.md"` +### v1.4.0 Release Session (2026-01-29) + +**Accomplished:** + +1. Created Gitea CI/CD release pipeline: + - `.gitea/workflows/release.yml` - Automated release workflow + - Triggers on version tags (`v*`) + - Validates plugin version matches tag + - Installs production Composer dependencies + - Compiles translations (.po → .mo) + - Creates release package with proper exclusions + - Generates SHA256 checksum + - Publishes release to Gitea with changelog notes + +2. Added git submodule for license client: + - `vendor/magdev/wc-licensed-product-client/` as git submodule + - Avoids private repository authentication during CI/CD + - Updated `.gitignore` to allow submodule path + - Updated `composer.json` to use path repository + +3. Updated documentation: + - README.md - Added CI/CD section, updated file structure + - CLAUDE.md - Updated release process, added submodule docs + +**Key Learnings:** + +- Git submodules require `submodules: recursive` in checkout action +- Composer path repository with `symlink: false` works with submodules +- `.gitignore` patterns: Use `/vendor/*` then `!/vendor/magdev/` to allow specific paths +- When adding submodules to ignored paths, use `git submodule add -f` to force + +**CI/CD Pipeline Notes:** + +- Pipeline file: `.gitea/workflows/release.yml` +- Required secret: `SRC_GITEA_TOKEN` for Gitea API access +- Uses `shivammathur/setup-php@v2` for PHP setup +- Uses `actions/checkout@v4` with `submodules: recursive` + --- Always refer to this document when starting work on this project. Good luck! diff --git a/README.md b/README.md index c0478f5..f511b25 100644 --- a/README.md +++ b/README.md @@ -42,14 +42,17 @@ A powerful WooCommerce plugin that adds tier pricing and package pricing functio ### Automated Releases -This project uses a Gitea CI/CD pipeline for automated releases. When a version tag (e.g., `v1.3.2`) is pushed: +This project uses a Gitea CI/CD pipeline for automated releases. When a version tag (e.g., `v1.4.0`) is pushed: -1. The pipeline validates the plugin version matches the tag -2. Composer dependencies are installed (production only) -3. Translation files are compiled -4. A release package is created with proper exclusions -5. SHA256 checksum is generated -6. Release is published to Gitea with changelog notes +1. Code is checked out with git submodules (dependencies bundled) +2. The pipeline validates the plugin version matches the tag +3. Composer dependencies are installed (production only) +4. Translation files are compiled (.po → .mo) +5. A release package is created with proper exclusions +6. SHA256 checksum is generated +7. Release is published to Gitea with changelog notes extracted from CHANGELOG.md + +The `magdev/wc-licensed-product-client` library is bundled as a git submodule to avoid private repository authentication during CI/CD. ## Configuration @@ -122,7 +125,9 @@ When editing a product, scroll to the **Product data** panel: ``` wc-tier-and-package-prices/ -├── wc-tier-and-package-prices.php # Main plugin file (v1.3.1) +├── wc-tier-and-package-prices.php # Main plugin file (v1.4.0) +├── .gitea/workflows/ +│ └── release.yml # CI/CD release pipeline ├── includes/ │ ├── class-wc-tpp-admin.php # Admin settings integration │ ├── class-wc-tpp-settings.php # WooCommerce settings page @@ -149,7 +154,8 @@ wc-tier-and-package-prices/ │ ├── wc-tier-package-prices.pot # Translation template │ ├── wc-tier-package-prices-*.po # Translation sources │ └── wc-tier-package-prices-*.mo # Compiled translations -├── vendor/ # Composer dependencies (Twig) +├── vendor/ # Composer dependencies +│ └── magdev/wc-licensed-product-client/ # License client (git submodule) ├── CHANGELOG.md # Complete version history ├── INSTALLATION.md # Installation guide ├── QUICKSTART.md # Quick start guide @@ -195,18 +201,25 @@ This plugin is licensed under the GPL v2 or later. ## Changelog +### Version 1.4.0 - 2026-01-29 + +__Current Release__ - CI/CD Release Pipeline + +- __New__: Gitea CI/CD release pipeline for automated builds and releases +- __New__: Git submodule for `magdev/wc-licensed-product-client` library +- __Changed__: Composer now uses path repository for bundled license client +- __DevOps__: Automated version validation, translation compilation, and release publishing + +See [CHANGELOG.md](CHANGELOG.md) for complete details. + ### Version 1.3.1 - 2026-01-27 -__Current Release__ - Secure License Client +Secure License Client - __Changed__: Switched to `SecureLicenseClient` with HMAC-SHA256 response signature verification - __New__: Server Secret configuration field for secure communication with license server -- __New__: Rate limit exception handling with retry time display -- __New__: Signature verification and URL validation error handling - __Security__: Response signatures verified using HMAC-SHA256 with license-specific derived keys -See [CHANGELOG.md](CHANGELOG.md) for complete details. - ### Version 1.3.0 - 2026-01-25 __Breaking Changes__ - PHP 8.3+ Required