SCRYDOSBox-XReferenceProjectpromoteAlso in MAME

DOSBox-XProject

promote

Review what the session learned and write the entries you approve into the repository's .scry/ folder.

promote(dry_run=false, entries=null, names=null, root="")

Try it

On Bricks, the game this repository builds, in a session started with the game's conf and cwd. The repository already has a .scry/ folder.
Ask

Show me what this session would save into the repository's .scry/, without writing anything.

Call
promote(dry_run=true)
Reply 4 of 7 fields
{
  "store": "./.scry",
  "unchanged": [],
  "total_bytes": 5283,
  "store_bytes": 10126
}

The review read the repository's own .scry/ folder and wrote nothing. total_bytes is the size of the candidates that would change it, and store_bytes the folder's size with them written.

The whole reply
JSON
{
  "summary": "promote: 2 candidates in ./.scry",
  "status": "ok",
  "store": "./.scry",
  "candidates": [
    {
      "entry": "perform/session",
      "kind": "perform",
      "name": "session",
      "file": ".scry/perform/session.json",
      "bytes": 5129,
      "change": "new"
    },
    {
      "entry": "start/bricks",
      "kind": "start",
      "name": "bricks",
      "file": ".scry/start/bricks.json",
      "bytes": 154,
      "change": "update",
      "diff": {
        "added": [],
        "removed": ["break_on_int3"],
        "changed": [
          {
            "path": "conf",
            "was": "${env:DOSBOX_X_LIVE_BRICKS_DIR}/bricks.conf",
            "now": "${root}/demos/bricks/bricks.conf"
          },
          {"path": "cwd", "was": "${env:DOSBOX_X_LIVE_BRICKS_DIR}", "now": "${root}/demos/bricks"}
        ]
      }
    }
  ],
  "unchanged": [],
  "total_bytes": 5283,
  "store_bytes": 10126
}

Arguments

dry_run boolean, default false
true reviews: it lists every candidate and writes nothing. It cannot be given together with entries.
entries array of string, optional
The entries to write, each <kind>/<name> with a kind of start, maps or perform. Only these are written.
names object, optional
A new name for an entry as it is written, as {"<kind>/<name>": "<new name>"}. Left out, each keeps its name.
root string, default ""
The repository whose .scry/ folder takes every entry of the call: absolute, or starting with ~. Left out, each entry goes to its own repository.

What comes back

candidates
A review's list. Each entry has its kind, name, file, bytes and change (new or update), an update its diff, and one from another repository says from.
unchanged
A review's entries that already equal their file in .scry/, so there is nothing to approve.
unwritable
Entries this call cannot write, each with its reason: most often a repository with no .scry/ folder, which a call with root creates.
written
An approval's entries as written, in the fields candidates uses.
draft
After an approval, the session's candidates not yet written to .scry/.
would_create
What an approval would create that is not there yet: .scry/, its about.json and its README.md. An approval names what it created in created.
All 10 reply fields
  • candidates (array)
  • unchanged (array of string)
  • unwritable (array)
  • written (array)
  • would_create (array of string)
  • created (array of string)
  • draft (array of string)
  • total_bytes (integer)
  • store (string)
  • store_bytes (integer)

What it refuses

Why it works this way

Nothing is written into a repository until a call names the entries to write. The .scry/ folder is tracked, so every entry is reviewed before it is written, and only an approved call creates the folder. The .scry/ folder says what it holds.

dry_run=true lists each candidate that would change the folder: its file, its size and whether it is new or an update, an update with what changes. It names the candidates that would change nothing, and what an approval would create beside the entries.

An entry belongs to one repository, fixed when it is saved: the one a call read it from, else the current start's. That is its profile's repository, else the one its program runs in: its cwd or its conf's directory, up to the nearest directory holding .scry/, else .git.

More on why

A candidate is saved only when complete: a start profile with the arguments it cannot start without, a screen map its reader parses, a script with a check. A reply that saves one also names each repository with no .scry/ folder and the root to give.

An entry a call loaded (start(profile=), screen_map_write(method="load"), perform(path=)) gives its name to what is learned next, so saving it again is an update. An update keeps the keys that belong to a run as the file has them.

Every path in an entry is written as a placeholder (the rule), so the tracked file reads the same on any machine. close names in draft what was left unwritten, and the candidates stay until the server ends.

store is the .scry/ folder the call reads or writes, store_bytes its size with the entries written, and total_bytes the size of the candidates listed. A diff holds added, removed and changed, each change with its path, was and now; changed_total counts them when the list is cut.

The contract your client receives
Text
What this session learned, written into the repository's store (`.scry/`) only when
approved. `start` keeps the recipe it ran, a map's `add` keeps the map, a
`perform_export` keeps the script; each is complete only with what its reader accepts
(the arguments a recipe cannot boot without, a map the map reader parses, a script
with a check), and a reply that keeps one says `N saved for promote` in `kept`, naming
each repository of the draft with no store and the `root` it takes. An entry belongs
to the repository it was learned in: the one whose store a call loaded it from, else
the current `start`'s, its profile's or where its program runs, where the server can
tell. The identity is
(repository, kind, name): an entry a call loaded (`start(profile=)`,
`screen_map_write` `load`, `perform(path=)`) names what is learned next, and a name
the store already holds is an update, which keeps the keys a run owns as the
store has them, and one that changes nothing is named in `unchanged`, not offered.
`dry_run=true` lists every other candidate with its
file, its size and whether it is new or an update, an update with its diff; `entries`
(`<kind>/<name>`, the kind one of `start`, `maps`, `perform`) writes only those,
`names` renames one as it is written, and only
that approved call creates `.scry/`, and with the server's name also `about.json` and
the rendered `README.md`; `dry_run`
names those in `would_create`, the approval in `created`. Without `root` each entry
goes only to its own repository's store, one store a call, and one whose repository
has none is unwritable; `root` names the repository whose store a call writes every
entry to, a candidate from another saying `from`. Every path is
written as a `project_store` placeholder, since a tracked file carries no path of this
machine; an approval of an entry a review calls unwritable is refused. Reply: `store`,
`candidates` and `unchanged` (a review), `unwritable`, each entry with its reason
(a review holding an entry it cannot write), `written` and `draft` (an approval),
`would_create` and `created` (the store, `about.json`, `README.md` not yet there),
`total_bytes`,
`store_bytes`; `close` names what was left unkept, which stays in the draft until the
server ends. Refused: nothing kept (`needs_call`); an entry the draft does not hold;
without `root`, a call none of whose entries has a store, or entries of two stores; a
name two repositories hold, unless `root` is one of them; two entries written to one
file; a kind or a store past its cap.

Reference: REFERENCE.md, The `.scry/` folder.
Tools