Make a stage

A stage is one self-contained change on top of a published Eclipse release: a folder with the files it ships, its rowlists, and a stage.json that the release pipeline reads. eb stage make writes stage.json for you from a stage.toml you fill in.

Checked against the code. Not run for this page: no stage was made while writing it.

EB means py -3.12 -I -B S:/eclipse-build/eb.py.

Before you start

• The base release tree must exist: S:/souls-script-kt/output/eclipse-release-<base>/depth6-online-mods. stage make stops with stage: base release tree ... not found without it.
• Pick a stage folder. Stages for release 0.0.NN live in S:/eclipse-00NN-stage/<name>.
• Pick an id, for example fix-0106/my-fix. Other stages refer to it.

Steps

1. Create the stage.

   EB stage init S:/eclipse-00NN-stage/<name> --id fix-00NN/<name> --base <base release, e.g. 0.0.105> --title "<one line>"
   

   --id and --base are required. --title is optional. It writes stage.toml and, if there is none, a README.md stub with the headings What changed, How it was built, Checks, Not proven. If stage.toml already exists it stops with ... exists; edit it.

2. Build your files twice, into two folders inside the stage: work/run-A and work/run-B. Run each build as an eb job (run-heavy-jobs.md). Each run folder holds the files at their release paths, for example work/run-A/mod/chr/c9240.anibnd.dcx.

3. Fill in stage.toml (fields below).

4. Write stage.json.

   EB stage make S:/eclipse-00NN-stage/<name>
   

stage.toml

This is the template stage init writes:

id = "fix-00NN/name"
title = "..."
kind = "fix"
risk = "low"
base_release = "0.0.105"
changelog = [""]
test = [""]
not_proven = []
approved = ""

[build]
command = ""          # how this stage's files are built (recorded in stage.json provenance)
runs = []             # e.g. ["work/run-A", "work/run-B"]: every shipped file must be identical in all of them

# [[file]]
# path = "mod/chr/cXXXX.anibnd.dcx"
# why = ""

# [[rowlist]]
# path = "rowlist-x.tsv"
# tool = "polish"
# order = 300
# expect = { set = 0, added = 0 }

[[file]]: a whole file that goes into the mod tree

[[rowlist]]: regulation changes

What stage make does

1. Stops if id, title, kind, risk or base_release is empty.
2. With two or more runs: copies every [[file]] from each run into .eb-stage-check/ in the stage folder, makes the .dcx copies canonical (the same as eb dcx normalize), and compares them. If any differ it stops with stage: these files differ between the build runs (not reproducible, not shipped): and the list. The check folder is removed afterwards.
3. Copies each file into the stage folder at its release path and makes .dcx files canonical.
4. Hashes each file and the file it replaces in the base release tree (base_sha256; null for a new file). A file identical to the one it replaces stops the run: ... is identical to ...; leave it out.
5. Hashes each rowlist.
6. Writes stage.json and prints wrote .../stage.json: N files, M rowlists, 2 build runs identical. With fewer than two runs it prints no build-twice check (give [build] runs) instead.

Chained files (base_stage)

Use this when your file was built on another stage's version of the same path, for example a sound bank that already holds another stage's sounds.

[[file]]
path = "mod/sd/cs_c4340.bnk"
base_stage = "fix-0088/ds3-arts-088"

• Make the base stage first. stage make finds its stage.json by id in the folders beside your stage folder. If it lives elsewhere, set base_stage_json = "<path to its stage.json or its folder>".
• base_sha256 is optional. Left out, it is read from the base stage's stage.json. If you give both, they must agree.
• stage.json then records base_stage and base_sha256 for the file. No merges entry is needed.
• The release check orders the two stages by it. If the base stage later ships a different file, or is missing from the release while the base tree does not hold that file, the check fails with STALE CHAIN (check-and-build-a-release.md). Rebuild on the new file and run stage make again.

What stage.json contains

Schema eclipse-stage/1, described in pipeline/stage.schema.json. stage make writes:

• schema, id, title, kind, risk, base_release, stage_dir (the stage folder), readme;
• files: per file path, source, sha256, base_sha256, and base_stage / why when given;
• rowlists: per list path, sha256, tool, order, expect, and overrides / why when given;
• merges, touches, changelog, test, not_proven, approved;
• provenance: made_by (eb stage make), eclipse_build (the eclipse-build commit, with (dirty) when the repo has uncommitted changes), stage_toml_sha256, build_command, build_runs, runs_identical, dcx_canonical, made.

The schema allows more keys that stage make does not write (binaries, sha_lists, seed_deltas, source_patches, when variants). A stage that needs them is not covered by this page.

The provenance gate

eb release check and eb release build look for the provenance block in every stage.

• For a release from 0.0.89 on, a stage without it is refused with a line that starts GATE FAIL <id>: no provenance.
• The same gate fails a stage whose merge steps pin tools that live only in souls-script-kt/.tmp or a Claude scratchpad.
• This also covers a stage carried over from an older release. Give it a stage.toml and run stage make on it.
• EB_GATE=warn turns the failure into a warning. It is for an emergency only; say so in the release notes.

How to tell it worked

stage.json exists in the stage folder and has a provenance block with "runs_identical": true. Then run the release check on it: check-and-build-a-release.md.

What goes wrong