Draft versus published
The editor is the draft. Saving writes that draft. Nothing a visitor (or a Staging / Production token) sees changes until you publish. Publishing compiles the draft into an immutable snapshot: the parameters, the enabled rules, the default, and the resolved published keys for this environment. Each publish creates a new version. History is append-only. You never edit a past snapshot in place.
Development is the exception. The Development resolve path reads the live draft. There is no publish step there, the same way Development integration already works for a single widget.
Who can press which button
Viewing and editing sit on the Widget Selection Access groups for that environment:
- View — open the list, the editor (read-only), the published snapshot, and history.
- Manage — create, edit, dry-run, copy, and resync cache when that control is shown.
- Admin — archive a draft and unpublish a snapshot.
Publish and promote reuse the same Staging / Production publish and promote permissions you already grant for widgets. A writer who can publish widgets to Staging can publish a ruleset to Staging. Production is the production permission. Lower environments (Development and any custom lower env) do not offer Publish — they offer Promote to Staging.
Publish a snapshot
- Finish the draft. Every rule outcome and the default must point at a widget that is published in this environment.
- Click Publish to Staging or Publish to Production, matching the environment you are in.
- The editor validates first. If something is wrong — missing default, unknown widget key, operator the schema will not compile — you get the issue list and nothing is published.
- Confirm. Optionally add a tag name and description, the same way you annotate a widget release.
- The first publish is version 1.0.0. Each later publish increments that number. The draft status becomes published. Open View published to read the compiled snapshot.
A cache-sync badge appears on the published head. After a successful publish you want ok — the snapshot was pushed to the cache that Staging and Production resolve from. failed (or stuck pending) means the dashboard write worked but the cache did not hear it. Click Resync; that retries the stored artifact and does not recompile the draft. A first resolve can still pull the snapshot on its own if the push missed.
Promote versus copy
These two actions look similar and do different jobs. Use the wrong one and you either overwrite a sibling environment or invent a second ruleset key you did not mean to have.
| Promote | Copy | |
|---|---|---|
| What it does | Writes this ruleset into the target environment under the same key, then publishes it there. | Creates a new draft in the target environment with a new key. It does not publish. |
| When to use it | The homepage hero is ready to leave Development for Staging, or Staging for Production. Same slot, next environment. | You want a fork — a second slot, or a sandbox to try a different order without touching the original. |
| What must already exist | Every widget key the ruleset names must be published in the target environment, or promote copies the draft and then stops with a validation list. | Nothing. The new draft can sit incomplete until you fix it. |
Promote from Development offers Staging. Promote from Staging offers Production. You cannot promote onto the environment you are already in. Copy can target any other environment on the project, including another lower environment.
Because outcomes store widget keys, promote does not rewrite the rules. It asks the target environment for those same keys. Publish the German hero, the Pro hero, and the default in Staging before you promote the ruleset, or you will be staring at a 422 with a list of missing widgets.
History and republish
History lists every published version, newest first. Open a version to read it. You cannot edit that page — it is the snapshot as it was compiled.
Republish copies that snapshot back onto the draft and publishes again as a new version. Version 1.0.0 stays 1.0.0. You get 1.0.1 (or whatever the next number is) whose contents happen to match the old one. Use this when last Tuesday's rules were right and this morning's were not. The widgets those old rules name still have to be published now, or republish will refuse.
Unpublish and archive
Unpublish (Admin) marks the published head inactive and returns the draft to draft status. The version history remains. Development resolve still works against the draft. Staging / Production resolve then answers that the ruleset was not found.
Archive (Admin, from the draft) hides the ruleset from the default list. You cannot archive a draft that still has an active published head — unpublish first. Archived rulesets come back on the list when you include archived.
Deleting a widget that an active published ruleset still names — as a rule outcome or as the default — is rejected. Unpublish or edit the ruleset first, then delete the widget. That guard exists so a live decision cannot point at a missing page.
A release habit that works
- Author and dry-run in Development.
- Publish each variant widget to Staging. Then promote the ruleset to Staging.
- Point your QA site at Staging resolve with a Staging token and the ruleset published key. The widgets those rules name must already be published in Staging.
- When QA is happy, publish the same widget keys to Production and promote the ruleset.
If you need a second experiment that must not overwrite the hero ruleset, Copy it, rename the copy, and keep the keys separate.