Staging a change

The person says: “Change the headline on the home page to ‘Open every night’ and put it live.”

The answer is one change set: the edit lands as a draft inside it, the person sees it rendered, and one promote puts it live with an undo. Follow next on every answer; it names the legal next step and fills in what the platform already knows (the site, the change set, the item).

The loop

1. Empress:whoami — which workspace, which sites, and the slug of the one the person means.
2. Empress:site_status — what is live and staged on that site now, and whether a change set is already open (join it instead of opening a second).
3. Empress:changeset_create — title is the person’s sentence, word for word.
4. Empress:content_query — find the item: name the collection when you know it, a query when you do not.
5. Empress:site_call — tool: "content_update", as next offers it, with the change set’s id; put only the fields the person asked to change in args.data. Leave out _rev: the current revision is read for you, and the answer has the new one and a preview of the draft.
6. Empress:site_preview — target: "draft"; look at every width before saying anything is done.
7. Empress:changeset_promote — only after the person has seen the preview and said yes; then confirm: true.
8. Empress:site_preview — target: "live": what visitors get now.
9. Empress:site_status — the versions section now shows the promote, and says whether Empress:version_revert can undo it.

Looking closer

The default preview is the first screen at a phone, a tablet and a laptop. For a layout review, look at the whole page: Empress:site_preview with target: "stage" (or "draft"), path: "/events" and fullPage: true draws the page top to bottom at each width, and says where it stopped when the page is taller than one picture. To refine one section, pass selector: ".section-rail" instead: each picture is that element alone, cropped to its box. The inline pictures are scaled down; open the link for the full-size file.

To check precisely rather than by eye, add probes: { tokens: true, layout: true, type: true }. tokens finds elements whose radius, font size, line height, spacing or colour is on no step of the theme’s own scale, with the step it is nearest; layout finds what overflows the page edge, text its box clips, stretched images, lines over about 80 characters and text below AA contrast; type detects fallback-font painting — a declared @font-face that failed to load or was never requested, and every text element whose painted family differs from its declared one. Each finding is one cause: it carries a count, the first three elements it applies to and the widths it was seen at (add detail: true for every element); fix those elements by name, then render again.

To see what a change does rather than what the page looks like, pass compare: "live" with the stage: both are drawn whole at each width, and the answer lists the regions that differ, each naming the element it sits in, with a link to the stage picture with those regions boxed. During a migration, compare with the site being replaced: declare its address once with Empress:site_call, tool: "empress.site_reference_set", args: { "origin": "https://www.example.com" } (Owner or Admin), then pass compare: "reference"; target: "reference" draws that site alone. To check against a design, bring the frame in as a 1x PNG with Empress:media_ingest and pass compare: { "asset": "<media id>" }. A region that changed on purpose is the change; one that did not is the thing to fix.

When a site is pinned

A pin holds a site to one release of its theme while the theme moves on, and the engine roll rebuilds that release for the new engine instead of the theme’s newest. Empress:site_status shows it in theme.pinned; when drift is true, what is live is not the pinned release, so the next roll will change what visitors see. Promoting a theme on a grouped site with choice: "pin" makes the same pin. To keep what is live, call Empress:site_call with tool: "empress.theme_pin" and args: { "ref": "live" }. To let the site follow its theme again, call it with tool: "empress.theme_unpin"; the theme’s newest release may be newer than anything the person has reviewed, so say so before you do it.

Judgment

• Read back is not proof. A draft read back from the CMS returns the draft; only the live render after the promote shows what visitors see.
• The person says yes, not you. confirm: true is their answer to a question you asked with the preview in front of them. If they are away, stop at step 6 and say what is waiting.
• One sentence, one set. A request that also touches the menu or the theme belongs in the same change set (see composing-a-change-set).
• A refusal is an instruction. It ends in Next:; do that, do not retry the same call.
• When the platform gets in the way, say so with Empress:empress_feedback after the task, in the person’s words.