From c63ce6dd912a47a6fc8e6839efd61b680e33b8ab Mon Sep 17 00:00:00 2001 From: juanatsap Date: Sat, 6 Dec 2025 11:34:57 +0000 Subject: [PATCH] docs: add cache busting, mobile FAB, and lint workflow documentation --- README.md | 29 +++++++++ doc/2-MODERN-WEB-TECHNIQUES.md | 106 +++++++++++++++++++++++++++++++++ 2 files changed, 135 insertions(+) diff --git a/README.md b/README.md index 36df243..d05415e 100644 --- a/README.md +++ b/README.md @@ -115,6 +115,35 @@ go run main.go go build -o cv-server && ./cv-server \`\`\` +### Development Workflow + +The project includes automated quality checks at multiple stages: + +| Stage | Command | What Runs | Coverage | +|-------|---------|-----------|----------| +| **Commit** | `git commit` | Pre-commit hook | Changed files only (fast) | +| **Push** | `git push` | Pre-push hook | **Entire codebase** (same as CI) | +| **Manual** | `make lint` | golangci-lint | Entire codebase | +| **Auto-fix** | `make lint-fix` | golangci-lint --fix | Fixes issues automatically | + +**Available Make targets:** + +\`\`\`bash +make lint # Run linter on entire codebase (same as CI) +make lint-fix # Auto-fix lint issues where possible +make test # Run unit tests +make test-all # Run all tests including integration +make check # Run lint + unit tests +make css-prod # Bundle and minify CSS for production +make dev # Start development server with hot reload +\`\`\` + +**Bypassing hooks (when needed):** +\`\`\`bash +git commit --no-verify # Skip pre-commit hook +git push --no-verify # Skip pre-push hook +\`\`\` + ### Access the Site Open **http://localhost:1999** in your browser diff --git a/doc/2-MODERN-WEB-TECHNIQUES.md b/doc/2-MODERN-WEB-TECHNIQUES.md index 8362732..00c3324 100644 --- a/doc/2-MODERN-WEB-TECHNIQUES.md +++ b/doc/2-MODERN-WEB-TECHNIQUES.md @@ -1470,6 +1470,11 @@ end - ✅ **Print CSS separate** (media="print" for PDF export) - ✅ **Makefile targets** (css-dev, css-prod, css-watch) +### Phase 10 Achievements (Cache Busting & Mobile Optimization): +- ✅ **CSS version query strings** for cache invalidation +- ✅ **Mobile FAB overflow fix** (responsive buttons on 375px screens) +- ✅ **Pre-push lint hook** catches CI issues before push + ### Cumulative Achievements: - ✅ **715 lines of JavaScript eliminated total** (74.9% reduction) - ✅ **54% CSS size reduction** in production (Lightning CSS bundling) @@ -1484,6 +1489,107 @@ end --- +## 🔄 Phase 10: Cache Management & Mobile Optimization + +### 11. CSS Cache Busting - Version Query Strings + +**Problem:** Browser caching (especially mobile Safari) serves stale CSS even after deployments, causing users to see outdated styles. + +**Solution:** Add version query strings to CSS bundle URLs, forcing browsers to fetch fresh files after deployments. + +#### Implementation: + +```html + + + + + +``` + +#### Why This Works: +- Browsers treat `bundle.min.css?v=1` and `bundle.min.css?v=2` as different resources +- Cache headers (`max-age=86400`) still provide performance benefits +- New versions are fetched immediately without manual cache clearing +- Zero impact on server-side caching (query string ignored by CDNs if configured) + +#### Best Practices: +```html + + + + + + + + +``` + +#### Mobile Safari Considerations: +- iOS Safari caches aggressively, even with `no-cache` headers +- Version strings ensure fresh CSS on first visit after deployment +- Users don't need to manually clear browser data + +--- + +### 12. Responsive FAB Buttons - Mobile-First CSS + +**Problem:** Floating Action Buttons (FAB) calculated for 380px minimum width overflow on iPhone 13 mini (375px) and smaller screens. + +**Solution:** Progressive CSS with media queries for very small screens. + +#### Implementation: + +```css +/* Base mobile styles (≤900px) */ +@media (max-width: 900px) { + .download-btn, .info-button, .back-to-top /* ... */ { + /* Fluid sizing: 36px at 380px → 50px at 900px */ + width: clamp(36px, calc(2.7vw + 25.7px), 50px) !important; + height: clamp(36px, calc(2.7vw + 25.7px), 50px) !important; + } +} + +/* Very small screens (≤400px) - iPhone 13 mini, iPhone SE */ +@media (max-width: 400px) { + .download-btn, .info-button, .back-to-top /* ... */ { + width: 34px !important; + height: 34px !important; + } + + /* 6 buttons * 34px + 5 gaps * 6px = 234px total */ + /* Centered: calc(50% - 117px) to calc(50% + 83px) */ + .is-mobile-device .download-btn { + left: calc(50% - 117px) !important; + } + /* ... remaining button positions ... */ +} +``` + +#### Key Technique: Progressive Enhancement +1. **Desktop first**: Full-size buttons with hover effects +2. **Mobile (≤900px)**: Fluid `clamp()` sizing, centered layout +3. **Very small (≤400px)**: Fixed small size, tight spacing + +#### Testing Strategy: +```javascript +// Playwright test for mobile overflow +const iphone13Mini = await page.evaluate(() => { + const buttons = document.querySelectorAll('.download-btn, .info-button, ...'); + let rightMost = 0; + buttons.forEach(btn => { + rightMost = Math.max(rightMost, btn.getBoundingClientRect().right); + }); + return { + overflow: rightMost > window.innerWidth, + viewport: window.innerWidth + }; +}); +expect(iphone13Mini.overflow).toBe(false); +``` + +--- + ## 🚀 Phase 7-8: Smooth Toggle Animations - Pure Client-Side Pattern (COMPLETED) ### 9. HTMX `hx-swap="none"` + Inline Hyperscript - Client-First Toggles