Deployment & Production Workflow

PRE-DEPLOYMENT TESTING CHECKLIST
═══════════════════════════════════════════

PAGES TO TEST
□ Homepage (with all sections populated)
□ Collection page (with products)
□ Collection page (empty collection)
□ Product page (with variants)
□ Product page (single variant)
□ Product page (sold out)
□ Product page (on sale)
□ Cart page (with items)
□ Cart page (empty)
□ Search page (with results)
□ Search page (no results)
□ Blog page
□ Article page
□ Custom page (e.g., About Us)
□ Contact page
□ 404 error page
□ Password page
□ Gift card page
□ Customer login page
□ Customer account page

FUNCTIONALITY
□ Add to cart works (all product types)
□ Cart updates quantity correctly
□ Cart removes items
□ Navigation links all work (no broken links)
□ Search returns relevant results
□ Predictive search works (if implemented)
□ Mobile menu opens and closes
□ All forms submit correctly
□ Variant selector updates price and image
□ Newsletter signup submits
□ Social media links open in new tabs

RESPONSIVE DESIGN
□ Test at 320px (smallest phone)
□ Test at 375px (standard phone)
□ Test at 768px (tablet portrait)
□ Test at 1024px (tablet landscape)
□ Test at 1440px (desktop)
□ No horizontal scrollbar at any width
□ All text is readable (no overflow)
□ Buttons/links are tappable (44px min)
□ Images don't overflow containers

BROWSER TESTING
□ Chrome (latest)
□ Firefox (latest)
□ Safari (latest — test on Mac/iPhone if possible)
□ Edge (latest)
□ Mobile Safari (iOS)
□ Mobile Chrome (Android)

PERFORMANCE
□ Lighthouse score above 50 (ideally 70+)
□ No render-blocking resources
□ Images optimized with srcset
□ Lazy loading implemented
□ No console errors

ACCESSIBILITY
□ Skip-to-content link works
□ All images have alt text
□ Color contrast meets WCAG AA
□ Keyboard navigation works (Tab through page)
□ Focus states are visible
□ Form labels are properly associated
□ ARIA labels on interactive elements

SEO
□ Page titles are unique and descriptive
□ Meta descriptions present
□ Canonical URLs are correct
□ Open Graph tags present
□ Structured data (if implemented)
□ No broken links

ERROR: "Liquid error: Unknown tag 'endfor'"
FIX:   Check for typos — ensure {% endfor %} matches {% for %}
       Check nesting — every if/for/case needs a closing tag

ERROR: "Liquid error: undefined variable"  
FIX:   Variable doesn't exist in current scope.
       If using {% render %}, pass the variable explicitly.
       Check for typos in variable names.

ERROR: "Liquid error: Array index out of bounds"
FIX:   Check array .size before accessing by index.
       Use {% if array.size > 0 %} before looping.

ERROR: "Liquid error: wrong number of arguments"
FIX:   Check filter syntax. Common mistake:
       ❌ {{ image | image_url: 400 }}
       ✅ {{ image | image_url: width: 400 }}

ERROR: Page renders but section is blank
FIX:   1. Check {% if %} conditions — something is probably blank/nil
       2. Output debug: {{ section.settings | json }}
       3. Check schema — setting IDs must match Liquid references
       4. Check template JSON — is the section referenced?

PROBLEM: Section doesn't appear in "Add section" menu
CHECK:  Does your schema have a "presets" array?
        Without presets, the section can't be added manually.

PROBLEM: Settings don't appear in theme editor sidebar
CHECK:  Is the setting inside the "settings" array in schema?
        Is the JSON valid? (missing comma, bracket, quote)
        Validate JSON at jsonlint.com

PROBLEM: Blocks can't be clicked in the editor preview
CHECK:  Is {{ block.shopify_attributes }} on the block wrapper?
        This is REQUIRED for editor interactivity.

PROBLEM: Section shows in editor but not on live site
CHECK:  Is the section in the JSON template's "order" array?
        Is there a conditional that hides it?

PROBLEM: Schema changes not reflecting
FIX:    Save the section file, refresh the theme editor.
        Sometimes you need to close and reopen the editor.
        Clear browser cache if needed.

# Step 1: Push to a new unpublished theme
shopify theme push --unpublished \
  --store client-store.myshopify.com

# This creates a new theme named "[development] Your Theme"
# It does NOT affect the live store

# Step 2: Share preview link with client
# The CLI will output a preview URL like:
# https://client-store.myshopify.com/?preview_theme_id=XXXXXXX

# Step 3: After client approves, publish via Shopify Admin
# Online Store → Themes → Actions → Publish

# Or publish via CLI (use with caution):
shopify theme publish --theme THEME_ID \
  --store client-store.myshopify.com

# List existing themes to find the ID
shopify theme list --store client-store.myshopify.com

# Output:
# ID           NAME                  ROLE
# 123456789    Dawn (Live)           live
# 987654321    My Custom Theme       unpublished

# Push to the specific unpublished theme
shopify theme push --theme 987654321 \
  --store client-store.myshopify.com

# This pushes directly to the live published theme
# WARNING: Changes are immediately visible to customers
shopify theme push --allow-live \
  --store client-store.myshopify.com

# SAFER: Push specific files only
shopify theme push --allow-live \
  --only sections/header.liquid \
  --only assets/section-header.css \
  --store client-store.myshopify.com

# Never overwrite the merchant's customized settings
shopify theme push \
  --ignore config/settings_data.json \
  --store client-store.myshopify.com

# You can also create a .shopifyignore file
# in your project root:

# .shopifyignore
config/settings_data.json
templates/*.json

# Don't overwrite merchant's theme settings
config/settings_data.json

# Don't overwrite template configurations
# (merchant may have added/reordered sections)
templates/*.json

# Keep the default templates in your repo
# but don't push them over merchant customizations
!templates/product.json
!templates/collection.json

RECOMMENDED BRANCHING MODEL
═══════════════════════════════════════════

main (or production)
  │
  ├── The stable, production-ready code
  ├── Only merged from staging or hotfix branches
  ├── Tagged with version numbers (v1.0.0, v1.1.0)
  │
  └── staging (or develop)
        │
        ├── Integration branch for testing
        ├── Features merge here first
        ├── Pushed to unpublished theme for review
        │
        ├── feature/hero-redesign
        │     └── New feature development
        │
        ├── feature/mega-menu
        │     └── Another feature in parallel
        │
        └── fix/mobile-nav-bug
              └── Bug fix branch


SIMPLIFIED MODEL (for solo developers):

main
  │
  ├── Stable theme code
  │
  ├── feature/new-section
  │     └── Develop → Test → Merge to main
  │
  └── fix/cart-bug
        └── Fix → Test → Merge to main

# ── DEVELOPMENT PHASE ──────────────────────────

# 1. Create a feature branch
git checkout main
git pull origin main
git checkout -b feature/announcement-bar

# 2. Develop with live preview
shopify theme dev --store dev-store.myshopify.com

# 3. Make changes, test, commit regularly
git add sections/announcement-bar.liquid
git add assets/section-announcement-bar.css
git commit -m "feat: add announcement bar section with auto-rotate"

git add sections/announcement-bar.liquid
git commit -m "fix: announcement bar dismiss uses sessionStorage"

# 4. Push branch to GitHub
git push -u origin feature/announcement-bar


# ── REVIEW PHASE ──────────────────────────────

# 5. Merge to main when feature is complete
git checkout main
git merge feature/announcement-bar
git push origin main

# 6. Clean up feature branch
git branch -d feature/announcement-bar
git push origin --delete feature/announcement-bar


# ── DEPLOYMENT PHASE ──────────────────────────

# 7. Push to unpublished theme on client store
shopify theme push --unpublished \
  --ignore config/settings_data.json \
  --store client-store.myshopify.com

# 8. Share preview link with client for approval

# 9. After approval, publish the theme
# (via Shopify Admin or CLI)

# 10. Tag the release in Git
git tag -a v1.2.0 -m "Add announcement bar section"
git push origin v1.2.0

# Create an annotated tag
git tag -a v1.0.0 -m "Initial theme release"

# Push tags to GitHub
git push origin v1.0.0

# Push all tags
git push origin --tags

# List all tags
git tag -l

# View tag details
git show v1.0.0

# Before ANY major deployment, create a backup:

# Option 1: Download the live theme as a backup
shopify theme pull \
  --theme LIVE_THEME_ID \
  --path ./backups/backup-$(date +%Y%m%d) \
  --store client-store.myshopify.com

# Option 2: Duplicate the live theme in Shopify Admin
# Online Store → Themes → Actions → Duplicate
# This creates a copy the merchant can revert to

# Option 3: Git tags serve as backups
git tag -a backup/pre-v2-launch -m "Backup before v2 launch"
git push origin backup/pre-v2-launch

# Option 1: Revert a specific commit
git revert HEAD    # Reverts the last commit
git push

# Option 2: Reset to a specific tag
git checkout v1.1.0    # Go to a tagged version
shopify theme push --unpublished \
  --store client-store.myshopify.com

# Option 3: Reset branch to a previous state (destructive!)
git reset --hard v1.1.0
git push --force     # CAUTION: rewrites remote history

PRODUCTION READINESS
═══════════════════════════════════════════

CODE QUALITY
□ All debug output removed ({{ product | json }}, HTML comments)
□ No console.log() statements in JavaScript
□ No TODO or FIXME comments left unresolved
□ Code is consistently formatted
□ Snippets are documented with accepted parameters
□ Schema settings have helpful labels, info text, and defaults
□ Translation keys used for all user-facing strings

THEME SETTINGS
□ settings_schema.json has theme_info block (name, version, author)
□ All global settings have sensible defaults
□ Color settings provide good default palette
□ Typography defaults are readable and professional

CONTENT
□ All sections render placeholder content when no data is set
□ Empty states are handled gracefully (empty cart, no results, etc.)
□ All images have meaningful alt text
□ Locales file has all required translation keys

LEGAL
□ No copyrighted code from premium themes
□ No copyrighted images or fonts
□ License information is clear (if distributing)
□ Privacy-related features comply with GDPR (cookie consent, etc.)

DEPLOYMENT
□ .shopifyignore is configured
□ .gitignore is configured
□ Git repository is clean (no uncommitted changes)
□ Live theme is backed up (duplicated in Shopify Admin)
□ Client has been notified of deployment timing
□ Post-deployment verification plan is ready

IMMEDIATELY AFTER PUBLISHING
═══════════════════════════════════════════

□ Visit the homepage — does it load correctly?
□ Visit a product page — can you add to cart?
□ Visit a collection page — do products display?
□ Test on mobile (real phone, not just DevTools)
□ Complete a test checkout (on dev store) or verify
  checkout loads correctly (on live store)
□ Check browser console for JavaScript errors
□ Run a quick Lighthouse audit
□ Verify header and footer render correctly
□ Check that merchant's custom content is intact
□ Notify the client that deployment is complete

# This is a conceptual example — adapt to your needs
name: Deploy Shopify Theme

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Shopify CLI
        run: npm install -g @shopify/cli @shopify/theme

      - name: Deploy to Shopify
        env:
          SHOPIFY_CLI_THEME_TOKEN: ${{ secrets.SHOPIFY_CLI_THEME_TOKEN }}
          SHOPIFY_FLAG_STORE: ${{ secrets.SHOPIFY_STORE }}
        run: |
          shopify theme push \
            --theme ${{ secrets.THEME_ID }} \
            --ignore config/settings_data.json