# What is prompt versioning?

> Prompt versioning gives every change to a prompt an identifier and a history, so you can compare versions, trace outputs to them and roll back.

Source: https://www.honeyhive.ai/learn/prompt-versioning (updated 2026-11-07)

Prompt versioning is applying version control to prompts: each change gets an identifier and a stored history, so you can tell which prompt produced an output, compare two versions and go back to an earlier one. Adobe's ColdFusion guide [frames it](https://guides.adobe.com/coldfusion/en/docs/coldfusion-ai-guide/prompt-versioning.html) as a controlled way to introduce improvements and breaking changes without disrupting existing workflows. It applies to any prompt you change over time, including a [system prompt](/learn/system-prompt).

## Where the version lives

Adobe's guide [describes](https://guides.adobe.com/coldfusion/en/docs/coldfusion-ai-guide/prompt-versioning.html) two ways to record it, and says many deployments combine them: a stable name with optional version metadata, and new names for major changes.

| Approach | Example | Upside | Downside |
|---|---|---|---|
| Version in the name | `summarize_document_v1` | Callers know which version they use, and versions coexist | Noisier prompt list, and every new version needs a new name |
| Version as metadata | a `version` field such as `1.1.0` | Names stay clean, and clients can take the latest or pin one | The client must respect the field, and the version may be less visible in the UI |

## What counts as a new version

[Semantic Versioning](https://semver.org/) increments MAJOR for incompatible changes, MINOR for backward compatible additions and PATCH for backward compatible fixes, and its rule 3 says the contents of a released version must not be modified. Prompts are not packages, but the same logic carries over. Adobe's guide [lists](https://guides.adobe.com/coldfusion/en/docs/coldfusion-ai-guide/prompt-versioning.html) what to treat as breaking, which warrants a new major version or name:

- removing or renaming an argument
- changing an argument's meaning or type
- changing the output format
- changing the core task

It treats clearer wording with the same goal, optional arguments with defaults, minor tone tweaks and bug fixes as non-breaking, so a minor bump is enough. The guide also says to keep the old version available until all callers are ready to upgrade, and to track which version is used in logs and analytics.

## Rollback

Rolling back is easiest when saved versions are never overwritten. In Google Cloud's prompt management, a prompt resource [contains](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/model-reference/prompt-classes) version history that stores previous saved versions, and `restore_version()` restores an older version as the latest version of the prompt. The restored prompt becomes the newest version instead of replacing the history.

## A prompt version is not the whole change

The same prompt can behave differently under a different model. OpenAI [advises](https://developers.openai.com/api/docs/guides/prompt-engineering) pinning production applications to specific model snapshots, with `gpt-4.1-2025-04-14` as its example, and building tests and evaluation suites so you can track performance as you iterate or upgrade models. It also says to add representative fixtures, tests and evaluation checks before changing production prompts. See [LLM evaluation](/learn/llm-evaluation) for how to run those checks and [prompt optimization](/learn/prompt-optimization) for improving a prompt systematically.

Where versions are stored is also a decision. As of November 2026, OpenAI [is deprecating](https://developers.openai.com/api/docs/guides/prompt-engineering) reusable prompt objects in its API: prompt creation was de-emphasized beginning June 3, 2026, `v1/prompts` is scheduled to shut down on November 30, 2026, and the guide recommends storing prompts in application code. It suggests feature flags or configuration for staged releases. Prompts kept with your code get the same history, review and rollback as the rest of it.

## Versioning prompts in HoneyHive

HoneyHive's docs [describe](https://docs.honeyhive.ai/v2/prompts/overview.md) a prompt as a configuration, a single record you can update or fork. Saving over an existing configuration overwrites it, so the docs say to fork first to preserve a working prompt. You can deploy a prompt to an environment such as dev, staging or prod. To tie outputs back to a version, the [tracing configuration](https://docs.honeyhive.ai/v2/tracing/configuration-details.md) guide shows how to attach details such as prompt version and model parameters to traces so you can correlate outputs with the settings that produced them. For the wider practice of improving prompts, see [prompt engineering](/learn/what-is-prompt-engineering).

## FAQ

### What is prompt versioning?

Prompt versioning is applying version control to prompts. Adobe's ColdFusion guide [describes](https://guides.adobe.com/coldfusion/en/docs/coldfusion-ai-guide/prompt-versioning.html) it as a controlled way to introduce improvements and breaking changes without disrupting existing workflows.

### Should the version go in the prompt name or in metadata?

Either works. Adobe's guide [lists](https://guides.adobe.com/coldfusion/en/docs/coldfusion-ai-guide/prompt-versioning.html) names such as summarize_document_v1 (explicit, but a noisier list) and a version field such as 1.1.0 (clean names, but clients must respect the field), and says many deployments combine them.

### What counts as a breaking change to a prompt?

Adobe's guide [lists](https://guides.adobe.com/coldfusion/en/docs/coldfusion-ai-guide/prompt-versioning.html) removing or renaming an argument, changing an argument's meaning or type, changing the output format and changing the core task. Clearer wording with the same goal is non-breaking.

### Does restoring an old prompt version overwrite the newer ones?

Not in Google Cloud's implementation. Its docs [say](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/model-reference/prompt-classes) restore_version() restores an older version as the latest version, so history stays intact.

### Is a prompt version enough to reproduce an output?

No, the model matters too. OpenAI [advises](https://developers.openai.com/api/docs/guides/prompt-engineering) pinning production applications to specific model snapshots and running evaluation checks before you change production prompts.