# Prompt versioning: keep changes and run evidence connected

Build a prompt versioning workflow that preserves text, variables, model settings, and evaluation evidence. Review changes and recover your baseline reliably.

Prompt versioning is the practice of retaining identifiable prompt revisions so a team can explain which instructions produced an output. Useful versioning includes the execution context that changes behavior, not only the latest text in an editor.

A revision history becomes operational evidence when it connects a change to frozen evaluation cases and the exact configuration used to run them. This guide describes that record and a release workflow you can adopt in a repository or a prompt platform.

## Key points

- **Keep revisions immutable:** An incident must still resolve to the same prompt after labels move.
- **Version the contract:** Variables and message roles are part of behavior.
- **Preserve the comparison:** A release decision needs pinned cases and scoring rules.

## What belongs in a prompt version?

Record the system and user message templates, variable names, expected types, and the output contract. Associate the version with the model route and settings used for an evaluation. If the application adds retrieval context or tools, retain the relevant application configuration separately.

Treat version identifiers as evidence pointers. A mutable production label tells you where new requests should go; the resolved immutable version tells you what an individual request actually used.

### Example release record — illustrative

```
{
  "promptVersion": "support-triage-v4",
  "variables": [
    "ticket",
    "policy"
  ],
  "modelRoute": "your-pinned-model-route",
  "datasetVersion": "support-cases-v2",
  "evaluatorVersion": "escalation-check-v1",
  "previousRelease": "support-triage-v3"
}
```

## Review the behavioral diff

A text diff shows where wording changed. A behavioral review asks which requirement the edit changes. Removing “escalate active outages” is more important than reorganizing examples, even if the removed sentence is shorter.

Annotate the intended effect of an edit and identify the cases that should expose it. Include at least one case that should remain unchanged. That prevents the evaluation from measuring only the benefit the author hoped to see.

- [Compare prompt text locally](https://www.promptlens.io/tools/prompt-diff)

## Freeze the comparison conditions

Run the baseline and candidate on the same cases with the same evaluator definitions. A changed dataset or judge can explain a changed score independently of the prompt. If multiple variables must change, keep those experiments separate enough to identify the cause.

Inspect pass-to-fail flips, newly introduced parsing errors, and scenario-level changes before accepting an aggregate improvement. Record missing or failed evaluations separately from scored passes.

## Move the release pointer with a recovery plan

After review, identify the version selected for future requests and retain the previous version as a recovery target. Confirm that the running application actually records the resolved prompt version. Caches and long-lived sessions can make a deployment pointer change take effect at different times.

Use the permissions and publication controls documented by your chosen platform. The general method does not imply that every platform supplies deployment automation, traffic experiments, or an unattended CI release mechanism.

- [Langfuse version and label concepts](https://langfuse.com/docs/prompt-management/overview)
- [PromptLens prompt workflow](https://www.promptlens.io/docs/prompts/versions)

## Make version history useful during an incident

Prompt versioning works when a reviewer can recover the instructions, execution settings, test evidence, and release decision behind an output. Save that connected record before a release, while the context is available, instead of trying to reconstruct it after users report a regression.

## Related resources

- [Prompt management tools](https://www.promptlens.io/guides/prompt-management-tools)
- [Regression release checks](https://www.promptlens.io/llm-regression-testing)
- [Dataset starter](https://www.promptlens.io/templates/customer-support-evaluation)