Developers · Releases and review
Releases and review
Every version, first or fiftieth, goes through the same steps: automatic checks in about a minute, then a person. Nothing reaches a merchant's shop unreviewed.
Numbers
Versioning
Versions are semver, and the kind of version decides what it may change. A merchant decides whether to take an update based on that number, so it has to mean what it says.
| Kind | Example | May change |
|---|---|---|
| Patch | 1.4.2 → 1.4.3 | Fixes. No new settings the merchant has to fill in, no removed sections. |
| Minor | 1.4.3 → 1.5.0 | New sections, settings and tokens. Nothing removed. |
| Major | 1.5.0 → 2.0.0 | May remove or rename sections, with migrations for every one. |
"version": "2.0.0",
"migrations": {
"sections": { "harbour.slideshow": "harbour.hero", "harbour.ticker": "drop" },
"settings": { "headline": "heading" },
"tokens": { "brandColor": "colorAccent" }
}A section with no mapping is left on the merchant's page and flagged, never deleted, because the merchant's copy lives in its settings. That is why a removal without a migration is blocked.
Side by side
Building the next version
Your working copy and the version the catalogue sells are two separate things. You can take 2.0.1 apart for a week while merchants keep buying, installing and viewing the demo of 2.0.0.
| Changes when | |
|---|---|
| Your working copy | You save, in the editor, the CLI or Claude. |
| Your development shop | You preview. Only you see it. |
| The catalogue and its demo | A reviewer approves a version. The showcase shop is upgraded to it automatically, with its products and pages kept, and the still on the theme's page is taken again. |
| Merchants' shops | Each merchant updates, when they choose to. |
A showcase never takes previews, so a half-finished header cannot reach the demo. Preview on another development shop.
whizzy-theme reset --yes, or ask Claude (reset_theme). Every change you never submitted is thrown away; submitted versions stay where they are.Automatic
The checks
They run when you submit, and validate_theme runs the bundle checks at any time. A block stops the submission with reasons. A warning goes to you and to the reviewer.
| Check | What it verifies | At worst |
|---|---|---|
valid | The theme installs. Anything the validator would drop is listed; a theme that does not install at all is blocked. | block |
css | The CSS survives sanitising and scoping. Dropped rules and more than 100 kB warn; more than 180 kB blocks. | block |
version | The version is newer than the last one you submitted or published. | block |
sections-removed | No section type went away, unless this is a major version and migrations say where each one went. | block |
class-collisions | No class name is styled by two different sections. | block |
plugins | Every declared plugin is in the catalogue at a version inside your range. | block |
changelog | There is a changelog of at least 10 characters. | block |
renders | Every page the theme lays out answers without an error on your development shop. | block |
screenshots | Home, collection and product are photographed at 390, 768 and 1440 pixels for the reviewer. | warn |
performance | The home page HTML is under 600 kB and every image has a width. | warn |
A person
What reviewers look at
The reviewer sees your screenshots beside the last published version's, a structural diff of sections, settings and CSS, the check results and your changelog. Then they go through this list.
- The listing's claims are true: every feature it names is in the theme.
- The theme looks right on a phone, a tablet and a desktop, on every page it lays out.
- Demo content is licensed: the sample catalogue, or assets you can show a licence for.
- No copying of another brand's or theme's design, name or trademark.
- Text a merchant would reword is a setting, not a literal.
- The changelog says what changed in words a merchant understands.
- The support email works.
- Warnings from the checks are explained or fixed.
How long
Review times
Our target is two business days from submission to a decision. The theme's page in your Developer area shows where your version is in the queue.
Back to you
When changes are requested
Most first submissions get at least one round. It is normal.
Notes arrive
Developer › Themes › your theme, email, get_release_status
The reviewer writes what to change, with the page and width where they saw it.Fix in your workspace
Your submitted version is not edited; you keep working on the files as usual.Bump the version
Usually the patch number. A version number can only be submitted once.Submit again
whizzy-theme submit -m "Addresses review notes"Say in the changelog what you changed.
You can withdraw a version that is still waiting for review from the theme's page. A version can also be rejected outright, for example for copied work; the notes say why.
Earned
Trusted developers
After a record of clean releases, staff can mark your account as trusted.
A trusted developer's patch release of a theme that is already listed is published automatically when every check passes with no warnings. Minor and major versions, and any release with a warning, still go to a person. Staff can pull an automatic release back, and a problem with one can cost the trusted status.
Delivery
How merchants receive updates
Publishing a version never changes a live shop by itself.
- Shops on an older version see an update notice under Design › Themes, with your changelog.
- The merchant chooses when to update. Nobody's shop changes under them.
- Migrations run when they update, so their sections and settings follow your renames.
- Updates are free for anyone who bought the theme. See pricing rules.