integration.trains

{
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty",
  "type": "object"
}

{
  "$defs": {
    "BeneathLink": {
      "description": "A pull request below a train that is not open any more.",
      "properties": {
        "number": {
          "description": "Its number.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "state": {
          "$ref": "#/$defs/DependencyState",
          "description": "What the forge says became of it."
        },
        "url": {
          "description": "The pull request on the forge, when the repository is known.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "number",
        "state"
      ],
      "type": "object"
    },
    "CheckRunState": {
      "description": "Where one check run stands.",
      "oneOf": [
        {
          "const": "passed",
          "description": "Completed and passed.",
          "type": "string"
        },
        {
          "const": "failed",
          "description": "Completed and failed (failure, timed out, cancelled, action required).",
          "type": "string"
        },
        {
          "const": "pending",
          "description": "Queued or running; also what a report that says nothing is taken to be, so a\ndefault is never a pass.",
          "type": "string"
        },
        {
          "const": "skipped",
          "description": "Completed as skipped or neutral.",
          "type": "string"
        }
      ]
    },
    "DependencyState": {
      "description": "What became of a pull request another one depends on.",
      "oneOf": [
        {
          "const": "open",
          "description": "Still open.",
          "type": "string"
        },
        {
          "const": "merged",
          "description": "Merged: the only state that satisfies it.",
          "type": "string"
        },
        {
          "const": "closed_unmerged",
          "description": "Closed without a merge: its work never landed, so a person decides.",
          "type": "string"
        },
        {
          "const": "unread",
          "description": "Not open, and the forge could not say what became of it — refused, or not a pull\nrequest at all: unknown, never satisfied.",
          "type": "string"
        }
      ]
    },
    "IntegrationLane": {
      "description": "The queues the Cockpit and the status table group pull requests into.",
      "oneOf": [
        {
          "const": "ready",
          "description": "The executor may merge it now.",
          "type": "string"
        },
        {
          "const": "waiting",
          "description": "Something will happen without a person: a refresh, a check, a dependency.",
          "type": "string"
        },
        {
          "const": "repair",
          "description": "A person must change the branch.",
          "type": "string"
        },
        {
          "const": "cleanup",
          "description": "Its work is on master already, or a successor that landed replaced it.",
          "type": "string"
        },
        {
          "const": "held",
          "description": "Not asking to be merged, held by a label or a setting, unsafe for the executor, or\nundecidable.",
          "type": "string"
        }
      ]
    },
    "LinkCheck": {
      "description": "One check run on a link's head.",
      "properties": {
        "name": {
          "description": "The check's name.",
          "type": "string"
        },
        "state": {
          "$ref": "#/$defs/CheckRunState",
          "description": "Where it stands."
        }
      },
      "required": [
        "name",
        "state"
      ],
      "type": "object"
    },
    "PrepState": {
      "description": "Whether a prepared head has reached the forge.",
      "oneOf": [
        {
          "const": "pushed",
          "description": "The prepared head is the pull request's head: it was pushed.",
          "type": "string"
        },
        {
          "const": "pending",
          "description": "The prepared head is another commit: it waits for its turn to be pushed.",
          "type": "string"
        }
      ]
    },
    "PreparedHead": {
      "description": "The head the executor prepared for a link under `refs/prep/<n>`.",
      "properties": {
        "reference": {
          "description": "The ref.",
          "type": "string"
        },
        "sha": {
          "description": "The commit it names.",
          "type": "string"
        },
        "state": {
          "$ref": "#/$defs/PrepState",
          "description": "Whether that commit is the head the forge serves."
        }
      },
      "required": [
        "reference",
        "sha",
        "state"
      ],
      "type": "object"
    },
    "PullRequestDisposition": {
      "description": "The one classification of an open pull request. Every value carries a machine-readable\nreason in `PullRequestAssessment::reasons`; there is no `mergeable: bool`.",
      "oneOf": [
        {
          "const": "ready",
          "description": "Contains the current master, every required check passed on its head, nothing\nblocks it: the executor may merge it.",
          "type": "string"
        },
        {
          "const": "needs_refresh",
          "description": "Merges cleanly but does not contain master: the executor may bring master in (a\nmerge commit on the branch, never a rewrite), after which CI must run again.",
          "type": "string"
        },
        {
          "const": "waiting_for_checks",
          "description": "Contains master; a required check has not finished on this head.",
          "type": "string"
        },
        {
          "const": "waiting_for_review",
          "description": "A required review is missing or changes were requested.",
          "type": "string"
        },
        {
          "const": "waiting_for_dependency",
          "description": "A declared dependency has not landed.",
          "type": "string"
        },
        {
          "const": "draft",
          "description": "A draft.",
          "type": "string"
        },
        {
          "const": "needs_repair",
          "description": "A required check failed on this head.",
          "type": "string"
        },
        {
          "const": "conflicting",
          "description": "Conflicts on authored paths: a person resolves them.",
          "type": "string"
        },
        {
          "const": "blocked",
          "description": "A label whose policy is to hold holds it, or the repository allows no merge commit,\nwhich is the only way the executor merges.",
          "type": "string"
        },
        {
          "const": "unsafe",
          "description": "The forge has auto-merge armed on it: the forge would merge it on its own, outside the\nexecutor and against whatever master is then. Held until a person disarms it.",
          "type": "string"
        },
        {
          "const": "redundant",
          "description": "Its head already landed, its merge changes nothing, or every one of its commits is on\nmaster as an equal patch: strong evidence from git, eligible for closure under policy.\n(Before 0.13 this was the word `superseded`.)",
          "type": "string"
        },
        {
          "const": "superseded",
          "description": "A successor was declared for it by someone the repository lets declare one — an owner,\nmember or collaborator, in a pull request of this repository — and that successor\nlanded: git finds its head or its merge commit in master. The successor is\n`PullRequestAssessment::superseded_by`. Eligible for closure under policy.",
          "type": "string"
        },
        {
          "const": "possibly_redundant",
          "description": "Weak evidence: only derived artifacts would change, or its declared successor was merged\nsomewhere master does not contain. Surfaced for a person; never closed automatically.",
          "type": "string"
        },
        {
          "const": "other_base",
          "description": "Targets a branch other than the integration base.",
          "type": "string"
        },
        {
          "const": "unknown",
          "description": "Something needed to decide could not be observed.",
          "type": "string"
        },
        {
          "const": "obsolete",
          "description": "A person marked it obsolete with a label the label policy declares (owner decision\nD3): the only evidence that reaches this word. Listed for a person by cleanup and\nnever closed automatically; age, shared paths or a similar title never make one.",
          "type": "string"
        }
      ]
    },
    "RelationToMaster": {
      "description": "What the pull request's head is to the current master, decided locally by git with\nthis repository's own merge drivers — never by the forge's `mergeable`, which cannot\nrun the derived-file driver and calls nearly every pull request here conflicting.",
      "oneOf": [
        {
          "description": "The head is an ancestor of master: every commit already landed.",
          "properties": {
            "kind": {
              "const": "contained",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "Merging the head into master changes nothing: its patch is already fully there.",
          "properties": {
            "kind": {
              "const": "superseded",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "The merge would conflict or change only derived output, but every commit the head has\nand master lacks is on master already as an equal patch (`git cherry` marks each `-`):\nthe change landed, and master moved on past it. Never a partial match, and never a\nhead that carries a merge commit of its own, whose resolution has no patch to compare.",
          "properties": {
            "commits": {
              "description": "How many commits, every one of them already on master.",
              "format": "uint64",
              "minimum": 0,
              "type": "integer"
            },
            "kind": {
              "const": "patch_ids_upstream",
              "type": "string"
            }
          },
          "required": [
            "kind",
            "commits"
          ],
          "type": "object"
        },
        {
          "description": "Merging changes only derived artifacts: the authored change is already on master,\nand what differs is output the generators rewrite.",
          "properties": {
            "kind": {
              "const": "derived_only",
              "type": "string"
            },
            "paths": {
              "description": "The derived paths that would change.",
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          },
          "required": [
            "kind",
            "paths"
          ],
          "type": "object"
        },
        {
          "description": "The head already contains master and merges cleanly.",
          "properties": {
            "authored": {
              "description": "Authored (non-derived) paths the merge changes.",
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "kind": {
              "const": "up_to_date",
              "type": "string"
            },
            "owes_version": {
              "description": "The version a landing of this head allocates, when master allocates at landing\n(ADR 0134) and the head does not carry it: the head owes a refresh even though it\ncontains master. Absent when the policy does not allocate, or the head carries it.",
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "kind",
            "authored"
          ],
          "type": "object"
        },
        {
          "description": "The head does not contain master, yet master holds nothing the head lacks: merging it\nwrites the head's own tree, and every commit master has beyond it is a merge commit.\nThat is a head stacked on a pull request that has since landed. A verdict on the head\nis then a verdict on what master becomes, tree and listed history alike, exactly as\nwhen the head contains master; and no path is merged at all, so the forge needs no\ndriver for it.",
          "properties": {
            "authored": {
              "description": "Authored (non-derived) paths the merge changes.",
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "behind": {
              "description": "Commits on master the head does not have.",
              "format": "uint64",
              "minimum": 0,
              "type": "integer"
            },
            "kind": {
              "const": "carries_master",
              "type": "string"
            }
          },
          "required": [
            "kind",
            "behind",
            "authored"
          ],
          "type": "object"
        },
        {
          "description": "The head does not contain master, but the merge is clean with the derived driver.",
          "properties": {
            "authored": {
              "description": "Authored paths the merge changes.",
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "behind": {
              "description": "Commits on master the head does not have.",
              "format": "uint64",
              "minimum": 0,
              "type": "integer"
            },
            "kind": {
              "const": "behind",
              "type": "string"
            }
          },
          "required": [
            "kind",
            "behind",
            "authored"
          ],
          "type": "object"
        },
        {
          "description": "Merging conflicts on authored paths: a person must resolve it.",
          "properties": {
            "kind": {
              "const": "conflicting",
              "type": "string"
            },
            "paths": {
              "description": "The conflicting authored paths.",
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          },
          "required": [
            "kind",
            "paths"
          ],
          "type": "object"
        },
        {
          "description": "Git could not answer (the head is not fetched, or git failed); the reason.",
          "properties": {
            "kind": {
              "const": "unknown",
              "type": "string"
            },
            "reason": {
              "description": "Why.",
              "type": "string"
            }
          },
          "required": [
            "kind",
            "reason"
          ],
          "type": "object"
        }
      ]
    },
    "RequiredCheckState": {
      "description": "The state of the repository's *required* checks on one head, which is the only check\nstate a merge decision reads. A visible green check that is not required proves nothing,\nand a required check that is absent is not a pass.",
      "oneOf": [
        {
          "const": "passed",
          "description": "Every required check passed on this head.",
          "type": "string"
        },
        {
          "const": "skipped",
          "description": "Every required check passed, at least one of them by a skip the policy permits for\nthat context. A skip the policy does not permit is not a pass: it is `missing`.",
          "type": "string"
        },
        {
          "const": "pending",
          "description": "A required check is queued or running.",
          "type": "string"
        },
        {
          "const": "failed",
          "description": "A required check failed.",
          "type": "string"
        },
        {
          "const": "missing",
          "description": "A required check has not reported on this head at all.",
          "type": "string"
        },
        {
          "const": "unknown",
          "description": "The repository's required checks could not be read.",
          "type": "string"
        }
      ]
    },
    "Train": {
      "description": "One train: open pull requests joined by confirmed dependencies, in the order they land.",
      "properties": {
        "beneath": {
          "description": "The pull requests below the train that are no longer open — landed, closed without a\nmerge, or unread — which a link still declares.",
          "items": {
            "$ref": "#/$defs/BeneathLink"
          },
          "type": "array"
        },
        "by_disposition": {
          "additionalProperties": {
            "format": "uint",
            "minimum": 0,
            "type": "integer"
          },
          "description": "Links by disposition word.",
          "type": "object"
        },
        "edges": {
          "description": "Every confirmed dependency of a link, upper link first.",
          "items": {
            "$ref": "#/$defs/TrainEdge"
          },
          "type": "array"
        },
        "id": {
          "description": "`train-<n>`, after the first root in turn order: stable while that link is open.",
          "type": "string"
        },
        "links": {
          "description": "Every open link, in turn order — `TrainLink::position` 1 first.",
          "items": {
            "$ref": "#/$defs/TrainLink"
          },
          "type": "array"
        },
        "next": {
          "description": "The first link, in turn order, whose every dependency has landed: the train's next\nmerge as far as order is concerned (its disposition says whether it can merge now).",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "roots": {
          "description": "The links that land first: no open link of the train is below them.",
          "items": {
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          },
          "type": "array"
        },
        "tops": {
          "description": "The links at the top: no link of the train is stacked on them.",
          "items": {
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          },
          "type": "array"
        }
      },
      "required": [
        "id",
        "roots",
        "tops",
        "links",
        "edges",
        "beneath",
        "by_disposition"
      ],
      "type": "object"
    },
    "TrainEdge": {
      "description": "A confirmed dependency between two pull requests of a train.",
      "properties": {
        "from": {
          "description": "The upper link: the one that depends.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "kind": {
          "$ref": "#/$defs/TrainEdgeKind",
          "description": "How the dependency is declared."
        },
        "satisfied": {
          "description": "Whether it is satisfied: the pull request below landed.",
          "type": "boolean"
        },
        "to": {
          "description": "The pull request it stands on.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "from",
        "to",
        "kind",
        "satisfied"
      ],
      "type": "object"
    },
    "TrainEdgeKind": {
      "description": "How a dependency between two links is declared.",
      "oneOf": [
        {
          "const": "stacked_on",
          "description": "Its base branch is the other's head, or its body says `Stacked on #N`.",
          "type": "string"
        },
        {
          "const": "depends_on",
          "description": "Its body says `Depends on #N`, `Requires #N` or `Land after #N`.",
          "type": "string"
        }
      ]
    },
    "TrainLink": {
      "description": "One open pull request as a link of a train.",
      "properties": {
        "at_turn": {
          "description": "Every dependency it declares has landed: it is the link the order allows next.",
          "type": "boolean"
        },
        "author": {
          "description": "Its author's login.",
          "type": "string"
        },
        "base_ref": {
          "description": "The branch it targets: the integration base, or the head of the link below.",
          "type": "string"
        },
        "behind": {
          "description": "How many master commits its head lacks, when the relation counts them.",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "carries": {
          "description": "The links stacked on it.",
          "items": {
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          },
          "type": "array"
        },
        "carries_master": {
          "description": "Whether its head carries master by a merge of its own (ADR 0129) — read from the\nrelation's word, so an executable that does not know that relation says `false`.",
          "type": "boolean"
        },
        "checks": {
          "description": "Every check the forge reported on its head, required or not.",
          "items": {
            "$ref": "#/$defs/LinkCheck"
          },
          "type": "array"
        },
        "checks_url": {
          "description": "Its checks on the forge, when the repository is known.",
          "type": [
            "string",
            "null"
          ]
        },
        "depth": {
          "description": "How many links are below it on its longest path to master; a root is 0.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "disposition": {
          "$ref": "#/$defs/PullRequestDisposition",
          "description": "The executor's classification."
        },
        "head_ref": {
          "description": "Its head branch.",
          "type": "string"
        },
        "head_sha": {
          "description": "The head commit it was assessed at, as the forge served it.",
          "type": "string"
        },
        "in_cycle": {
          "description": "Caught in a cycle of confirmed dependencies: no link of the cycle can land first.",
          "type": "boolean"
        },
        "lane": {
          "$ref": "#/$defs/IntegrationLane",
          "description": "The lane that disposition belongs to."
        },
        "next_action": {
          "description": "What happens next, in words, when anything does.",
          "type": [
            "string",
            "null"
          ]
        },
        "number": {
          "description": "The pull request number.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "on": {
          "description": "The pull requests it stands on, open links and those beneath alike.",
          "items": {
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          },
          "type": "array"
        },
        "position": {
          "description": "Its turn in the train, 1-based: every link below it comes earlier.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "prep": {
          "anyOf": [
            {
              "$ref": "#/$defs/PreparedHead"
            },
            {
              "type": "null"
            }
          ],
          "description": "The head the executor prepared for it, when `refs/prep/<n>` exists."
        },
        "rank": {
          "description": "Its rank in the queue, 1-based.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "reasons": {
          "description": "The machine-readable reasons, as every surface spells them (`stacked_on:#<number>`).",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "relation": {
          "$ref": "#/$defs/RelationToMaster",
          "description": "What its head is to master, decided by git."
        },
        "relation_kind": {
          "description": "That relation's word (`behind`, `up_to_date`, `carries_master`, ...).",
          "type": "string"
        },
        "required_checks": {
          "$ref": "#/$defs/RequiredCheckState",
          "description": "The required checks on its head."
        },
        "title": {
          "description": "Its title.",
          "type": "string"
        },
        "url": {
          "description": "The pull request on the forge, when the repository is known.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "number",
        "title",
        "author",
        "head_ref",
        "base_ref",
        "head_sha",
        "disposition",
        "lane",
        "reasons",
        "required_checks",
        "checks",
        "relation",
        "relation_kind",
        "carries_master",
        "position",
        "depth",
        "at_turn",
        "on",
        "carries",
        "rank",
        "in_cycle"
      ],
      "type": "object"
    },
    "TrainTallies": {
      "description": "Counts over every train.",
      "properties": {
        "by_disposition": {
          "additionalProperties": {
            "format": "uint",
            "minimum": 0,
            "type": "integer"
          },
          "description": "Links by disposition word.",
          "type": "object"
        },
        "links": {
          "description": "Open links across every train.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "pending_prep": {
          "description": "Links whose prepared head is not the head the forge serves.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "trains": {
          "description": "Trains.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "trains",
        "links",
        "pending_prep",
        "by_disposition"
      ],
      "type": "object"
    },
    "UnattachedPrep": {
      "description": "A prepared head whose pull request is no link of any train.",
      "properties": {
        "number": {
          "description": "The pull request the ref is named for.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "open": {
          "description": "Whether that pull request is open.",
          "type": "boolean"
        },
        "sha": {
          "description": "The commit it names.",
          "type": "string"
        }
      },
      "required": [
        "number",
        "sha",
        "open"
      ],
      "type": "object"
    }
  },
  "description": "Every train of the observed queue, and why there is none when there is none.",
  "properties": {
    "base": {
      "description": "The integration base.",
      "type": [
        "string",
        "null"
      ]
    },
    "diagnostics": {
      "description": "What makes this answer less than a full one: the queue's own diagnostics (a stale\nobservation first), and a dependency cycle when one is found.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "master_sha": {
      "description": "The master commit every link's relation was decided against.",
      "type": [
        "string",
        "null"
      ]
    },
    "observed": {
      "description": "Whether a forge observation is recorded in this checkout.",
      "type": "boolean"
    },
    "observed_at": {
      "description": "When the forge was observed.",
      "type": [
        "string",
        "null"
      ]
    },
    "reason": {
      "description": "Why there are no trains to show, when nothing is observed.",
      "type": [
        "string",
        "null"
      ]
    },
    "repository": {
      "description": "`owner/name`, when observed.",
      "type": [
        "string",
        "null"
      ]
    },
    "tallies": {
      "$ref": "#/$defs/TrainTallies",
      "description": "Counts over every train."
    },
    "trains": {
      "description": "Every train, the one whose next link ranks highest in the queue first.",
      "items": {
        "$ref": "#/$defs/Train"
      },
      "type": "array"
    },
    "unattached_prep": {
      "description": "Prepared heads under `refs/prep/` whose pull request is no link of any train: open\nand stacked on nothing, or not open at all (landed, closed).",
      "items": {
        "$ref": "#/$defs/UnattachedPrep"
      },
      "type": "array"
    }
  },
  "required": [
    "observed",
    "trains",
    "unattached_prep",
    "tallies",
    "diagnostics"
  ],
  "title": "TrainsView",
  "type": "object"
}