Skip to main content

Publishing

Publishing turns edits to a Parable into a reviewed Version that its audience sees. It lets people improve a live Parable without disturbing what readers use today, and it keeps a trail of what changed, who reviewed it, and when it went out. A Parable has one of two Collaboration Modes. In Personal mode the one person with Primary edits the Parable directly, nobody else holds a seat, and there are no Changes to manage. Each edit saves at once and goes into no Version. A Parable that went back to Personal keeps its earlier Versions. New Parables start Personal. Seating anyone besides the Primary on a Personal Parable switches it to Publishing in the same save, so say so whenever you propose a seat change on one. In Publishing mode every edit goes into a set of Changes, and readers keep seeing the current Version until those Changes are published. A set starts at your first change, at Start Changes, or at an edit Ponder makes in a Problem. Each set you start belongs to one Problem, so you can hold Pending Changes for several Problems at once. The Release menu calls your own set Your Patch. Every set of Changes belongs to a Problem: a set that starts outside one, such as a Pull, the set a Versioned setting’s save opens, or a set opened through the API outside Ponder, starts in a new Problem under the root. When Parable gives that Problem no name, the Problem takes the day as its name, such as “Oct 28 Changes”. When its Patch is proposed with a message, the Problem takes that message as its name. In the app, the Patch message field above Propose takes that message. The field is optional. A Parable’s root Problem holds no Changes: a change asked there goes into a new Problem under the root. A child Problem’s set starts from the newest Release, not from its parent’s Pending Changes, and it publishes on its own. When a Release changes a Piece that an open set also changed, that set collides. It cannot be proposed, and its message names the Release and the Pieces. Pocket it, then start a new set from that Release. A set of Changes moves through clear states. Pending is editable. Proposed is submitted for review and frozen, so later edits cannot silently alter what reviewers see. Published has become the current Version. Pocketed is put away without being deleted. Versions read like v1.2, and a Parable with no published Version reads v0. A Version describes the Parable’s structure and behavior; a Report reading is data. Choosing one never changes the other. Deployments lists the Workspaces that receive the Parable’s published Versions. Choosing All Workspaces or Selected Workspaces prepares the audience for future publishes; the choice alone deploys nothing. Sending a Version to other Workspaces is a Parable staff action: Publish & Deploy publishes and deploys in one approved step, and Deploy sends an already published Version to the Workspaces in its list without creating a new one. The list replaces the audience. So a Deploy, or a Publish & Deploy, whose list leaves out a Workspace of the current audience is refused with PA-AU-117, and nothing changes, until confirmedDroppedWorkspaceIds names each Workspace it drops. Tell the person which Workspaces it drops and ask before you send that confirmation. A confirmed drop does what Revoke does to each Workspace it drops: it cancels the Deliveries on their way to the Workspace and removes the seats the Deploy gave it. To take a Parable away from Workspaces without a new Deploy, Revoke it: send the Workspaces that keep it and the current Rollout. Revoke is a Parable staff action too. Outside Ponder, an agent has no tool to Deploy, Publish & Deploy or Revoke: ask Parable staff. Pocket, a staff delete and Visible off do not remove a Workspace. A receiving Workspace can read a delivered Parable before it pulls it. The Deploy seats the Workspace at Pinging, and the copy shows to its members only while Visible is on. Visible starts off unless Parable staff turned it on for every Workspace. Pulling it brings the delivery into that Workspace’s own Changes for review, and later deliveries keep the Workspace’s own edits and removals. Besides a new seat, only the Primary switches Collaboration Mode. Switching to Publishing opens no Changes, publishes nothing, and sends no Ping. Only a person whose own Primary seat is the Parable’s only Primary switches back to Personal. Switching back keeps the content and every Version, pockets every open set of Changes, colleagues’ sets included, removes every other participant, and does not withdraw copies already published. Copies get none of the later edits, and the last Version sent to them can be older than the newest Version. Nobody is told. Before Ponder asks you to approve the switch, it lists each participant that the switch removes, each set of Changes that it pockets with the person who started it, and the last Version sent to copies in other Workspaces, or that no other Workspace has the Parable. After the switch, edits save at once and go into no Version, and the app’s Release control says so. When the Parable goes back to Published Versions, the next set of Changes that is submitted carries those edits into the next Version. Opening, editing, submitting, preparing, publishing, pocketing, and restoring Changes need Publishing participation or higher. A set of Changes always names the person who started it. A set in a Problem that a person started is shared: anyone in Publishing or Primary who can see that Problem may edit, prepare, propose, patch, pocket, restore, and delete it, as the person who started it may. A set in a Problem that Parable started for it, such as a Pull, a Versioned setting’s save, or a set saved outside Ponder, stays with the person who started it in every stage. The Primary may still prepare and patch a Pull. Peeking and Pinging only read it. For a change of your own beside a colleague’s set, start a Problem under theirs. Publishing Changes, deleting pocketed Changes, and switching mode are Ask by default, because they change what others see or cannot be undone. In Ponder, each asks a person for approval, and a Ponder reply is never the approval itself. Outside Ponder, Ask is only a hint to the agent’s host, and Parable asks nobody: say what the call changes and wait for the person’s go-ahead before you make it. Outside Ponder, a switch back to Personal is refused, and the person makes it in the app. No Power or participation mode widens what the server allows.
  1. Stay Personal for solo work. Seating someone switches to Publishing; ask Ponder to switch sooner when you want Changes and Versions before anyone joins.
  2. Keep one outcome per set of Changes, and one set per Problem. Ask Ponder to open Changes in the Problem for that outcome, then make the edits there. Asked in the root Problem, Ponder first starts a Problem under the root and names it for the change.
  3. Preview the affected Pages, Panes, Plots, and data. The Proofs that the Changes must pass come from the Proofs Platform Parable, not from their Problem.
  4. Ask Ponder to submit the Changes for review. An empty set is refused.
  5. Ask Ponder to check what publishing would do and get the Changes ready. When the Changes change a Pipeline, Ponder also calls Estimate what publishing these Changes would run again. It lists each Pipeline that the next Refresh runs again, with the reason. It also counts the paid AI calls of that Refresh and their cost. The first call starts the estimate, and a later call reads it as it finishes. Ponder reports the estimate and the Workspace’s Refresh cost threshold before it asks to publish. Publishing waits until every Page, Pane and Plot in the Changes is free of Warnings & Errors: the warnings and errors the editor lists under each Piece’s code. A warning blocks Publish as an error does. The refusal names each Piece with its counts and lists its first findings, errors first: at most 5 for each Piece and 20 in all, each with its rule, message, line and column. It also says how many findings it does not list. To read every finding of one Piece, use Read a Piece’s problems. Through the API, that is GET /api/parable/authoring/primaries/{rootRefId}/piece-diagnostics?pieceKey={Piece key}&proposalId={Changes id}. With the Changes’ id, it answers their author and a person who shares their Problem. Any other publisher fixes from the findings in the refusal. If a finding blocks publication, such as a Warning or Error or a Plot whose SQL fails its check, reopen the Changes, fix it, and submit again. Publishing also waits until the Parable has a description. Ask Ponder to write it (see the Pages Power). Through the API, the author of the open Changes saves it into them with Rename a Parable or change how it is labelled: POST /api/parable/authoring/primaries/{rootRefId}/actions/identity with proposalId, expectedRefVersion (the sourceRefVersion of the Changes) and description. In Publishing mode this edit needs proposalId. Without it, the edit is refused. Any other publisher asks the author. Publishing does not wait for a preview. A Parable that is not Personal gets a card picture by itself. At its first Propose, or at a Publish while it has no picture, Ponder Details makes an image set at Speedy: a scene and a story, with logos off. The scene goes on the card. A person’s favorite image in Ponder Details replaces it at once. A favorite does not wait for Publish. A Parable that another Workspace delivered to yours shows its source’s description and preview, so it needs none of its own.
  6. Ask Ponder to publish. Read the Parable, the resulting Version, and the audience in the approval before you allow it.
  7. Pocket work you are setting aside instead of deleting it. Taking it out of the Pocket returns it to Pending, and it must be submitted and reviewed again.
Good publishing ships one coherent outcome that was previewed, reviewed, and sent to the intended audience. Check the result by listing the Parable’s Versions and the history of its Changes, reading the published Version’s contents, and confirming the Deployments. Removing an inherited Piece is a real change and stays removed after publication. If Ponder finds nothing to submit, confirm the edits were saved in the intended Changes. If a control is disabled, read its explanation (stale, conflicted, already closed, or a missing responsibility) and repair that condition; do not recreate the Changes just to enable the control. Related Powers: Participants, Problems, Reports, Workspaces, Policies. Find each by its title; do not guess stored names.