Versioning Prompts & Templates

Overview

Conductor’s component versioning system (powered by Edgit) enables independent evolution of prompts, templates, and other components without coupling them to application code releases. This guide covers strategies, patterns, and best practices for versioning components effectively. Perfect for teams that need to:

Update AI prompts rapidly without code deployments
A/B test template variations simultaneously
Roll back specific components independently
Maintain different component versions across environments
Track component evolution over time

Quick Example

# Create and version a prompt
echo "You are a data analyst..." > prompts/analyst.md
edgit components add data-analyst prompts/analyst.md prompt
edgit tag create data-analyst v1.0.0
edgit deploy set data-analyst v1.0.0 --to production

# Iterate on the prompt
vim prompts/analyst.md  # Improve instructions
edgit tag create data-analyst v1.1.0
edgit deploy set data-analyst v1.1.0 --to staging

# Test both versions simultaneously
# Production: prompt://data-analyst@v1.0.0
# Staging:    prompt://data-analyst@v1.1.0

# Promote when ready
edgit deploy set data-analyst v1.1.0 --to production

Why Component Versioning?

Independent Evolution

Components evolve at different speeds:

# Your repository timeline
Week 1: API v1.0.0, Prompt v1.0.0, Template v1.0.0
Week 2: API v1.0.0, Prompt v1.1.0, Template v1.0.0  # Improved prompt
Week 3: API v1.1.0, Prompt v1.1.0, Template v1.1.0  # New API + template
Week 4: API v1.1.0, Prompt v2.0.0, Template v1.1.0  # Major prompt update

# Without component versioning:
# - Prompt changes force new API deployment
# - Template tweaks require full release cycle
# - Can't test prompt improvements independently

# With component versioning:
# - Update prompts instantly (zero downtime)
# - Test new templates in staging, keep prod stable
# - Mix and match versions optimally

Zero-Downtime Updates

Update components without restarting or redeploying:

# Traditional deployment
Update prompt in code
Rebuild application
Deploy to staging
Test
Deploy to production (service restart)
Monitor for issues
Rollback entire deployment if problems occur

# Component versioning
Update prompt file
Create new version (edgit tag create)
Deploy to staging (instant, no restart)
Test
Deploy to production (instant, no restart)
Monitor for issues
Rollback just the prompt if needed (instant)

A/B Testing Made Simple

Run multiple versions simultaneously:

# Test prompt improvements
members:
  - name: analyze-control
    type: Think
    config:
      prompt: prompt://analyst@v1.0.0  # Control (stable)

  - name: analyze-variant-a
    type: Think
    config:
      prompt: prompt://analyst@v1.1.0  # Variant A (improved)

  - name: analyze-variant-b
    type: Think
    config:
      prompt: prompt://analyst@v2.0.0  # Variant B (major update)

# Route traffic based on experiment group
  - name: analyze
    type: Route
    config:
      routes:
        - condition: ${input.group === 'control'}
          member: analyze-control
        - condition: ${input.group === 'variant-a'}
          member: analyze-variant-a
        - condition: ${input.group === 'variant-b'}
          member: analyze-variant-b

Semantic Versioning

Version Format

Follow semantic versioning: vMAJOR.MINOR.PATCH

v1.0.0  # Initial version
v1.0.1  # Patch: Bug fix
v1.1.0  # Minor: New feature (backward compatible)
v2.0.0  # Major: Breaking change

Prompt Versioning

Patch (v1.0.0 → v1.0.1): Minor fixes, no behavior change

# Fix typos or formatting
- "Analyz the data"  # Typo
+ "Analyze the data"

# Clarify existing instructions
- "Be helpful"  # Vague
+ "Be helpful and provide detailed explanations"

edgit tag create data-analyst v1.0.1

Minor (v1.0.0 → v1.1.0): Enhanced functionality, backward compatible

# Add optional capabilities
+ "If the user asks for visualizations, suggest appropriate chart types."

# Improve prompt engineering
+ "Think step-by-step before providing your answer."

# Add examples (few-shot learning)
+ "Example: Given revenue data [100, 120, 110], identify the trend..."

edgit tag create data-analyst v1.1.0

Major (v1.0.0 → v2.0.0): Breaking changes to behavior or interface

# Change output format
- "Provide analysis as narrative text"
+ "Provide analysis as structured JSON with specific fields"

# Change variable names
- Variables: {data, context}
+ Variables: {dataset, metadata, options}

# Fundamental behavior change
- "Provide brief summaries"
+ "Provide comprehensive analysis with citations"

edgit tag create data-analyst v2.0.0

Template Versioning

Patch (v1.0.0 → v1.0.1): Visual tweaks, no structure change

# Fix styling issues
- <p style="color: red">  # Wrong color
+ <p style="color: #dc3545">

# Correct typos in static text
- "Welcom to our app"
+ "Welcome to our app"

edgit tag create welcome-email v1.0.1

Minor (v1.0.0 → v1.1.0): New sections, backward compatible

# Add optional sections
+ {{#if promotion}}
+   <div class="promo">{{promotion}}</div>
+ {{/if}}

# Add new styling options
+ <style>
+   .dark-mode { background: #000; color: #fff; }
+ </style>

edgit tag create welcome-email v1.1.0

Major (v1.0.0 → v2.0.0): Breaking structural changes

# Change required variables
- Variables: {name, email}
+ Variables: {user.name, user.email, user.preferences}

# Redesign with different structure
- <h1>{{title}}</h1>
- <p>{{content}}</p>
+ <header>{{>header}}</header>
+ <main>{{>content}}</main>
+ <footer>{{>footer}}</footer>

edgit tag create welcome-email v2.0.0

Versioning Strategies

Strategy 1: Latest Tag

Use @latest for rapid iteration:

members:
  - name: analyze-data
    type: Think
    config:
      prompt: prompt://analyst@latest  # Always use newest version

# Workflow
edgit tag create data-analyst v1.0.0
edgit deploy set data-analyst v1.0.0 --to latest  # Point latest to v1.0.0

# Update
edgit tag create data-analyst v1.1.0
edgit deploy set data-analyst v1.1.0 --to latest  # Move latest to v1.1.0

Pros:

Always use newest version automatically
Single reference point to update
Fast iteration

Cons:

Unpredictable behavior if latest changes unexpectedly
Harder to debug “it worked yesterday” issues
No explicit version in code

Use When:

Development environment
Rapid experimentation
Non-critical workflows

Strategy 2: Pinned Versions

Explicitly pin to specific versions:

members:
  - name: analyze-data
    type: Think
    config:
      prompt: prompt://analyst@v1.0.0  # Pinned to v1.0.0

# Update workflow
1. Create new version: edgit tag create data-analyst v1.1.0
2. Test in staging
3. Update ensemble.yaml: prompt://analyst@v1.1.0
4. Deploy ensemble changes

Pros:

Explicit version control
Predictable behavior
Easy to track what’s deployed
Simple rollback (just change version)

Cons:

Requires ensemble updates for component changes
More coordination between teams
Can’t update components independently

Use When:

Production environments
Critical workflows
Compliance requirements
Multi-team coordination needed

Strategy 3: Environment Tags

Use environment-specific tags:

members:
  - name: analyze-data
    type: Think
    config:
      prompt: prompt://analyst@${env.STAGE}  # Dynamic based on environment

# Deployment workflow
# Production
edgit deploy set data-analyst v1.0.0 --to production
# ENV: STAGE=production → prompt://analyst@production → v1.0.0

# Staging
edgit deploy set data-analyst v1.1.0 --to staging
# ENV: STAGE=staging → prompt://analyst@staging → v1.1.0

Pros:

Update components per environment independently
No ensemble changes needed
Clean separation between environments
Easy canary deployments

Cons:

Requires environment configuration
Less explicit than pinned versions
Need to track deployment tags separately

Use When:

Multi-environment setups (dev/staging/prod)
Canary deployments
Progressive rollouts
Regional variations

Strategy 4: Hybrid Approach

Combine strategies for different component types:

members:
  # Critical prompts: pinned versions
  - name: fraud-detection
    type: Think
    config:
      prompt: prompt://fraud-detector@v2.1.0  # Pinned (critical)

  # Marketing templates: environment tags
  - name: send-newsletter
    type: Email
    config:
      template: template://newsletter@${env.STAGE}  # Environment (frequent updates)

  # Experimental features: latest
  - name: analyze-sentiment
    type: Think
    config:
      prompt: prompt://sentiment@latest  # Latest (experimental)

Use When:

Complex systems with varying criticality
Different update frequencies per component
Balance between stability and agility

Deployment Workflows

Workflow 1: Direct to Production

For low-risk updates:

# 1. Update component
vim prompts/analyst.md

# 2. Create version
edgit tag create data-analyst v1.0.1

# 3. Deploy directly to production
edgit deploy set data-analyst v1.0.1 --to production

# 4. Monitor
# Rollback if needed: edgit deploy set data-analyst v1.0.0 --to production

Workflow 2: Staging → Production

For tested updates:

# 1. Update component
vim prompts/analyst.md

# 2. Create version
edgit tag create data-analyst v1.1.0

# 3. Deploy to staging
edgit deploy set data-analyst v1.1.0 --to staging

# 4. Test thoroughly
curl -X POST https://api-staging.myapp.com/analyze -d '{"data": [...]}'

# 5. Promote to production
edgit deploy set data-analyst v1.1.0 --to production

# 6. Monitor and validate

Workflow 3: Canary Deployment

Progressive rollout:

# 1. Create new version
edgit tag create data-analyst v1.2.0

# 2. Deploy to canary environment
edgit deploy set data-analyst v1.2.0 --to canary

# 3. Route 5% of traffic to canary
# (in ensemble config)
members:
  - name: analyze
    type: Route
    config:
      routes:
        - condition: ${random() < 0.05}
          prompt: prompt://analyst@canary    # 5% get v1.2.0
        - default: true
          prompt: prompt://analyst@production  # 95% get v1.1.0

# 4. Monitor metrics (error rates, latency, quality)

# 5. Gradually increase canary percentage
# 5% → 10% → 25% → 50% → 100%

# 6. Promote to production when confident
edgit deploy set data-analyst v1.2.0 --to production

Workflow 4: Blue-Green Deployment

Zero-downtime switchover:

# Current state: Blue (v1.0.0) is live

# 1. Deploy new version to Green environment
edgit deploy set data-analyst v1.1.0 --to green

# 2. Test Green thoroughly
# Green environment uses: prompt://analyst@green

# 3. Switch traffic (atomic operation)
edgit deploy set data-analyst v1.1.0 --to production

# 4. Keep Blue as immediate rollback option
# Blue environment still has: prompt://analyst@blue (v1.0.0)

# 5. After validation period, update Blue
edgit deploy set data-analyst v1.1.0 --to blue

Multi-Version Testing

A/B Testing Framework

Test prompt variations systematically:

# ensemble.yaml
members:
  # Control group
  - name: analyze-control
    type: Think
    config:
      prompt: prompt://analyst@v1.0.0
      model: claude-3-5-sonnet-20241022

  # Variant A: Different prompt engineering
  - name: analyze-variant-a
    type: Think
    config:
      prompt: prompt://analyst@v1.1.0  # "Think step-by-step"
      model: claude-3-5-sonnet-20241022

  # Variant B: Different model + prompt
  - name: analyze-variant-b
    type: Think
    config:
      prompt: prompt://analyst@v2.0.0  # Optimized for GPT-4
      model: gpt-4

  # Router for experiment
  - name: analyze
    type: Route
    config:
      routes:
        - condition: ${input.experimentGroup === 'control'}
          member: analyze-control
        - condition: ${input.experimentGroup === 'variant-a'}
          member: analyze-variant-a
        - condition: ${input.experimentGroup === 'variant-b'}
          member: analyze-variant-b

  # Track metrics
  - name: track-experiment
    type: Data
    config:
      query: |
        INSERT INTO experiment_results (user_id, group, prompt_version, result, metrics)
        VALUES ($1, $2, $3, $4, $5)
      params:
        - ${input.userId}
        - ${input.experimentGroup}
        - ${member.analyze.output.version}
        - ${member.analyze.output.result}
        - ${member.analyze.output.metrics}

Template Variations

Test email template designs:

members:
  # Original design
  - name: send-email-v1
    type: Email
    config:
      template: template://welcome@v1.0.0
      subject: "Welcome to MyApp"

  # Redesign with clearer CTA
  - name: send-email-v2
    type: Email
    config:
      template: template://welcome@v2.0.0
      subject: "Get Started with MyApp"

  # Alternative subject line
  - name: send-email-v3
    type: Email
    config:
      template: template://welcome@v2.0.0
      subject: "Your MyApp account is ready!"

  # Split traffic evenly
  - name: send-welcome
    type: Route
    config:
      routes:
        - condition: ${hash(input.email) % 3 === 0}
          member: send-email-v1
        - condition: ${hash(input.email) % 3 === 1}
          member: send-email-v2
        - condition: ${hash(input.email) % 3 === 2}
          member: send-email-v3

Version Tracking

Metadata Best Practices

Document component versions with rich metadata:

# Add metadata when registering
edgit components add data-analyst prompts/analyst.md prompt \
  --metadata '{
    "description": "Financial data analyst prompt",
    "provider": "anthropic",
    "model": "claude-3-5-sonnet-20241022",
    "temperature": 0.7,
    "maxTokens": 4096,
    "variables": ["dataset", "timeRange", "metrics"],
    "usedBy": ["financial-analysis", "quarterly-report"],
    "tags": ["finance", "analysis", "production"],
    "owner": "data-team@example.com"
  }'

# Version-specific notes
edgit tag create data-analyst v1.1.0 \
  --message "Add step-by-step reasoning; improves accuracy by 15%"

# Track changes
edgit tag list data-analyst
# v1.0.0 (Initial version)
# v1.0.1 (Fix typo in prompt)
# v1.1.0 (Add step-by-step reasoning; improves accuracy by 15%)
# v2.0.0 (Major update: structured JSON output format)

Changelog Management

Maintain a changelog for major components:

# prompts/analyst.CHANGELOG.md

## v2.0.0 (2024-11-15)

### Breaking Changes
- Changed output format from text to structured JSON
- Renamed variables: `data` → `dataset`, `context` → `metadata`

### Added
- Support for multiple chart types in recommendations
- Citation of data sources in analysis

### Migration Guide
Update ensemble config:
- Old: `data: ${input.data}`
- New: `dataset: ${input.data}, metadata: ${input.context}`

## v1.1.0 (2024-11-10)

### Added
- Step-by-step reasoning improves accuracy by 15%
- Few-shot examples for trend analysis

### Performance
- 15% improvement in analysis accuracy
- 20% more consistent outputs

## v1.0.1 (2024-11-05)

### Fixed
- Corrected typo: "Analyz" → "Analyze"
- Improved clarity in instructions

## v1.0.0 (2024-11-01)

### Initial Release
- Financial data analysis prompt
- Supports revenue, expense, and profit analysis
- Compatible with Claude 3.5 Sonnet

Deployment Tracking

Track what’s deployed where:

# Check deployment status
edgit deploy status data-analyst

# Output:
# Environment    Version    Deployed At
# production    v1.1.0     2024-11-10 14:30:00 UTC
# staging       v1.2.0     2024-11-15 10:15:00 UTC
# canary        v1.2.0     2024-11-15 09:00:00 UTC

# Track in monitoring
curl -X POST https://api.myapp.com/metrics \
  -d '{
    "component": "data-analyst",
    "version": "v1.1.0",
    "environment": "production",
    "event": "deployment"
  }'

Rollback Strategies

Instant Rollback

Roll back specific components immediately:

# Issue detected in production
# Current: prompt://analyst@v1.2.0 (causing errors)

# Rollback to previous version (instant, no restart)
edgit deploy set data-analyst v1.1.0 --to production

# Traffic now uses: prompt://analyst@production → v1.1.0
# Zero downtime, instant effect

Gradual Rollback

Shift traffic back gradually:

# Current: 100% on v1.2.0 (issues detected)

# Step 1: Deploy old version to canary
edgit deploy set data-analyst v1.1.0 --to canary

# Step 2: Route 10% to old version
# Update ensemble routing to send 10% to canary (v1.1.0)

# Step 3: Monitor improvement

# Step 4: Increase rollback percentage
# 10% → 25% → 50% → 75% → 100%

# Step 5: Full rollback
edgit deploy set data-analyst v1.1.0 --to production

Selective Rollback

Roll back for specific users or regions:

members:
  - name: analyze
    type: Route
    config:
      routes:
        # Premium users: use latest version
        - condition: ${input.user.tier === 'premium'}
          prompt: prompt://analyst@v1.2.0

        # All others: use stable version
        - default: true
          prompt: prompt://analyst@v1.1.0

Best Practices

1. Version Everything

Version all components, not just code:

# Prompts
edgit components add * prompts/*.md prompt

# Templates
edgit components add * templates/**/*.html template

# Configs
edgit components add * configs/*.yaml config

# SQL queries
edgit components add * queries/*.sql query

2. Test Before Promoting

Always test in lower environments:

# Never skip staging
edgit tag create component v1.1.0
edgit deploy set component v1.1.0 --to staging  # Test here
# ... thorough testing ...
edgit deploy set component v1.1.0 --to production  # Then promote

3. Small, Incremental Changes

Make small version jumps:

# Good: Small, testable changes
v1.0.0 → v1.0.1 (typo fix)
v1.0.1 → v1.1.0 (add optional feature)
v1.1.0 → v1.1.1 (performance tweak)

# Risky: Large jumps with many changes
v1.0.0 → v2.0.0 (complete rewrite, hard to debug issues)

4. Document Breaking Changes

Clearly mark and document breaking changes:

# In commit message
edgit tag create data-analyst v2.0.0 \
  --message "BREAKING: Change output format to JSON. See CHANGELOG.md for migration."

# In code comments
# prompts/analyst.md
<!--
BREAKING CHANGE in v2.0.0:
- Output format changed from text to JSON
- Required variables changed
- See migration guide: docs/migrations/v2.0.0.md
-->

5. Monitor Version Performance

Track metrics per version:

// Log version information with metrics
await context.logger.info('Component execution', {
  component: 'data-analyst',
  version: 'v1.1.0',
  duration: 1250,  // ms
  tokens: 850,
  success: true,
  environment: 'production'
});

// Query metrics by version
// "Which version has better performance?"
// "Did v1.2.0 increase error rates?"

6. Deprecation Policy

Establish clear deprecation timeline:

# v1.0.0: Current stable version
# v1.1.0: New version released
# v1.0.0: Marked deprecated, will be removed in 3 months

# v2.0.0: Major update
# v1.x.x: All 1.x versions deprecated, will be removed in 6 months

# Notify users
echo "⚠️  WARNING: prompt://analyst@v1.0.0 is deprecated."
echo "   Please upgrade to v1.1.0 or later."
echo "   v1.0.0 will be removed on 2025-02-01."

Troubleshooting

Version Not Found

Problem: Version not found: prompt://analyst@v1.1.0 Solutions:

# Check if version exists
edgit tag list data-analyst

# Create version if missing
edgit tag create data-analyst v1.1.0

# Check deployment
edgit deploy status data-analyst

# Redeploy if needed
edgit deploy set data-analyst v1.1.0 --to production

Unexpected Behavior After Update

Problem: New version behaves differently than expected Solutions:

# Check what version is actually deployed
edgit deploy status component-name

# Compare versions
git show components/component-name/v1.0.0
git show components/component-name/v1.1.0

# Rollback immediately
edgit deploy set component-name v1.0.0 --to production

# Debug with bypass cache
# cache: { bypass: true }

Mixed Versions in Production

Problem: Some regions using old version, others using new Solutions:

# Check all deployment tags
git tag -l "components/component-name/*"

# Sync all regions to same version
edgit deploy set component-name v1.1.0 --to us-west
edgit deploy set component-name v1.1.0 --to eu-central
edgit deploy set component-name v1.1.0 --to ap-southeast

Next Steps

Templates Guide

Deep dive into template versioning

Edgit Integration

Complete Edgit integration guide

Component Types

Learn about all component types

Email Campaign Example

Real-world versioning example

Conductor

Core Concepts

Guides

Member Types

Built-In Members

Examples

API Reference

Deployment

​Overview

​Quick Example

​Why Component Versioning?

​Independent Evolution

​Zero-Downtime Updates

​A/B Testing Made Simple

​Semantic Versioning

​Version Format

​Prompt Versioning

​Template Versioning

​Versioning Strategies

​Strategy 1: Latest Tag

​Strategy 2: Pinned Versions

​Strategy 3: Environment Tags

​Strategy 4: Hybrid Approach

​Deployment Workflows

​Workflow 1: Direct to Production

​Workflow 2: Staging → Production

​Workflow 3: Canary Deployment

​Workflow 4: Blue-Green Deployment

​Multi-Version Testing

​A/B Testing Framework

​Template Variations

​Version Tracking

​Metadata Best Practices

​Changelog Management

​Deployment Tracking

​Rollback Strategies

​Instant Rollback

​Gradual Rollback

​Selective Rollback

​Best Practices

​1. Version Everything

​2. Test Before Promoting

​3. Small, Incremental Changes

​4. Document Breaking Changes

​5. Monitor Version Performance

​6. Deprecation Policy

​Troubleshooting

​Version Not Found

​Unexpected Behavior After Update

​Mixed Versions in Production

​Next Steps

Templates Guide

Edgit Integration

Component Types

Email Campaign Example

Overview

Quick Example

Why Component Versioning?

Independent Evolution

Zero-Downtime Updates

A/B Testing Made Simple

Semantic Versioning

Version Format

Prompt Versioning

Template Versioning

Versioning Strategies

Strategy 1: Latest Tag

Strategy 2: Pinned Versions

Strategy 3: Environment Tags

Strategy 4: Hybrid Approach

Deployment Workflows

Workflow 1: Direct to Production

Workflow 2: Staging → Production

Workflow 3: Canary Deployment

Workflow 4: Blue-Green Deployment

Multi-Version Testing

A/B Testing Framework

Template Variations

Version Tracking

Metadata Best Practices

Changelog Management

Deployment Tracking

Rollback Strategies

Instant Rollback

Gradual Rollback

Selective Rollback

Best Practices

1. Version Everything

2. Test Before Promoting

3. Small, Incremental Changes

4. Document Breaking Changes

5. Monitor Version Performance

6. Deprecation Policy

Troubleshooting

Version Not Found

Unexpected Behavior After Update

Mixed Versions in Production

Next Steps