magdev/wc-tier-and-package-prices
1
Fork 0
Code Issues Pull Requests Actions Releases 2 Activity

Update CLAUDE.md with v1.1.22 release learnings and best practices

Browse Source 
- 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 <noreply@anthropic.com>
This commit is contained in:
Marco Grätsch
2025-12-23 17:09:46 +01:00
parent 1e6d86ca10
commit f530b37285
1 changed files with 178 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
CLAUDE.md
View File

@@ -303,22 +303,112 @@ Update version in 3 places:
3. `composer.json` - version field (optional, not critical) 3. `composer.json` - version field (optional, not critical)
### Creating Release Package ### Creating Release Package
```bash
# From project root
cd releases
# Create zip excluding dev files **CRITICAL:** The zip command must be run from the **parent directory** of the plugin folder to create proper archive structure.
zip -r wc-tier-and-package-prices-X.X.X.zip .. \
-x '*.git*' '*.log' '.claude/*' 'CLAUDE.md' 'releases/*' 'node_modules/*' \ ```bash
'.DS_Store' 'Thumbs.db' '.vscode/*' '.idea/*' '*.sublime-*' \ # From parent directory (/home/magdev/workspaces/node)
'notes.*' 'logs/*' 'templates/cache/*' 'composer.lock' 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 # Generate checksums
cd releases
md5sum wc-tier-and-package-prices-X.X.X.zip > wc-tier-and-package-prices-X.X.X.zip.md5 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 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 <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
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 ### What Gets Released
@@ -375,6 +465,85 @@ When making changes, test these critical paths:
## Development Tips for Future AI Assistants ## 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 ### Future Features and Roadmap
The is a hierarchical list for upcoming features and can be considered as a The is a hierarchical list for upcoming features and can be considered as a