Shipping
Review & Release
On this page
Introduction
Every upload lands inactive, a human promotes it, and anything that widens what your applet can reach waits for explicit approval first. This page walks through that path from your side: what happens to your zip after you upload it, when it waits for a reviewer, and what your participants experience when a new version goes live.
Installing a Version
When you upload a zip, the Rack validates its manifest against the capabilities it implements, then records the version, extracts its files and runs each declared capability's install step, all as one unit. If anything fails, nothing is kept. Installing never touches your applet's existing data.
Your manifest's slug decides which applet the upload belongs to. A package whose slug already belongs to an applet you cannot manage is refused. A version may be uploaded only once per applet, so bump it for every upload. See Applet Versions.
A newly installed version arrives ready but not current. Your participants keep running whatever was current before, until someone promotes the new one.
The one exception is your applet's very first version. There is nothing to review a first version against, so it is promoted automatically.
Once installed, the Rack resolves your declared media and checks the package URLs in your SBOM against a vulnerability database. Findings attach to the version and are shown to the reviewer. They do not block the install.
Capability Diff Review
When you upload a new version of an existing applet, the Rack diffs its requires block against the current version:
{
"added": ["ai@1", "db@1"],
"removed": [],
"profile_added": ["business_unit"],
"profile_removed": [],
"pinning_changed": true,
"pinned": true
}In this example, the new version asks for two capabilities and one profile attribute the current version did not have.
Any addition, whether a capability or a profile attribute, blocks promotion until a reviewer approves it.
pinning_changed is flagged just as prominently, because adding or removing attempt@1 changes your applet's own update semantics from rolling to pinned, or back. See Version Pinning.
Removals need no approval. Narrowing what an applet can reach is always allowed.
If you know a release will add a capability or a profile attribute, expect it to wait for a human. Keeping such additions in their own release makes the reviewer's decision easy to read.
Promotion
Promoting a version makes it current. It is a deliberate human action, and the Rack refuses it when:
- the version is not ready,
- the version has a capability addition no reviewer has approved (the refusal names exactly what was added), or
- carrying your applet's data over to the new version needs a decision (see The Data Cutover).
Otherwise the data cutover, including loading the seed of any applet collection that is still empty, and the move of the current version commit together.
Keep in mind that your activity ids are what tie answers together across versions. Changing an activity's id between versions splits its export columns, while changing its label only changes the headers. See Designing for the Export.
Rolling and Pinned Applets
What promotion means for your participants depends on pinning:
- Rolling applet (no
attempt@1): everyone is on the new version at their next page load. - Pinned applet (
attempt@1): new attempts start on the new version, while attempts already in progress stay on the version they started on until they complete. Two versions run side by side until the old one drains.
The Data Cutover
Records outlive versions. If your applet declares db@1, its user, room and applet records carry over to every new version (see Data Across Versions), so promotion is also the moment your existing data meets the new version's collections.
If nothing about your data needs a decision, the version simply promotes. Otherwise, the promotion is refused with a plan of what changes and a reason, and waits:
| Situation | What happens |
|---|---|
The version ships data migrations that have to run: its pending ups, or downs for applied migrations it lacks. |
The version is promoted from the Rack's UI, which runs the migrations before committing. |
| No migration runs, and the new schema or quota rejects existing records, or a dropped collection still holds records. | Someone must confirm the loss before the version is promoted. |
| What the migrations returned does not fit the version. | You fix the migration and upload a new version. |
| The data changed between planning the cutover and committing it, or another promotion committed in the meantime. | The plan is reviewed again and the promotion retried. |
When records are rejected by the new schema, the person promoting may choose to discard them (the default) or keep them. Either way, nothing is lost silently.
A version that drops db@1 still goes through the cutover. All of your applet's collections count as removed, so promoting it needs the same confirmation as removing them one by one.
An upload that asks to be activated straight away is promoted only if the cutover needs no decision. If it does, the version is installed but not current, and it is promoted once the decision is made.
A migration runs over every participant's carried records, with no network. Write it to be safe to run once over the real data, and always ship a down so a rollback can reverse it.
Every cutover that changes data is preceded by a snapshot of the applet's whole dataset, so a cutover that goes wrong can be undone.
The Review Queue
Your version waits in the Rack's review queue when it has:
- new capabilities or profile attributes,
- vulnerability findings from the SBOM,
- manifest validation warnings that were overridden, or
- it is your first upload as a publisher.
When a reviewer looks at your version, they see the capability diff, the SBOM summary, any findings and you, the publisher.
Retiring a Version
A retired version can no longer be launched. In-progress attempts pinned to it land on a holding screen with an explanation, not a blank frame.
Retiring the current version leaves the applet with no current version until another is promoted. The Rack does not fall back to an older version on its own, so promote the one you want participants on.