Release channels and staged rollouts

Offer beta and release candidate builds to the sites that ask for them, and roll a release out to a share of sites at a time. This needs TierMint Pro.

The free update server offers every site your newest published release. A draft reaches no site. TierMint Pro adds two things to each release:

• a Channel, so a beta or release candidate draft reaches only the sites that asked for it
• a Rollout percentage, so a release reaches a growing share of sites instead of all of them at once

A beta or release candidate build stays a draft. TierMint Pro offers the draft to the sites on its channel. When you publish the draft, it becomes the stable release for every site, still at its rollout.

Both apply when a customer's plugin checks for updates. Nothing changes on a customer's site until its next update check. The update client keeps its answer for 12 hours, so a new offer, a stopped offer or a raised rollout can take that long to reach a site.

Offer a beta or release candidate build

Upload the release, set its channel on the draft, then offer it. The draft stays a draft, so a site on the stable channel never sees it.

1. Open TierMint → Products, open the product and click the Releases tab.
2. Under Upload a new release, fill in the version, package and changelog as usual, and click Upload release. The release is saved as a draft on the stable channel at 100%.
3. On the draft's row, click Channel and rollout.
4. Pick the Channel: Stable, Release candidate or Beta. A draft on the stable channel cannot be offered, so pick Release candidate or Beta.
5. Set the Rollout percentage. Leave it at 100 to reach every site on the channel.
6. Click Save. The row now shows the channel, and the rollout when it is below 100%.
7. Click Offer to beta sites. On the release candidate channel the button reads Offer to release candidate sites.

The row now shows Offered and this line: "Beta sites in the rollout get this draft now. Saved changes reach them. A new version or package stops the offer until you offer it again." On the release candidate channel, the line starts with "Release candidate and beta sites in the rollout get this draft now."

The channels nest:

A site on	Is offered
Stable	Published releases
Release candidate	Published releases and release candidate offers
Beta	Published releases, release candidate offers and beta offers

Rules for an offer

An offer needs a version that is newer than the latest published release and newer than any draft already offered on the same channel. Otherwise TierMint Pro refuses the offer with a message that names the version.

For a site on the beta or release candidate channel, a standing offer comes before the published releases, because an offer is always newer than the latest published release. When two offers reach the same site, the later offer comes first.

Edit an offered draft

• A change to the changelog or the compatibility fields applies to the offer at once. Sites see it at their next update check.
• A new version or a new package stops the offer. The row loses Offered. Click the offer button again to offer the draft.
• Moving the draft to Stable ends the offer.
• Moving the draft between Beta and Release candidate keeps the offer only if the draft is still the newest on the new channel. If another offer there has the same or a higher version, the save is refused with a message that names that version.

Stop offering a draft

Click Stop offering on the draft's row. The offer ends at once.

Download links that the update check already handed out keep working until they expire. By default a link lasts five minutes. Signed package downloads explains the link lifetime.

A site can still show the update notice for up to 12 hours, because the update client keeps its answer.

Publish the draft

Click Publish on the draft's row. The release becomes the stable release and keeps its rollout. TierMint Pro also withdraws every other offer of the product whose version is not newer than the one you published. A newer offer stays offered.

Published releases

A published release is always on the stable channel. Its row has a Rollout button that changes only the rollout. The window says "A published release is on the stable channel. Only its rollout can change."

To ship the same build to beta or release candidate sites again, yank and delete the release, then upload it again as a draft.

Stage a rollout and ramp it up

Rollout percentage is the share of sites a release reaches, as a whole number from 0 to 100. Each site gets a fixed position from 0 to 99, worked out from the site and the release. A release at 25% reaches the sites in positions 0 to 24.

The position stays the same for a site and a release, so raising the percentage only adds sites. A site that got the release at 25% still gets it at 50% and at 100%. Every site counts the same, whatever its traffic.

To ramp up a rollout:

1. Click Rollout on the published release. On a draft, click Channel and rollout.
2. Raise the Rollout percentage, for example from 10 to 50.
3. Click Save.

A release below 100% shows its percentage next to its channel in the list. An offered draft also shows Offered.

A site outside a staged release is offered the newest older release that reaches it, usually the previous full release. A rollout of 0 reaches no site.

Let your users choose a channel

Every site is on stable unless its copy of the update client asks for another channel. To offer early builds, add a setting to your own plugin and pass the chosen channel to the client's channel option:

new TierMint_Update_Client( array(
	'api_url'      => 'https://your-store.example/wp-json/tiermint/v1',
	'product_slug' => 'your-plugin',
	'plugin_file'  => __FILE__,
	'license_key'  => get_option( 'your_plugin_license_key' ),
	'channel'      => get_option( 'your_plugin_update_channel' ), // '', 'rc' or 'beta'.
) );

The client sends channel to every store. Only a store that runs TierMint Pro reads it.

An empty or missing channel means stable. A channel name the store does not know is also served as stable, so a typo never leaves a site with no updates. A change of channel takes effect at the site's next update check. The client caches each channel's answer separately, so a site that moves from beta back to stable does not get its old beta answer.

Manage channels and offers through the REST API

The routes need management authentication and the manage_tiermint capability, like the core release routes. The licensing REST API page explains how to authenticate.

Route	What it does
PATCH /tiermint/v1/pro/releases/{id}/distribution	Sets the channel, the rollout percentage or both.
POST /tiermint/v1/pro/releases/{id}/distribution/offer	Offers a draft to the sites on its channel.
POST /tiermint/v1/pro/releases/{id}/distribution/withdraw	Stops offering a draft.

Send PATCH /wp-json/tiermint/v1/pro/releases/87/distribution with the channel, the rollout percentage or both:

{
  "channel": "beta",
  "rollout_percent": 40
}

A release that is not a draft stays on the stable channel, so only its rollout can change. The offer and withdraw routes need no body.

Each route answers with the release's id, product_id, version, status and a distribution object. The object holds channel, rollout_percent, offered and offered_at. offered_at is null when the release is not offered.

An unknown channel, a rollout outside 0 to 100 or a refused offer returns 400 tiermint_invalid_params with every problem in data.errors, and nothing is saved. A rollout_percent that is not a whole number, null included, returns 400 rest_invalid_param. An unknown release id returns 404 tiermint_not_found.

With TierMint Pro active, the core release routes on the update server page add the same distribution object to each release. Change the channel, the rollout and the offer only through the routes above.

Channel and rollout limits

The channels are stable, rc and beta. You cannot add your own.

A yanked release reaches no site, whatever its channel or rollout.

When Pro is deactivated

The free plugin then offers every site the newest published release. Offered drafts are not served, a staged rollout reaches every site, and a channel request is ignored. The channel, rollout and offer buttons leave the release rows.

TierMint Pro keeps its channel and offer data, so they apply again when Pro is active again.