Environments and promotion

An environment is a complete, separate copy of a project's content, and promotion moves a set of changes you choose from one copy into another in a single transaction.

Why changes move between copies, not branches

You want to try a change where readers cannot see it, and then make exactly that change live. For that, Quillet gives each project one or more environments, such as prod and staging, and keeps the content of each one isolated from every other. A delivery key belongs to one environment, so a site reads exactly one copy and never a mixture.

There are no branches and no merges. To start a second copy, you clone the first. To move work back, you compare the two and promote the rows you choose. The compare shows exactly what each promoted row will overwrite, so nothing happens that you did not see first.

Conflicts are left to a person on purpose. A promotion replaces the target's version of a document with the source's; it never merges two edits of one document. If someone changed a row in the target after your compare, Quillet refuses the promotion and writes nothing. You compare again, see both edits and decide.

What clone, compare and promote each do

Clone once, edit in the copy, compare, and promote only the rows you select; the target never changes until you do.

Clone

An owner can create an environment as a copy of another. The copy takes every published document and, if you ask for it, each document's current draft as a second version. History is not copied, so every document starts again at version 1. The new environment does not exist until the copy is complete, which means nothing ever serves half of it.

Compare

A compare reads both environments over a scope and changes nothing. The scope is a list of folders, each with the locales it covers. Every document in it comes back with one of four statuses:

Status	Meaning
`added`	in the source, not in the target
`changed`	in both, with different bodies
`unchanged`	in both, with the same body
`removed`	in the target, gone from the source

A row can also say that its metadata differs, or that it references documents outside the scope. A document outside the scope is never reported, so it is never deleted by accident.

Promote

A promotion writes the selected rows into the target as new versions, all in one transaction. Without Publish after promoting, they arrive as drafts; with it, they go live at one instant. Each body is checked against the target's own components. A document whose component the target lacks is refused, unless you promote the component in the same step. Each row comes back as created, updated, unchanged, deleted or not found, and the target's History says "Promoted from staging".

Files are never copied. A file belongs to the project rather than to an environment, so every environment already has it.

How to

Dashboard

Choose the target in the header's Environment select, then open the Promote tab.
Choose the source in From. Choosing the environment To already holds swaps the two, and the swap button between the selects does the same. Under Folders, leave the row empty for everything, or type a folder such as landing/.
Press Compare. Each row shows its status, its versions and Show diff.
Select rows, tick Publish after promoting if you want them live, and confirm. The dialog names both environments, counts what will be added and changed, and names the deletions.

API

Compare a source with the target named in the path:

curl -s -u '<keyId>:<secret>' -X POST \
  'http://localhost:3000/api/v1/projects/<project>/envs/<target>/compare' \
  -H 'Content-Type: application/json' \
  -d '{"from":"<source>","scope":[{"prefix":""}]}'

In the answer, summary counts each status. When you promote, send each row's targetHash back as its baseHash.

Limits

There is no quillet promote command. It is designed but not built.
There is no scheduling, no approval step and no named release.
There is no three-way merge. A conflicting edit comes back as a 409 base_mismatch for a person to resolve.
A promotion that publishes cleans each body under the target's published component, so the next compare of the same pair can read changed.
A clone or a compare covers at most 20 000 documents per environment. One promotion request carries at most 500 rows, and the dashboard sends a larger selection in chunks of 500, each its own transaction.
A key bound to one environment cannot compare or promote, because both actions read a second environment.

Environments: creating, cloning, deleting and keys per environment.
Promotion: every refusal and the audit trail.
Files and media: why files are shared across environments.
Versions and publishing: what a promoted version is.
Access: who may clone, compare and promote.