# Versioning

PromptPack follows semantic versioning (SemVer) to ensure compatibility and provide clear expectations for users and implementers.

## Semantic Versioning

Version numbers follow the format `MAJOR.MINOR.PATCH` where:

- **MAJOR** - Incremented for incompatible API changes
- **MINOR** - Incremented for backwards-compatible functionality additions  
- **PATCH** - Incremented for backwards-compatible bug fixes

### Examples

- `1.0.0` - Initial stable release
- `1.1.0` - Added new optional fields (backwards compatible)
- `1.1.1` - Fixed documentation or clarified behavior (no schema changes)
- `2.0.0` - Removed deprecated fields or changed required fields (breaking change)

## What Constitutes a Breaking Change

### Major Version Changes (Breaking)

- **Removing required fields** from any entity
- **Changing field types** (e.g., string to number)
- **Renaming fields** or entities
- **Removing entity types** (prompts, tools, workflows, etc.)
- **Changing validation rules** that make previously valid files invalid
- **Modifying template syntax** in incompatible ways

### Minor Version Changes (Backwards Compatible)

- **Adding new optional fields** to existing entities
- **Adding new entity types**
- **Adding new validation options** (that don't break existing files)
- **Expanding allowed values** for enumerated fields
- **Adding new features** that don't affect existing functionality

### Patch Version Changes (Backwards Compatible)

- **Documentation updates** and clarifications
- **Example corrections** and improvements
- **Clarifying ambiguous behavior** without changing functionality
- **Fixing typos** in specification text

## Version Support Policy

### Current Version

- **Full support** - Active development and bug fixes
- **Latest features** - All new capabilities available
- **Community support** - Active help and discussion

### Previous Major Version  

- **Maintenance support** - Critical bug fixes only
- **Security updates** - Vulnerabilities addressed
- **No new features** - Feature development focused on current version
- **Duration** - 12 months after new major version release

### Older Versions

- **No official support** - Community support only
- **No updates** - No bug fixes or security patches
- **Deprecation warnings** - Migration guidance provided

## Migration Guide

When breaking changes occur, we provide:

### Automated Migration Tools

- **Schema converters** for common breaking changes
- **Validation tools** to identify compatibility issues
- **Command-line utilities** for bulk file updates

### Documentation

- **Migration guides** with step-by-step instructions
- **Change summaries** highlighting key differences  
- **Code examples** showing before/after patterns
- **FAQ sections** addressing common migration questions

### Community Support

- **Migration assistance** during community office hours
- **Discussion forums** for migration questions
- **Example repositories** showing migration patterns

## Version History

### v1.4.0 (Current)

- Agent loops extension ([RFC-0009](/docs/rfcs/agent-loops))
- Terminal states (`terminal: true`) for explicit workflow exit points
- Per-state `max_visits` with optional `on_max_visits` redirect
- Named `artifacts` slots that flow structured metadata across visits
- Global `engine.budget` (total visits, tool calls, wall time)
- Replayable execution traces — artifacts captured at every transition

### v1.3.1

- Skills extension ([RFC-0008](/docs/rfcs/skills-extension))
- Top-level `skills` array (paths, package references, or inline)
- SkillPathSource with optional `preload` flag
- WorkflowState `skills` field for directory-scoped filtering

### v1.3.0

- Workflow extension ([RFC-0005](/docs/rfcs/workflow-extension))
- Agents extension ([RFC-0007](/docs/rfcs/agents-extension))
- State-machine workflows with event-driven transitions
- Per-state context persistence (`transient`/`persistent`) and orchestration modes
- A2A-compatible Agent Cards with discovery tags and MIME types

### v1.2.0

- Evals extension ([RFC-0006](/docs/rfcs/evals-extension))
- Pack-level and prompt-level eval definitions
- Prometheus-style metric declarations (gauge, counter, histogram, boolean)
- Eval triggers: every_turn, on_session_complete, sample_turns, sample_sessions
- Prompt-level evals override pack-level evals by ID

### v1.1.0

- Multimodal content support ([RFC-0004](/docs/rfcs/multimodal-support))
- Image, audio, video, and document media types
- Extensible media types with GenericMediaTypeConfig

### v1.0.0

- Initial specification release
- Core entities: prompts, tools, workflows, personas, fragments
- YAML format with semantic validation
- Template variable system

### Planned Releases

#### v2.0.0 (Future)

- Potential breaking changes under consideration
- Advanced templating features
- Multi-file PromptPack support
- Binary format options

## Implementation Compatibility

### Runtime Requirements

Runtimes supporting PromptPack should:

1. **Clearly indicate** which specification version they support
2. **Validate compatibility** before processing files
3. **Provide helpful errors** for unsupported features
4. **Document limitations** and extensions

### File Versioning

PromptPack files specify their target version:

```yaml
apiVersion: v1  # Specification version
kind: PromptPack
metadata:
  version: 2.1.0  # PromptPack content version (separate from spec version)
```

### Forward Compatibility

- **Unknown fields** should be ignored (not cause errors)
- **Graceful degradation** when optional features aren't supported
- **Clear error messages** for unsupported required features

### Backwards Compatibility

- **Older runtimes** should reject newer specification versions gracefully
- **Version checks** should happen before processing begins
- **Helpful guidance** should be provided for upgrading

## Deprecation Process

When features need to be removed:

### 1. Deprecation Warning

- **Mark as deprecated** in documentation
- **Add deprecation notices** in validation tools
- **Provide migration path** to new approach
- **Timeline** for removal (minimum 12 months)

### 2. Transition Period  

- **Both old and new** approaches supported
- **Migration tools** available
- **Community education** about upcoming changes
- **Regular reminders** about deprecation timeline

### 3. Removal

- **Breaking change** in next major version
- **Complete removal** of deprecated feature
- **Updated documentation** reflecting changes
- **Migration assistance** for remaining users