A prompt is part of how your app behaves. When it changes, the answers change, and sooner or later someone asks which wording produced a bad answer, or how to get yesterday's prompt back. Prompt versioning is how you answer both questions in seconds.
What prompt versioning means
Each time a prompt is published, its text is saved as a new numbered version: v1, v2, v3. One version is live, and that's the one your app is served. Work in progress is a draft, which no app sees until it's published.
That's the whole model: versions that never change, and a pointer to the live one. Everything else follows from it. Try it below: pick a version to compare it with live, then make it live.
Why a version must never change
If v3 can be edited after it's published, "v3" stops meaning anything. A rollback to v3 might bring back text nobody has tested, and a log line saying an answer came from v3 can't tell you what v3 said at the time.
So a published version is read-only, and fixing a typo in it means publishing v4. The numbers grow quickly, and that's fine: versions are cheap, and each one is a record of exactly what your app sent.
Rollback is moving a pointer
Because old versions never change, rolling back creates nothing new. It points live at an older version. Nothing is rebuilt or redeployed, and the bad version stays in the history so you can see what went wrong.
Your app follows a rollback the same way it follows a publish. If it fetches prompts at runtime with a cache, as in changing a prompt without a redeploy, the rollback reaches every running copy within one cache ttl. Two details make that dependable:
- Name the live version, not the newest. If clients revalidate with an
ETag(RFC 9110), derive it from the live version. Then a rollback changes it, and every cache notices, just as with a publish. - Rolling forward is the same move. If the newer version was fine after all, make it live again. Nothing was lost.
Review the change before it goes live
Most prompt regressions are small: a dropped instruction, a softened rule, a variable renamed in the text but not in the code. They're easiest to catch as a word-by-word diff against the live version, at the moment you publish.
Good questions for that review: Did an instruction disappear? Is there a new variable the code doesn't pass yet? Does the tone still match the rest of the product? For prompts that matter most, run a few real inputs through the new version before you publish it.
Record which version answered
Versioning pays off when you can trace an answer back to the text that produced it. Log the prompt's name and version beside each model call, together with the model and its settings.
PromptHelm's HTTP API returns the version with the text, so it's there to log:
{
"slug": "support-reply",
"version": 4,
"content": "You are the support assistant for {{company}}. …",
"variables": ["company", "customer_name"]
}Version what else changes the answer
The text isn't the only thing that shapes an answer. The model, its temperature, the tools it can call and the context you add all do too. A prompt version tells you what the instructions said; it can't tell you the model changed underneath them.
Keep those settings under version control as well, usually in the code beside the call, and log them with the prompt version. When answers change and nobody published a prompt, look there first.
Isn't git enough?
Prompts kept in the repository are versioned by git, reviewed in pull requests and tied to the code that uses them. For a small team that deploys several times a day, that can be all you need.
The cost shows when prompts change faster than the code, or when people outside engineering write them. Every change and every rollback then waits for a deploy, and a prompt's history is mixed in with everything else in the log. That's when a prompt store with its own versions earns its place.
How PromptHelm versions prompts
- Every publish creates a numbered version that never changes. Edits wait in a draft until you publish.
- Publishing shows the change from the live version, word by word, and Undo stays a click away afterwards.
- History lists every version. Making one live is a click, and your app follows on its next refresh.
- The API's
ETagis derived from the live version, so publishes and rollbacks both reach cached clients. - A version holds the model settings with the text, the model, temperature and max tokens, so a rollback restores both. A fallback carries none, so keep your defaults in the code.
The quickstart takes you from signing up to your first published version.