Versioning, Releases, and Deployment

Professional theme development requires systematic versioning and deployment. This lesson covers workflows that keep your themes organized and deployments safe.

Semantic Versioning

Use semantic versioning (SemVer) for your themes:

MAJOR.MINOR.PATCH

1.0.0 → Initial release
1.0.1 → Bug fixes
1.1.0 → New features (backward compatible)
2.0.0 → Breaking changes

Version Examples

Change	Version	Notes
Fix typo in CSS	1.0.0 → 1.0.1	Patch
Add new section	1.0.1 → 1.1.0	Minor
Restructure templates	1.1.0 → 2.0.0	Major
Security fix	1.1.0 → 1.1.1	Patch

Theme Version in Schema

Update version in config/settings_schema.json:

[
  {
    "name": "theme_info",
    "theme_name": "My Theme",
    "theme_version": "1.2.0",
    "theme_author": "Your Name",
    "theme_documentation_url": "https://docs.example.com",
    "theme_support_url": "https://support.example.com"
  }
]

Git Workflow

Branch Strategy

main (production)
├── develop (integration)
│   ├── feature/add-cart-drawer
│   ├── feature/new-product-template
│   └── fix/mobile-menu-bug
└── release/1.2.0 (preparation)

Branch Naming

# Features
feature/add-quick-view
feature/product-recommendations

# Bug fixes
fix/cart-drawer-height
fix/mobile-nav-z-index

# Releases
release/1.2.0
release/2.0.0

# Hotfixes
hotfix/critical-checkout-bug

Git Commands

# Start a new feature
git checkout develop
git pull origin develop
git checkout -b feature/new-section

# Work on feature
git add .
git commit -m "Add: New hero section with video support"

# Merge feature to develop
git checkout develop
git merge feature/new-section
git push origin develop

# Create release branch
git checkout -b release/1.2.0
# Update version number
git commit -m "Bump version to 1.2.0"

# Merge to main for production
git checkout main
git merge release/1.2.0
git tag v1.2.0
git push origin main --tags

Commit Messages

Convention

Type: Short description

Longer description if needed.

Type can be:
- Add: New feature
- Fix: Bug fix
- Update: Enhancement to existing feature
- Remove: Removed feature
- Refactor: Code restructure
- Docs: Documentation
- Style: Formatting, no code change

Examples

git commit -m "Add: Product quick view modal"
git commit -m "Fix: Cart drawer not closing on mobile"
git commit -m "Update: Improve collection filter performance"
git commit -m "Remove: Deprecated slideshow section"
git commit -m "Refactor: Extract product card into snippet"

Changelog

Maintain a CHANGELOG.md:

# Changelog

All notable changes to this theme will be documented in this file.

## [1.2.0] - 2024-01-15

### Added

- Product quick view modal
- Color swatch display on collection pages
- Newsletter popup section

### Changed

- Improved mobile navigation performance
- Updated product image zoom behavior

### Fixed

- Cart drawer height issue on iOS Safari
- Search results pagination

## [1.1.0] - 2024-01-01

### Added

- Blog article table of contents
- Product size guide popup

### Fixed

- Mobile menu not closing after navigation

Shopify CLI Deployment

Basic Deployment

# Push to development theme
shopify theme push

# Push to specific theme
shopify theme push --theme 123456789

# Push only changed files
shopify theme push --only templates/product.json

# Ignore specific files
shopify theme push --ignore config/settings_data.json

Deployment Workflow

# 1. Develop locally
shopify theme dev

# 2. Test on development theme
shopify theme push --development

# 3. Review in theme editor
# 4. Push to staging theme
shopify theme push --theme staging-theme-id

# 5. Final testing
# 6. Push to production
shopify theme push --live

Theme Push Options

# Push and keep settings
shopify theme push --ignore config/settings_data.json

# Push specific files
shopify theme push --only sections/header.liquid

# Force push (overwrites remote)
shopify theme push --force

# Preview before pushing
shopify theme push --dry-run

Environment Management

Multiple Stores

# ~/.shopify-cli.yml or use flags

# Connect to different stores
shopify theme push --store my-dev-store.myshopify.com
shopify theme push --store my-production-store.myshopify.com

Theme Environments

Production Theme (live)
├── ID: 123456789
├── Role: main
└── Updated via releases only

Staging Theme
├── ID: 987654321
├── Role: unpublished
└── Used for client review

Development Theme
├── ID: auto-generated
├── Role: development
└── Used for local development

Pre-Deployment Checklist

## Before Deployment

### Code Quality

- [ ] All features tested locally
- [ ] No console errors
- [ ] No Liquid errors (check theme editor)
- [ ] Theme Check passes

### Compatibility

- [ ] Cross-browser tested
- [ ] Mobile responsive verified
- [ ] Accessibility checked

### Performance

- [ ] Lighthouse score acceptable
- [ ] Images optimized
- [ ] No unnecessary assets

### Content

- [ ] Version number updated
- [ ] Changelog updated
- [ ] Documentation current

### Backup

- [ ] Current live theme downloaded
- [ ] Git tag created

Rollback Strategy

Quick Rollback

# Download previous theme version
shopify theme pull --theme previous-theme-id

# Or use Git tags
git checkout v1.1.0
shopify theme push --live --force

Theme Backup

# Before major deployments
shopify theme pull --live --path backup-$(date +%Y%m%d)

Theme Check

Run before deployment:

# Check for issues
shopify theme check

# Fix auto-fixable issues
shopify theme check --fix

# Check specific files
shopify theme check --path sections/

Common Checks

## Theme Check Categories

- Liquid syntax errors
- Missing translations
- Deprecated features
- Performance issues
- Accessibility problems
- Asset issues

Deployment Scripts

Package.json Scripts

{
  "scripts": {
    "dev": "shopify theme dev",
    "push:dev": "shopify theme push --development",
    "push:staging": "shopify theme push --theme $STAGING_ID",
    "push:live": "shopify theme push --live --ignore config/settings_data.json",
    "pull:live": "shopify theme pull --live",
    "check": "shopify theme check",
    "backup": "shopify theme pull --live --path ./backups/$(date +%Y%m%d)"
  }
}

Usage

npm run dev          # Local development
npm run push:dev     # Push to dev theme
npm run push:staging # Push to staging
npm run check        # Run theme check
npm run push:live    # Deploy to production

Safe Deployment Practices

1. Never Push settings_data.json

# Always ignore merchant settings
shopify theme push --ignore config/settings_data.json

2. Use Unpublished Themes for Testing

# Push to unpublished theme first
shopify theme push --theme staging-id

# Test thoroughly
# Then push to live

3. Deploy During Low Traffic

Avoid peak shopping hours
Consider timezone of primary audience
Never deploy before major sales events

4. Monitor After Deployment

## Post-Deployment Monitoring

- [ ] Check for JavaScript errors
- [ ] Verify critical pages load
- [ ] Test checkout flow
- [ ] Monitor error tracking (if available)
- [ ] Check Core Web Vitals

Practice Exercise

Set up a deployment workflow:

Initialize Git repository
Create branch strategy
Write deployment scripts
Document process in README
Practice a complete release cycle

Key Takeaways

Semantic versioning communicates change scope
Git branching organizes development
Meaningful commits document history
Changelog tracks releases
Shopify CLI automates deployment
Pre-deployment checklist catches issues
Safe practices prevent disasters

What’s Next?

The next lesson covers Automated Deployment with Buddy CI/CD for continuous integration.