Promoting a preview build to stable

Preview channels let you push iterative builds of an unreleased version — 2.0.5-dev.1, 2.0.5-dev.2, … — to opt-in test sites without touching what your customers run. Once a preview build checks out, Promote to stable publishes that exact build as your next stable release in one click. No second commit, no re-tagging, no manual zip.

Availability note. Preview channels and their -dev.N builds ship today. The one-click Promote to stable action described below is fully wired on the backend, but its dashboard button is currently turned off — so this page documents the promote flow ahead of the UI being switched on.

This guide assumes you already have a preview channel with a current build. For how releases work in general, see Publishing a plugin or theme.

What promote does

Open the product, find the preview channel row (it shows the current build as its full preview version, e.g. 2.0.5-dev.7 — base version 2.0.5, build number 7), and click Promote to stable. The confirm dialog spells out the resulting version. Confirm, and VelvetPress publishes the channel's current build as the stable release at the base version.

From there the normal update path takes over: stable-bound customer sites poll GET /update/<slug>, see the new version, and offer Update Now in wp-admin.

You ship exactly what you tested

The promoted artifact is the same bytes you validated on your test sites. VelvetPress does not rebuild from source when you promote — it takes the stored preview zip and re-stamps a single line: the Version: header, from 2.0.5-dev.7 to the clean 2.0.5. Every other file in the package is byte-for-byte identical to the build your test sites ran.

This matters because a rebuild can quietly differ from what you tested — a newer dependency resolves, a build tool emits different output. Promote sidesteps that entirely: what shipped is provably what you validated.

How the version is derived

The stable version is derived, not prompted. VelvetPress strips the VelvetPress-owned -dev.N suffix to get the base version — 2.0.5-dev.7 promotes to 2.0.5. That base is the release number you already declared in your plugin or theme header; there is no version field to fill in.

To release a different number, change the Version: header in your source and push a new build, then promote that.

When promote is blocked

Promote is refused — loudly, with no change to what customers see — in two cases:

• Stable is already at or above the base version. If stable already serves 2.0.5 (or higher), re-promoting 2.0.5-dev.7 would advertise 2.0.5 to sites already running 2.0.5, which WordPress treats as "no update" — your fix would silently never arrive. Bump the version in your header and push a new build to release again.
• The channel has no current build. There is nothing to promote until the channel has built at least once.

The dashboard reflects these as a disabled action with the reason, so you see why before you click.

What happens after you confirm

Promote completes asynchronously — a worker re-stamps and republishes the artifact, and the channel row reflects the in-progress and finished states. Once stable advances, VelvetPress's existing propagation pulls your preview channels forward to the released version too: the channel you promoted from (and any other preview channel it supersedes) is advanced to 2.0.5, so test sites land on the clean release through the normal updater instead of staying on a -dev build.