From f530b37285bee632761624b4ae67b60d78fa9b4f Mon Sep 17 00:00:00 2001 From: magdev Date: Tue, 23 Dec 2025 17:09:46 +0100 Subject: [PATCH] Update CLAUDE.md with v1.1.22 release learnings and best practices MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added detailed release package creation instructions - Documented correct zip command execution from parent directory - Added comprehensive verification steps for release packages - Included complete Git workflow for releases (dev → main → tag → push) - Added common pitfalls and solutions section - Documented WooCommerce CSS classes for admin UI - Added Twig template modification guidelines - Included complete release workflow summary with time estimates These updates will help future AI assistants avoid common mistakes when creating releases, especially around package creation and Git workflows. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- CLAUDE.md | 187 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 178 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c3a624d..41a30d4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -303,22 +303,112 @@ Update version in 3 places: 3. `composer.json` - version field (optional, not critical) ### Creating Release Package -```bash -# From project root -cd releases -# Create zip excluding dev files -zip -r wc-tier-and-package-prices-X.X.X.zip .. \ - -x '*.git*' '*.log' '.claude/*' 'CLAUDE.md' 'releases/*' 'node_modules/*' \ - '.DS_Store' 'Thumbs.db' '.vscode/*' '.idea/*' '*.sublime-*' \ - 'notes.*' 'logs/*' 'templates/cache/*' 'composer.lock' +**CRITICAL:** The zip command must be run from the **parent directory** of the plugin folder to create proper archive structure. + +```bash +# From parent directory (/home/magdev/workspaces/node) +cd /home/magdev/workspaces/node + +# 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' + +# Return to project directory +cd wc-tier-and-package-prices # Generate checksums +cd releases md5sum wc-tier-and-package-prices-X.X.X.zip > wc-tier-and-package-prices-X.X.X.zip.md5 sha256sum wc-tier-and-package-prices-X.X.X.zip > wc-tier-and-package-prices-X.X.X.zip.sha256 +cd .. ``` -**IMPORTANT:** The `vendor/` directory MUST be included in releases (Twig dependency required for runtime). +**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 +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 +``` + +**Important Git Notes:** + +- 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) ### What Gets Released @@ -375,6 +465,85 @@ When making changes, test these critical paths: ## Development Tips for Future AI Assistants +### Common Pitfalls and Solutions + +#### Release Package Creation +**Problem:** Empty or corrupted zip files (0 bytes or wrong structure) +**Cause:** Running zip command from wrong directory or incorrect path patterns +**Solution:** Always run from parent directory (`/home/magdev/workspaces/node`) and use full relative paths in exclusions + +**Problem:** Development files included in release (CLAUDE.md, .claude/, .git) +**Cause:** Exclusion patterns don't match actual paths used in zip command +**Solution:** Test with `unzip -l | grep` to verify exclusions before committing + +**Problem:** Package size is 8MB+ instead of ~400KB +**Cause:** Development files not excluded (especially .git directory) +**Solution:** Follow verification steps and check package size immediately after creation + +#### UI Changes in Admin +**WooCommerce CSS Classes:** +- `short` - Small input fields (~60px width) +- `regular` - Medium input fields (~120px width) +- `long` - Large input fields (~200px+ width) + +When modifying admin input fields in Twig templates, use WooCommerce's standard classes for consistency. + +**Location:** `templates/admin/*.twig` for admin UI changes + +#### Git Workflow Issues +**Problem:** Cannot rebase due to uncommitted changes +**Solution:** Stash local config files (`.claude/settings.local.json`) before git operations + +**Problem:** Tag already exists +**Solution:** Delete with `git tag -d vX.X.X` locally and `git push --delete origin vX.X.X` remotely + +**Problem:** Wrong branch for commits +**Solution:** Always start on `dev` branch, merge to `main`, never commit directly to `main` + +### Working with Twig Templates + +The plugin uses Twig 3.0 for templating. Key files: + +- `templates/admin/tier-row.twig` - Single tier input row in product edit page +- `templates/admin/package-row.twig` - Single package input row in product edit page +- `templates/frontend/*.twig` - Customer-facing pricing displays + +**Template rendering:** Done via `WC_TPP_Template_Loader` singleton class + +**When modifying templates:** + +1. Templates are cached - clear cache or test in development mode +2. Always escape output: use Twig's built-in filters or `|esc_attr`, `|esc_html` +3. Translation strings: `{{ 'Text'|__('wc-tier-package-prices') }}` +4. Keep consistent with WooCommerce admin UI patterns + +### Complete Release Workflow Summary + +Based on v1.1.22 release experience, here's the complete workflow: + +1. **Fix bugs/add features** on `dev` branch +2. **Update version numbers** (3 files: main plugin file header, constant, composer.json) +3. **Update CHANGELOG.md** with detailed changes +4. **Update CLAUDE.md** version number and roadmap +5. **Create release package** from parent directory with correct exclusions +6. **Verify package** (size, contents, exclusions, extraction test) +7. **Commit changes** to `dev` branch with proper message format +8. **Merge to main** (fast-forward merge) +9. **Create annotated tag** (`vX.X.X`) +10. **Push all** (main, tag, dev) +11. **Verify remote** (check repository web UI) + +**Time estimate:** 15-20 minutes for full release cycle + +**Files typically changed in a release:** + +- `wc-tier-and-package-prices.php` - Version bumps +- `composer.json` - Version bump +- `CHANGELOG.md` - Release notes +- `CLAUDE.md` - Version and roadmap updates +- `releases/wc-tier-and-package-prices-X.X.X.zip*` - Package and checksums +- Feature-specific files (templates, PHP classes, etc.) + ### Future Features and Roadmap The is a hierarchical list for upcoming features and can be considered as a