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 <noreply@anthropic.com>
2026-01-29 19:03:54 +01:00
parent 2bf0cd82fe
commit d80c9d90f9
2 changed files with 170 additions and 123 deletions
--- 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 <noreply@anthropic.com>"
-
-# 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 <noreply@anthropic.com>"
 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!