diff --git a/.github/scripts/forward-merge.sh b/.github/scripts/forward-merge.sh new file mode 100755 index 0000000000..af7dc83c11 --- /dev/null +++ b/.github/scripts/forward-merge.sh @@ -0,0 +1,204 @@ +#!/usr/bin/env bash +# The forward merge of a release line (SPEC.md §9.4): the pushed head of +# `release/vX.Y` merged, by merge commit, into the head of `release/vX.(Y+1)` +# on the branch `forward/vXY-to-vX(Y+1)-`, pushed, with its pull request. +# +# A conflict in a generated projection or a lock takes the next line's side: +# `regenerate.yml` writes those files again from the merged tree. While the +# pushed line has no `spec/` (its SPEC.md and register are hand-written), what +# it changed in SPEC.md and `model/ids.toml` is carried into the next line's +# modules by `cargo xtask spec port --merged … --register …`, since the +# projections are written from the modules and would drop it. Any other +# conflict, and a port that refuses, is committed as the next line's side and +# the pull request is opened as a draft naming the paths, for an agent to +# finish. A newer forward branch of the same lines closes the older ones. +# +# Inputs, from the environment: REPO, LINE or GITHUB_REF_NAME (the line), the +# checkout (the pushed commit, full history, the workflow token), GITHUB_OUTPUT, +# GITHUB_STEP_SUMMARY, GITHUB_SERVER_URL. Outputs: branch, commit, clean. +set -euo pipefail + +repo=${REPO:?REPO names owner/name} +summary=${GITHUB_STEP_SUMMARY:-/dev/null} +output=${GITHUB_OUTPUT:-/dev/null} +say() { printf '%s\n' "$1" | tee -a "$summary"; } + +line=${LINE:-${GITHUB_REF_NAME:?LINE or GITHUB_REF_NAME names the pushed line}} +if ! [[ "$line" =~ ^release/v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then + say "\`$line\` is not a release line: nothing to carry forward." + exit 0 +fi +major=${BASH_REMATCH[1]} +minor=${BASH_REMATCH[2]} +next="release/v$major.$((minor + 1))" +if ! git ls-remote --exit-code --heads origin "$next" >/dev/null; then + say "There is no \`$next\`: nothing to carry forward." + exit 0 +fi +git fetch --quiet origin "refs/heads/$next:refs/remotes/origin/$next" +source=$(git rev-parse HEAD) +if git merge-base --is-ancestor "$source" "origin/$next"; then + say "\`$next\` already contains \`$source\`." + exit 0 +fi +prefix="forward/v$major$minor-to-v$major$((minor + 1))-" +branch="$prefix${source:0:8}" +if git ls-remote --exit-code --heads origin "$branch" >/dev/null; then + say "\`$branch\` already exists: this head was carried forward before." + exit 0 +fi + +base=$(git merge-base "origin/$next" "$source") +git checkout --quiet -B "$branch" "origin/$next" +git config user.name 'github-actions[bot]' +git config user.email '41898282+github-actions[bot]@users.noreply.github.com' +git merge --quiet --no-ff --no-commit "$source" || true +git rev-parse --verify --quiet MERGE_HEAD >/dev/null || { + echo "::error::merging $source into $next did not start" + exit 1 +} + +# Only what a writer of §9.2 or `cargo metadata` writes from the merged tree. +# What a writer reads (an export's `roots.json`, a measured row of +# `tests/stack-bounds.json`) is authored, and a conflict in it is listed. +generated() { + case "$1" in + SPEC.md | model/ids.toml | model/errors.toml | model/ledger.toml | model/authorities.toml \ + | CONFORMANCE.md | ERRORS.md | Cargo.lock | lexlean.lock | */lexlean.lock | */expected/* \ + | tests/golden/*.txt | tests/production-export/*/packages/*) return 0 ;; + *) return 1 ;; + esac +} +unresolved=() +while IFS= read -r path; do + [ -n "$path" ] || continue + generated "$path" || unresolved+=("$path") + if git cat-file -e "HEAD:$path" 2>/dev/null; then + git checkout --quiet HEAD -- "$path" + else + git rm --quiet --cached --ignore-unmatch -- "$path" + rm -f -- "$path" + fi +done < <(git diff --name-only --diff-filter=U) + +projections=(SPEC.md model/ids.toml model/errors.toml model/ledger.toml model/authorities.toml) +if ! git cat-file -e "$source:spec/src" 2>/dev/null; then + # The projections the next line writes from its modules keep nothing of the + # pushed line's own text but what the port carries into the modules. + git checkout --quiet HEAD -- "${projections[@]}" + scratch=$(mktemp -d) + portable=true + for path in SPEC.md model/ids.toml; do + name=${path##*/} + git show "$base:$path" >"$scratch/base-$name" + git show "HEAD:$path" >"$scratch/next-$name" + git show "$source:$path" >"$scratch/line-$name" + if ! git merge-file -p "$scratch/next-$name" "$scratch/base-$name" "$scratch/line-$name" >"$scratch/$name"; then + unresolved+=("$path (both lines changed one hunk)") + portable=false + fi + done + for path in model/errors.toml model/ledger.toml model/authorities.toml; do + if ! git diff --quiet "$base" "$source" -- "$path"; then + unresolved+=("$path (changed on $line; its module is edited by hand)") + fi + done + if [ "$portable" = true ] && ! git diff --quiet "$base" "$source" -- SPEC.md model/ids.toml; then + args=(--merged "$scratch/SPEC.md") + git diff --quiet "$base" "$source" -- model/ids.toml || args+=(--register "$scratch/ids.toml") + if ! cargo xtask spec port "${args[@]}" 2>&1 | tee "$scratch/port.txt"; then + unresolved+=("spec/src (the port refused: $(tail -1 "$scratch/port.txt"))") + git checkout --quiet HEAD -- spec/ "${projections[@]}" + fi + fi + rm -rf "$scratch" +fi +# A lock that took the next line's side gains what the merged manifests add. +cargo metadata --format-version 1 >/dev/null +git add --all + +clean=true +[ "${#unresolved[@]}" -eq 0 ] || clean=false +{ + printf 'Merge %s into %s\n\n' "$line" "$next" + printf 'Forward merge of %s at %s (forward.yml).\n' "$line" "$source" + if [ "$clean" = false ]; then + printf '\nCommitted as the side of %s, to finish by hand:\n' "$next" + printf -- '- %s\n' "${unresolved[@]}" + fi +} >"${RUNNER_TEMP:-/tmp}/forward-message" +git commit --quiet --no-verify -F "${RUNNER_TEMP:-/tmp}/forward-message" +git push --quiet origin "HEAD:refs/heads/$branch" +commit=$(git rev-parse HEAD) +{ + echo "branch=$branch" + echo "commit=$commit" + echo "clean=$clean" +} >>"$output" + +# An older forward pull request of these lines is superseded only when its +# branch holds nothing but what this run makes again: the bot's merge and the +# bot's regeneration on it. One carrying any other commit (a conflict finished +# by hand) stays open, linked from the new one, until its work is carried. +bot_pattern='41898282\+github-actions\[bot\]@users\.noreply\.github\.com' +superseded=() +kept=() +while read -r number ref; do + [ -n "$number" ] || continue + if ! git fetch --quiet origin "refs/heads/$ref:refs/remotes/origin/$ref"; then + kept+=("$number") + continue + fi + extra=$(git log --format='%ae %s' "origin/$ref" --not "origin/$next" "$source" | + grep -v -x -E "$bot_pattern (Merge release/v[0-9.]+ into release/v[0-9.]+|Regenerate the written outputs of [0-9a-f]+)" || true) + if [ -z "$extra" ]; then + # The head inspected here is the lease of its deletion below. + superseded+=("$number $ref $(git rev-parse "origin/$ref")") + else + kept+=("$number") + fi +done < <(gh pr list --repo "$repo" --base "$next" --state open --json number,headRefName \ + --jq ".[] | select(.headRefName | startswith(\"$prefix\")) | select(.headRefName != \"$branch\") | \"\\(.number) \\(.headRefName)\"") + +title="Forward-merge $line (${source:0:8}) into $next" +if [ "$clean" = true ]; then + body="Merges \`$line\` at \`$source\` into \`$next\` (SPEC.md §9.4; opened by \`forward.yml\`). \`regenerate.yml\` writes the generated projections and locks from the merged tree, delivers them here, and dispatches the gate. Land it with a merge commit." + draft=() +else + body="Merges \`$line\` at \`$source\` into \`$next\` (SPEC.md §9.4; opened by \`forward.yml\`). These paths are committed as \`$next\`'s side and are finished by hand before this is ready; then push the head to \`regenerate/\`:"$'\n\n'"$(printf -- '- `%s`\n' "${unresolved[@]}")" + draft=(--draft) +fi +if [ "${#kept[@]}" -gt 0 ]; then + body+=$'\n\n'"Older forward pull requests with work missing from \`$next\`, left open: $(printf '#%s ' "${kept[@]}")" +fi +if url=$(gh pr create --repo "$repo" --base "$next" --head "$branch" "${draft[@]}" \ + --title "$title" --body "$body" 2>&1); then + say "Opened $url" +else + # The repository may not let the workflow token open pull requests. With + # no replacement open, nothing older is closed. + echo "::warning::no pull request opened ($url)" + say "Open the pull request: $GITHUB_SERVER_URL/$repo/compare/$next...$branch" + superseded=() +fi +[ "$clean" = true ] || say "Finish by hand: $(printf '`%s` ' "${unresolved[@]}")" +[ "${#kept[@]}" -eq 0 ] || say "Left open, with work missing from \`$next\`: $(printf '#%s ' "${kept[@]}")" +# A branch is deleted only while its head is still the one inspected (a lease: +# a push to it since then refuses the delete), and its pull request is closed +# only once that delete succeeded. Any other is kept and listed. +moved=() +for older in "${superseded[@]}"; do + read -r number ref sha <<<"$older" + if git push --quiet --force-with-lease="refs/heads/$ref:$sha" origin ":refs/heads/$ref"; then + gh pr close "$number" --repo "$repo" --comment "Superseded by $url." || + gh pr comment "$number" --repo "$repo" --body "Superseded by $url." || + echo "::warning::#$number not closed" + else + moved+=("$number") + fi +done +if [ "${#moved[@]}" -gt 0 ]; then + note="Older forward pull requests whose branch moved since this run read it, left open: $(printf '#%s ' "${moved[@]}")" + say "$note" + gh pr comment "$url" --repo "$repo" --body "$note" || true +fi diff --git a/.github/workflows/forward.yml b/.github/workflows/forward.yml new file mode 100644 index 0000000000..fd9a2c4298 --- /dev/null +++ b/.github/workflows/forward.yml @@ -0,0 +1,74 @@ +# The forward merge of a release line (SPEC.md §9.4): every push to +# `release/vX.Y` is merged, by merge commit, into `release/vX.(Y+1)` when that +# line exists, on the branch `forward/vXY-to-vX(Y+1)-`, with its pull +# request (`.github/scripts/forward-merge.sh`). A merge whose conflicts lie in +# generated projections and locks is opened ready, and `regenerate.yml` writes +# those files from the merged tree, delivers them to the branch, and +# dispatches the gate there. Any other conflict is committed as the next +# line's side and opened as a draft naming its paths, for an agent to finish +# and push to `regenerate/`. A newer push to the line cancels a run still +# working and closes the older forward pull request. +name: forward + +on: + push: + branches: ["release/**"] + # A merge made with the workflow token starts no push run, so a workflow + # that lands on a line itself (`cut.yml`) calls this one with the line. + workflow_call: + inputs: + line: + description: The release line whose head is carried forward + type: string + required: true + +permissions: + contents: read + +jobs: + merge: + name: forward merge + if: github.repository == 'UOR-Foundation/LexLean' + runs-on: ubuntu-24.04 + timeout-minutes: 30 + # On the job, not the workflow: a call from `cut.yml` is part of the + # caller's run, which a newer push to the line must not cancel. + concurrency: + group: forward-${{ inputs.line || github.ref_name }} + cancel-in-progress: true + permissions: + contents: write + pull-requests: write + outputs: + branch: ${{ steps.merge.outputs.branch }} + commit: ${{ steps.merge.outputs.commit }} + clean: ${{ steps.merge.outputs.clean }} + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ inputs.line || github.sha }} + fetch-depth: 0 + - name: Install the pinned Rust toolchain + run: rustup toolchain install + - name: Merge the line into the next and open the pull request + id: merge + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + LINE: ${{ inputs.line || github.ref_name }} + run: .github/scripts/forward-merge.sh + + regenerate: + name: regenerate + needs: merge + if: needs.merge.outputs.clean == 'true' + uses: ./.github/workflows/regenerate.yml + # A reusable workflow is validated against what its caller grants before + # any of its jobs starts: `deliver` pushes and dispatches. + permissions: + contents: write + actions: write + pull-requests: read + with: + ref: ${{ needs.merge.outputs.commit }} + branch: ${{ needs.merge.outputs.branch }} diff --git a/AGENTS.md b/AGENTS.md index 377139945c..7c65cda5b6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -123,6 +123,8 @@ decision: `cut.yml` regenerates the cut, waits for its gate, merges its pull request at the verified head, tags and publishes it (`tag.yml`, `release.yml`). Merge the pull request by hand only when `cut.yml` stopped short and says why. +Each push to a release line opens its forward merge into the next line +(`forward.yml`); a draft one names the conflicts left to finish by hand. A pull request that is final is marked ready with auto-merge on (`gh pr merge --auto --merge`), so it lands when its gate passes and its branch is deleted on merge. diff --git a/CHANGELOG.md b/CHANGELOG.md index 79903478bd..6f4f4208f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,15 @@ workspace carried at those versions without a tag. ## Unreleased +- Each push to a release line is merged forward by `forward.yml` (SPEC.md §9.4, `RP-14`): + the push is merged into the next line on `forward/vXY-to-vX(Y+1)-`, a conflict in a + generated projection or a lock takes the next line's side for `regenerate.yml` to rewrite, + SPEC.md and register changes of a line without `spec/` are carried into the next line's + modules by `cargo xtask spec port --register`, and any other conflict opens the pull + request as a draft naming its paths, an authored writer input such as an export's + `roots.json` among them. A newer push closes an older forward pull request only when its + branch holds nothing but the workflow's merge and regeneration, and only once the new one + is open; one with work finished by hand stays open and is linked. - CI runs the macOS AArch64 host's tests in lanes, as it does Windows' (SPEC.md §8.3): five lanes on `macos-15`, the four conformance lanes of `.github/intel-host-lanes.json` and the `producer` lane, joined on `ubuntu-24.04` under the unchanged context `build and non-Lean tests (aarch64-apple-darwin)`, diff --git a/SPEC.md b/SPEC.md index 6ca68cb07d..04ead970dc 100644 --- a/SPEC.md +++ b/SPEC.md @@ -693,10 +693,12 @@ Its image MUST install the pinned Rust and Lean toolchains at build, so that not `ci.yml` MUST run every recipe of `just vv` from a clean checkout on Linux x86-64. It MUST install the exact Rust toolchain, Lean 4.32.2 through `elan`, `just`, and `cargo-deny`. -**What a run is.** `ci.yml` starts with the job `plan`, which decides from the event and the repository alone, through `.github/ci-plan.sh`, what the run is before any job that costs a runner starts. A pull request that is a draft runs the initial honesty part then the `rest` leg: a head pushed again before it is final costs these two jobs and not the full gate, the run is a development signal, and a draft is not mergeable on it; marking the pull request ready, and every push to it after, run the whole gate. So is a ready pull request whose base branch is neither `main` nor a `release/*` line (a stacked pull request, whose base is another feature branch): only a pull request into `main` or a release line can land on a line, that pull request runs the whole gate on the tree it lands, and the stacked run says in its step summary that the base is why it runs honesty then the `rest` leg. A ready pull request into `main` or a release line, a `workflow_dispatch`, and a push to `main` or to a release line are the whole gate, every job below, except that a ready pull request into a release line runs no Intel macOS job (the construction, its lanes and their aggregate, §8.3) unless its head branch is a release cut, `cut/v*`: Intel macOS has about one hosted runner for this repository and its workload takes about three hours of it, so a pull request that waited for it waited for hours, and the push that lands the pull request runs those jobs on the tree it lands. The plan names this in the output `intel`, which is set on every whole gate but those pull requests, and the Intel jobs run when it is set; a pull request into `main` and a release cut run them, so the run that verified a tag's tree (§30.3) still holds every host. A `workflow_dispatch` on the head branch of exactly one open pull request of this repository is planned as that pull request, by its draft flag and base, because `regenerate.yml` commits to that branch with the workflow token, whose push starts no `pull_request` run, and dispatches the gate there instead; a dispatch on any other branch, or one whose pull request the plan cannot read, is the whole gate. A dispatch planned as a ready pull request whose head's tree such a run already verified, by the same walk down equal-tree merges from the head itself, runs no job but the plan, which records the run. One push to `main` or to a release line is not: when it is a merge commit whose tree is the tree of its second parent (a pull request head that already contained `main`) and a run of this workflow passed every job for that parent as a pull request of this repository or dispatched on its branch (or, while the parent is itself a merge whose tree is its second parent's, for that second parent, at most four merges down, as when a release merge that landed a regenerated head is carried to `main`), with none skipped, the join of Atlas, every host of §8.3, and every leg of `.github/vv-rows.json` among them, the push runs no job but the plan, which records the run: the tree it lands is byte for byte the tree that run verified, on the same runners and with the same pins. When the run of that parent passed every job but the Intel macOS jobs, which it skipped, with the Intel context once and skipped and every other host, leg and the join of Atlas passed, the push runs honesty and the Intel jobs only, and the plan records the run; such a run never counts as the whole gate, for the plan, a dispatch, or the release's evidence. Any other push to `main` or to a release line, including one the plan cannot decide (a failed query, no run, a run of a draft, a merge that changed the tree, a push that is no merge), is the whole gate. `release.yml` consumes the complete same-tree gate evidence described below. `RP-14` runs the script against planted events, among them a ready pull request into a feature branch, into a release line, and into `main`, a release cut, a dispatch on a draft's head, on a ready head, on a cut's head, and on a branch with no pull request, and a push landing a tree a run verified without the Intel jobs, and a plant in it fails the case, and reads the CI and reproducibility workflows' push triggers, which name `main` and `release/**`. +**What a run is.** `ci.yml` starts with the job `plan`, which decides from the event and the repository alone, through `.github/ci-plan.sh`, what the run is before any job that costs a runner starts. A pull request that is a draft runs the initial honesty part then the `rest` leg: a head pushed again before it is final costs these two jobs and not the full gate, the run is a development signal, and a draft is not mergeable on it; marking the pull request ready, and every push to it after, run the whole gate. So is a ready pull request whose base branch is neither `main` nor a `release/*` line (a stacked pull request, whose base is another feature branch): only a pull request into `main` or a release line can land on a line, that pull request runs the whole gate on the tree it lands, and the stacked run says in its step summary that the base is why it runs honesty then the `rest` leg. A ready pull request into `main` or a release line, a `workflow_dispatch`, and a push to `main` or to a release line are the whole gate, every job below, except that a ready pull request into a release line runs no Intel macOS job (the construction, its lanes and their aggregate, §8.3) unless its head branch is a release cut, `cut/v*`: Intel macOS has about one hosted runner for this repository and its workload takes about three hours of it, so a pull request that waited for it waited for hours, and the push that lands the pull request runs those jobs on the tree it lands. The plan names this in the output `intel`, which is set on every whole gate but those pull requests, and the Intel jobs run when it is set; a pull request into `main` and a release cut run them, so the run that verified a tag's tree (§30.3) still holds every host. A `workflow_dispatch` on the head branch of exactly one open pull request of this repository is planned as that pull request, by its draft flag and base, because `regenerate.yml` commits to that branch with the workflow token, whose push starts no `pull_request` run, and dispatches the gate there instead; a dispatch on any other branch, or one whose pull request the plan cannot read, is the whole gate. A dispatch planned as a ready pull request whose head's tree such a run already verified, by the same walk down equal-tree merges from the head itself, runs no job but the plan, which records the run. One push to `main` or to a release line is not: when it is a merge commit whose tree is the tree of its second parent (a pull request head that already contained `main`) and a run of this workflow passed every job for that parent as a pull request of this repository or dispatched on its branch (or, while the parent is itself a merge whose tree is its second parent's, for that second parent, at most four merges down, as when a release merge that landed a regenerated head is carried to `main`), with none skipped, the join of Atlas, every host of §8.3, and every leg of `.github/vv-rows.json` among them, the push runs no job but the plan, which records the run: the tree it lands is byte for byte the tree that run verified, on the same runners and with the same pins. When the run of that parent passed every job but the Intel macOS jobs, which it skipped, with the Intel context once and skipped and every other host, leg and the join of Atlas passed, the push runs honesty and the Intel jobs only, and the plan records the run; such a run never counts as the whole gate, for the plan, a dispatch, or the release's evidence. Any other push to `main` or to a release line, including one the plan cannot decide (a failed query, no run, a run of a draft, a merge that changed the tree, a push that is no merge), is the whole gate. `release.yml` consumes the complete same-tree gate evidence described below. `RP-14` runs the script against planted events, among them a ready pull request into a feature branch, into a release line, and into `main`, a release cut, a dispatch on a draft's head, on a ready head, on a cut's head, and on a branch with no pull request, and a push landing a tree a run verified without the Intel jobs, and a plant in it fails the case, and reads the CI and reproducibility workflows' push triggers, which name `main` and `release/**`, and the forward merge's, which names `release/**`, with the regeneration it calls on the forward branch. **Release lines.** A release line is the branch `release/vX.Y` of the release X.Y: it is cut from `main` when work on X.Y begins, every pull request for the milestone X.Y targets it, each `vX.Y.Z` tag is made from it, and it is merged forward, by merge commit, into the next release line after each landing so that the next line carries every fix of the one before it. `main` is the newest released line: a release line is merged into `main` when its release is tagged, and nothing else lands on `main`. A release line is held to the same gate as `main`: a push to it is the whole gate under the rule above, and a pull request against it is a pull request of this repository. +**Forward merges.** `forward.yml` makes the forward merge of a line on every push to it, and when a workflow that merges onto the line with the workflow token, whose merge starts no push run, calls it with the line: when `release/vX.(Y+1)` exists and does not contain the pushed commit, `.github/scripts/forward-merge.sh` merges the commit, by merge commit, into the head of `release/vX.(Y+1)` on the branch `forward/vXY-to-vX(Y+1)-`, pushes it, and opens its pull request into `release/vX.(Y+1)`. A conflict in a generated projection or a lock (`SPEC.md`, the five projected files of `model/`, CONFORMANCE.md, ERRORS.md, `Cargo.lock`, a `lexlean.lock`, an `expected/` oracle, the golden files, the packages under `tests/production-export/*/packages/`) takes the next line's side, because `regenerate.yml` writes those files again; a file a writer reads rather than writes, such as an export's `roots.json` or a measured row of `tests/stack-bounds.json`, is authored, and its conflict is listed like any other. While the pushed line has no `spec/`, the next line's projections are written from its modules, so what the line changed in SPEC.md and `model/ids.toml` is merged against their merge base and carried into the modules by `cargo xtask spec port --merged --register `; the port refuses an added or removed register row, which is written in its module by hand. Every other conflict, a hunk both lines changed, a change of another model file, and a refused port are committed as the next line's side, and the pull request is opened as a draft naming each, for the change to be finished by hand and regenerated through `regenerate/`. Otherwise the pull request is opened ready and `regenerate.yml` is called on the merge with the branch named, so `deliver` commits the regenerated tree there and dispatches the gate, which verifies the merge as it does any pull request into the line. When the workflow token may not open pull requests, the step summary names the compare link instead, as `cut.yml`'s does. A newer push to the line cancels a forward merge job still working. Once the new pull request is open, it closes an open forward pull request of an older commit and deletes its branch only when that branch holds no commit but the workflow's merge and the regeneration delivered on it; one that carries any other commit, such as a conflict finished by hand, stays open and is named in the new pull request, and when no new pull request could be opened nothing older is closed. The delete is leased to the head the workflow inspected (`--force-with-lease`), so a branch pushed to since then refuses it, and the older pull request is closed only after its branch was deleted; one whose branch moved or whose delete failed stays open with its branch and is named on the new pull request. + **Cutting a release.** A release `X.Y.Z` is cut by one push of the line's head to the branch `cut/vX.Y.Z`. `cut.yml` refuses a name that is not a version, a commit not on `release/vX.Y`, and a version already tagged; it runs `cargo xtask bump-version X.Y.Z`, which moves every site of the workspace version together (the `[workspace.package]` version and the workspace's path dependencies in `Cargo.toml`, the §2.3 block above, the identity literals of `RP-01` and `RP-12`, the changelog's `## Unreleased` heading, which becomes `## X.Y.Z` under a new empty `## Unreleased`, and the workspace rows of `Cargo.lock`), refuses to write anything when a site does not read as it expects or the version does not follow the workspace's, and puts every file back when the lock cannot be updated, commits that on the pushed commit, opens the pull request into the line, and calls `regenerate.yml` on the commit, which writes what the version moves and delivers it to the branch. The cut is the decision to release, and nothing after it waits for a person. `regenerate.yml` returns the head it delivered and dispatched `ci.yml` on; `cut.yml` waits for that run (in two jobs of at most six hours each, because the gate runs for hours) and lands the cut only when `.github/release-gate.sh` accepts it as the whole gate with every job passed, the evidence `release.yml` will attach. It then merges the pull request with a merge commit of exactly that head onto the line's head, which must be an ancestor of it, and pushes the merge with a lease on that line head, so a line that moves meanwhile refuses the push and the merge's tree is always the head's; a merge made with the workflow token starts no run, so `cut.yml` calls `tag.yml` on that merge itself. `tag.yml` also runs on every push to a release line, which is how a person's merge of a cut releases. It stops at once unless the commit changed the workspace version from its first parent's to one with no tag and a `## X.Y.Z` changelog entry; then it accepts the commit's tree as verified when `release-gate.sh` finds that run (on the commit, or, while it is a merge whose tree is its second parent's, on that parent), and otherwise waits for the push's own run of `ci.yml` (a call has none and stops); only when the tree is verified it tags the commit `vX.Y.Z`, dispatches `release.yml` on the tag (a tag pushed with the workflow token starts no run), opens the pull request that merges the line into `main`, dispatches `ci.yml` on the line (a pull request opened with the workflow token starts no run), whose plan finds the run that verified the tagged tree and runs nothing again, and merges that pull request, only while the line's head is still the tagged commit, when the line contains `main` (one such merge at a time across every line, since `main` takes changes only through a pull request and GitHub's merge cannot be bound to the base; the merge is then checked to have the `main` it examined as its first parent and the tagged tree as its tree, and fails loudly otherwise), so the merge lands that tree; when `main` has commits the line lacks, the pull request is left for a person. What stops the landing leaves the cut's pull request open, and merging it by hand releases as above: a gate that failed (re-running its failed jobs and then the cut run's failed jobs lands the cut), a gate with no verdict after both waits, no pull request, a line that moved since the cut, or a head pushed since the gate ran. A tag pushed by hand starts `release.yml` itself; nothing here changes what a release publishes or what evidence it requires. **The release's evidence.** `release.yml` runs no recipe of the gate. The CI evidence a release attaches (§30.3) is a run of `ci.yml` that was the whole gate and passed every job, on the tagged commit or, while the commit is a merge whose tree is the tree of its second parent, on that parent, at most four merges down (the walk the plan makes); `.github/release-gate.sh` finds it under the rule `plan` applies to a push, and refuses, naming the commits it looked at, when no such run exists. The evidence names the run, every job of it with its conclusion, and the transcript of every leg the run still retains. The gate run whole on one hosted runner exceeds the six-hour job limit (the `bdd` recipe alone takes over four hours there, and Atlas follows it), so a release gate that re-ran it would never conclude, and the run of the line has already verified the tree. diff --git a/crates/conformance/src/cases/repository.rs b/crates/conformance/src/cases/repository.rs index cb7ac2a186..ae6550c67e 100644 --- a/crates/conformance/src/cases/repository.rs +++ b/crates/conformance/src/cases/repository.rs @@ -2481,6 +2481,51 @@ pub(crate) fn run(id: &str) { "§9.4: {workflow} runs on a push to `main` and to a release line" ); } + // §9.4: the forward merge runs on every push to a release line, + // superseded by a newer one, and hands its merge to the + // regeneration on the forward branch, whose `deliver` commits there. + let forward = root_file(".github/workflows/forward.yml"); + for needed in [ + " push:\n branches: [\"release/**\"]\n", + " group: forward-${{ inputs.line || github.ref_name }}\n cancel-in-progress: true\n", + " workflow_call:\n", + "run: .github/scripts/forward-merge.sh", + "uses: ./.github/workflows/regenerate.yml", + "ref: ${{ needs.merge.outputs.commit }}", + "branch: ${{ needs.merge.outputs.branch }}", + ] { + assert!(forward.contains(needed), "§9.4: forward.yml has `{needed}`"); + } + let merge = root_file(".github/scripts/forward-merge.sh"); + // An authored writer input is never taken from one side unread. + for forbidden in [ + "tests/production-export/* ", + "tests/production-export/*)", + "tests/stack-bounds.json)", + ] { + assert!( + !merge.contains(forbidden), + "§9.4: forward-merge.sh takes no side of an authored input: `{forbidden}`" + ); + } + for needed in [ + "git merge --quiet --no-ff --no-commit", + "cargo xtask spec port", + "--register", + "--draft", + "compare/$next...$branch", + "tests/production-export/*/packages/*)", + "Regenerate the written outputs of", + "superseded=()", + // The delete of a superseded branch is leased to the head + // inspected, and its pull request closes only after it. + "--force-with-lease=\"refs/heads/$ref:$sha\" origin \":refs/heads/$ref\"", + ] { + assert!( + merge.contains(needed), + "§9.4: forward-merge.sh has `{needed}`" + ); + } for forbidden in [ "actions/cache", "paths:",