Preamble, purpose, actors and vocabulary
A statement of what sluice must always do and never do, written to admit any model that satisfies it.
The statement is in three parts. Part A is what must hold of sluice on its own: how work is submitted to a branch, ordered, tested in the combination it will land in, attributed when it fails, and landed. Part B is its contracts: the operations it needs across its five seams, a place, a check, a branch, a driver and the records, and the guarantee each must give. Part C is the profiles: the ways each contract is satisfied.
Parts A and B name no mechanism: no command, file, format, field, service or tool. One thing of the world they name freely, because section 9 fixes it: git. Every other real tool is named only in section 9 and in Part C. A reader who has never seen a merge queue should be able to design from Parts A and B and git alone.
1. Purpose
sluice admits finished work onto a branch only after the branch, extended by that work and by everything ahead of it, has passed the branch’s gate. It orders what is submitted, forms each candidate revision exactly as it would land, tests candidates ahead of need, names the one submission at fault when a candidate fails, and moves the branch only to a revision that passed. It never runs a check of its own invention, never starts a service, never chooses a port, and never decides what a gate requires. A session that built the work submits it and does nothing more.
2. Actors
| actor | may decide | may not |
|---|---|---|
| a session (an agent or a person building in a place) | when its work is ready, and to submit it; how to resolve a conflict or a failure in its own place | merge, land, or move a branch; change another submission’s order; withdraw another’s submission |
| a planner (a plan, or a person) | what a submission lands after, and its priority; to ask sluice to make or remove a branch it lands on (104, 105) | override a gate; move a branch |
| a policy’s author (a repository’s owners, a platform) | which checks gate each branch, which executors each branch trusts, how a flaky result reads, how deep a chain is tested, how long a candidate’s checks may run, what a run may use and reach | make a branch land untested; widen trust a layer above set |
| the operator | everything a policy does not settle | make a landing that skipped the gate count as one |
| sluice | the order among submissions within what the planner and the policy fixed; which candidates to test and how many at once; when a branch moves | run a check of its own, start a service, choose a port, resolve a conflict, decide trust, release a session’s place, move a branch to a revision that has not passed its gate, or remove a branch whose work has not landed into another (105) |
| an executor (a session’s shell, a confined run) | nothing; it runs checks and reports what it observed | report an outcome it did not observe |
3. Vocabulary
Terms are defined by meaning. A model may add terms; it may not redefine these.
- branch: a git branch that lands work: a repository’s shared branch, or a bolt’s branch off it.
- place: a working copy prepared for one session off one branch.
- head: the revision a place holds when its session submits.
- submission: one head offered to one branch, with what it must land after, its priority and who submitted it.
- entry: a submission as sluice holds it, with its state.
- after: the entries a submission names as having to land before it.
- work: an entry’s commits, from where its head left the branch to the head.
- candidate: a revision equal to the branch’s current revision extended, in order, by an entry and every entry ahead of it: the revision that entry would land as.
- chain: the candidates of one branch, each extending the one before.
- window: how many candidates of a branch’s chain are under test at once.
- conflict: a candidate that cannot be formed because its entry and the candidate before it change the same content incompatibly.
- check: a task run to judge a revision, ending in a pass or a fail.
- gate: for a branch, the checks it requires, the executors it trusts, and how a flaky key reads.
- key: the identity of one check over the inputs it reads.
- verdict: a gate’s reading of a candidate: for each required check exactly one of passed, failed, missing or flaky.
- culprit: the one entry a failed candidate is attributed to.
- landing: the branch moving to a candidate that passed.
- executor: what ran a check, with its identity and its host; confined when it ran in a place holding exactly the candidate and what the repository declares, which nothing of any session could reach, and when nothing but it could have written its records; open otherwise.
- host: a machine on which sessions, sluice or executors run.
- profile: one way a contract of Part B is satisfied, as Part C describes.