diff --git a/.github/scripts/await-gate.sh b/.github/scripts/await-gate.sh new file mode 100755 index 0000000000..262bcb0d9d --- /dev/null +++ b/.github/scripts/await-gate.sh @@ -0,0 +1,63 @@ +#!/usr/bin/env bash +# The wait of `cut.yml` for the gate of a cut (SPEC.md §9.4): polls the runs +# of `ci.yml` on HEAD_SHA, the regenerated head `regenerate.yml` delivered and +# dispatched the gate on, until the newest pull request or dispatched run of +# it completes or WAIT_MINUTES pass. A run that completed `success` counts +# only when `.github/release-gate.sh` accepts it as the whole gate with every +# job passed, the evidence `release.yml` will read for the tag; so a cut lands +# on exactly what would release. +# +# Writes `state` to GITHUB_OUTPUT: `passed`, `failed` (the newest run failed, +# was cancelled, or passed without being the whole gate; exit 1), or +# `pending` (no verdict in time; exit 0, or exit 1 when FINAL is `true`, the +# last wait of the cut). A run re-run after a failure is the newest run again, +# so re-running the cut's failed jobs waits for it afresh. +# +# Inputs, from the environment: REPO, HEAD_SHA, WAIT_MINUTES, FINAL. `gh` +# reads the runs and jobs (`actions: read`); the checkout is HEAD_SHA. +set -euo pipefail + +repo=${REPO:?REPO names owner/name} +head=${HEAD_SHA:?HEAD_SHA names the commit the gate runs on} +wait=${WAIT_MINUTES:-340} +final=${FINAL:-false} +out=${GITHUB_OUTPUT:-/dev/null} +summary=${GITHUB_STEP_SUMMARY:-/dev/null} +say() { printf '%s\n' "$1" | tee -a "$summary"; } + +deadline=$((SECONDS + wait * 60)) +while :; do + state=$(gh api "repos/$repo/actions/workflows/ci.yml/runs?head_sha=$head&per_page=30" \ + --jq "[.workflow_runs[] | select(.head_repository.full_name == \"$repo\") | select(.event == \"pull_request\" or .event == \"workflow_dispatch\")][0] // empty | \"\(.status) \(.conclusion) \(.html_url)\"" \ + 2>/dev/null || true) + case "$state" in + "completed success "*) + if SHA=$head OUT="${RUNNER_TEMP:-/tmp}/gate-evidence.txt" .github/release-gate.sh; then + say "The gate passed on \`$head\`: ${state##* }" + echo "state=passed" >> "$out" + exit 0 + fi + say "The newest run of \`ci.yml\` on \`$head\` passed without being the whole gate: ${state##* }" + echo "state=failed" >> "$out" + exit 1 + ;; + completed*) + echo "::error::the gate of $head did not pass: $state" + say "The gate of \`$head\` did not pass (${state##* }). Re-run its failed jobs, then re-run this run's failed jobs to land the cut; or fix the cut branch and merge its pull request by hand." + echo "state=failed" >> "$out" + exit 1 + ;; + esac + if [ "$SECONDS" -ge "$deadline" ]; then + break + fi + sleep 60 +done + +echo "state=pending" >> "$out" +if [ "$final" = true ]; then + echo "::error::the gate of $head did not finish in time: ${state:-no run yet}" + say "The gate of \`$head\` gave no verdict in time (${state:-no run yet}). Re-run this run's failed jobs to wait again, or merge the pull request by hand once it passes." + exit 1 +fi +say "The gate of \`$head\` gave no verdict in $wait minutes (${state:-no run yet}); the next job waits on." diff --git a/.github/scripts/deliver-regenerated.sh b/.github/scripts/deliver-regenerated.sh index 9cc5c347c7..e327aa40f6 100755 --- a/.github/scripts/deliver-regenerated.sh +++ b/.github/scripts/deliver-regenerated.sh @@ -15,7 +15,9 @@ # # Inputs, from the environment: REPO, COMMIT, BRANCH (may be empty), RUN_URL, # REGENERATED (the downloaded `regenerated-` artifact), GITHUB_REF, -# GITHUB_STEP_SUMMARY. The checkout is COMMIT with the workflow token. +# GITHUB_STEP_SUMMARY. The checkout is COMMIT with the workflow token. Output, +# to GITHUB_OUTPUT: `head`, the commit the gate was dispatched on, when it was +# (`cut.yml` waits for that run and lands the cut on it); nothing otherwise. set -euo pipefail repo=${REPO:?REPO names owner/name} @@ -23,6 +25,7 @@ commit=${COMMIT:?COMMIT names the regenerated commit} branch=${BRANCH:-} dir=${REGENERATED:?REGENERATED names the artifact directory} summary=${GITHUB_STEP_SUMMARY:-/dev/null} +output=${GITHUB_OUTPUT:-/dev/null} say() { printf '%s\n' "$1" | tee -a "$summary"; } (cd "$dir" && sha256sum --check --quiet SHA256SUMS) @@ -54,6 +57,12 @@ if [ -s "$dir/regenerated.patch" ]; then fi if git diff --cached --quiet; then say "The regenerated tree of \`$commit\` is the committed tree: nothing to deliver." + # A caller's branch was pushed with the workflow token, which started no + # run: the gate is dispatched for it all the same. + if [ -n "${BRANCH:-}" ]; then + gh workflow run ci.yml --repo "$repo" --ref "$branch" + echo "head=$commit" >> "$output" + fi else paths=$(git diff --cached --name-only | wc -l) { @@ -71,6 +80,7 @@ else # A plain push is a fast-forward or nothing. git push origin "HEAD:refs/heads/$branch" gh workflow run ci.yml --repo "$repo" --ref "$branch" + echo "head=$(git rev-parse HEAD)" >> "$output" say "Delivered $paths regenerated paths to \`$branch\` as \`$(git rev-parse HEAD)\` and dispatched \`ci.yml\` there." fi diff --git a/.github/workflows/cut.yml b/.github/workflows/cut.yml index dffbca81ae..3b3c1ed55c 100644 --- a/.github/workflows/cut.yml +++ b/.github/workflows/cut.yml @@ -1,5 +1,5 @@ # A release cut in one push (SPEC.md §9.4): the version commit, its -# regeneration, and the pull request that lands it on its line. +# regeneration, its gate, and its landing, tag, and release, with no hand step. # # git push origin release/vX.Y:refs/heads/cut/vX.Y.Z # @@ -8,10 +8,20 @@ # `## X.Y.Z`, commits that on the pushed commit, and opens the pull request # from `cut/vX.Y.Z` into `release/vX.Y`. `regenerate.yml` then writes what the # version moves (every build oracle names the compiler's version), delivers -# that to the branch, and dispatches the gate there. Merging the pull request -# is the decision to release: `tag.yml` tags the merge once its gate passes -# and `release.yml` publishes it. The pushed commit must be on the line, and -# the version must follow the line's and have no tag. +# that to the branch, and dispatches the gate there. `gate` and `gate-more` +# wait for that run (the gate takes hours, and a job may run six), `land` +# merges the pull request at the head the gate passed on, and `tag.yml`, +# called here because a merge made with the workflow token starts no run, +# tags the merge, dispatches `release.yml`, and carries the line to `main`. +# The pushed commit must be on the line, and the version must follow the +# line's and have no tag. +# +# What stops the landing leaves the pull request open, and a person's merge +# of it releases as before (`tag.yml` on the push): a gate that failed (re-run +# its failed jobs, then this run's failed jobs, and the cut lands), a gate +# with no verdict after two waits (re-run this run's failed jobs to wait +# again), no pull request, a line that moved since the cut, or a head pushed +# since the gate ran. name: cut on: @@ -83,7 +93,7 @@ jobs: -m "cargo xtask bump-version $VERSION: the workspace version, SPEC.md §2.3, RP-01, Cargo.lock, and the changelog's unreleased entries." git push origin "HEAD:refs/heads/$GITHUB_REF_NAME" echo "commit=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT" - body="Cuts LexLean $VERSION on \`$LINE\` (\`cut.yml\`). \`regenerate.yml\` writes what the version moves and dispatches the gate here. Merging releases: \`tag.yml\` tags the merge as \`v$VERSION\` once its gate passes, and \`release.yml\` publishes it. Edit the \`## $VERSION\` changelog section before merging if it needs a summary." + body="Cuts LexLean $VERSION on \`$LINE\` (\`cut.yml\`). \`regenerate.yml\` writes what the version moves and dispatches the gate here. Once that gate passes, \`cut.yml\` merges this pull request at the head it verified, tags the merge as \`v$VERSION\`, and \`release.yml\` publishes it; nobody needs to merge it. A push to this branch before then stops the automatic landing, and merging by hand releases as before." if url=$(gh pr create --repo "$GITHUB_REPOSITORY" --base "$LINE" --head "$GITHUB_REF_NAME" \ --title "Release $VERSION" --body "$body" 2>&1); then echo "Opened $url" >> "$GITHUB_STEP_SUMMARY" @@ -106,3 +116,140 @@ jobs: with: ref: ${{ needs.version.outputs.commit }} branch: ${{ needs.version.outputs.branch }} + + # The gate of the delivered head: the run `regenerate.yml` dispatched, + # planned as the pull request's, which must be the whole gate and pass every + # job. Two waits, because the gate runs for hours and a job for at most six. + gate: + name: wait for the gate + needs: regenerate + if: needs.regenerate.outputs.head != '' + runs-on: ubuntu-24.04 + timeout-minutes: 360 + permissions: + contents: read + actions: read + outputs: + state: ${{ steps.wait.outputs.state }} + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ needs.regenerate.outputs.head }} + persist-credentials: false + - name: Wait for the gate of the delivered head + id: wait + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + HEAD_SHA: ${{ needs.regenerate.outputs.head }} + WAIT_MINUTES: "340" + run: .github/scripts/await-gate.sh + + gate-more: + name: wait for the gate (continued) + needs: [regenerate, gate] + if: needs.gate.outputs.state == 'pending' + runs-on: ubuntu-24.04 + timeout-minutes: 360 + permissions: + contents: read + actions: read + outputs: + state: ${{ steps.wait.outputs.state }} + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ needs.regenerate.outputs.head }} + persist-credentials: false + - name: Wait for the gate of the delivered head + id: wait + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + HEAD_SHA: ${{ needs.regenerate.outputs.head }} + WAIT_MINUTES: "340" + FINAL: "true" + run: .github/scripts/await-gate.sh + + # The merge of the pull request at the head the gate passed on, as a merge + # commit made here on the line's head B and pushed with a lease on B: B is + # an ancestor of the head, so the merge's tree is the head's, the evidence + # `ci.yml`'s plan and `release-gate.sh` accept for it (the push, made with + # the workflow token, starts no run of its own), and a line that moved after + # the check refuses the push instead of taking a tree nobody verified. + land: + name: land the cut + needs: [version, regenerate, gate, gate-more] + if: >- + !cancelled() && needs.regenerate.result == 'success' + && (needs.gate.outputs.state == 'passed' || needs.gate-more.outputs.state == 'passed') + runs-on: ubuntu-24.04 + timeout-minutes: 15 + permissions: + contents: write + pull-requests: write + outputs: + merge: ${{ steps.merge.outputs.merge }} + line: ${{ steps.merge.outputs.line }} + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + - name: Merge the pull request at the verified head + id: merge + shell: bash + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + BRANCH: ${{ needs.version.outputs.branch }} + HEAD_SHA: ${{ needs.regenerate.outputs.head }} + REPO_OWNER: ${{ github.repository_owner }} + run: | + set -euo pipefail + pr=$(gh pr list --repo "$REPO" --head "$BRANCH" --state open --json number,baseRefName,headRefOid \ + --jq '.[] | "\(.number) \(.baseRefName) \(.headRefOid)"') + if [ -z "$pr" ] || [ "$(printf '%s\n' "$pr" | wc -l)" -ne 1 ]; then + echo "::error::no single open pull request from $BRANCH; open it and merge it by hand" + exit 1 + fi + read -r number line head <<< "$pr" + if [ "$head" != "$HEAD_SHA" ]; then + echo "::error::$BRANCH is at $head, not $HEAD_SHA where the gate passed; merge it by hand once its gate passes" + exit 1 + fi + git fetch --quiet origin "+refs/heads/$line:refs/remotes/origin/$line" + base=$(git rev-parse "refs/remotes/origin/$line") + if ! git merge-base --is-ancestor "$base" "$HEAD_SHA"; then + echo "::error::$line moved to $base since the cut, so the merge would land a tree the gate did not verify; merge it by hand" + exit 1 + fi + git checkout --quiet --detach "$base" + git -c user.name='github-actions[bot]' \ + -c user.email='41898282+github-actions[bot]@users.noreply.github.com' \ + merge --quiet --no-ff --no-edit \ + -m "Merge pull request #$number from $REPO_OWNER/$BRANCH" -m "Release ${BRANCH#cut/v}, landed by cut.yml at the head its gate verified." "$HEAD_SHA" + if [ "$(git rev-parse 'HEAD^{tree}')" != "$(git rev-parse "$HEAD_SHA^{tree}")" ]; then + echo "::error::the merge's tree is not the tree the gate verified" + exit 1 + fi + # The lease makes the push land only on the B checked above. + git push --force-with-lease="refs/heads/$line:$base" origin "HEAD:refs/heads/$line" + merge=$(git rev-parse HEAD) + echo "merge=$merge" >> "$GITHUB_OUTPUT" + echo "line=$line" >> "$GITHUB_OUTPUT" + echo "Merged #$number into \`$line\` as \`$merge\` at the verified head \`$HEAD_SHA\`." >> "$GITHUB_STEP_SUMMARY" + + tag: + name: tag + needs: land + uses: ./.github/workflows/tag.yml + # A reusable workflow is validated against what its caller grants: `tag` + # pushes the tag, dispatches, and opens and merges the pull request into + # `main`. + permissions: + contents: write + actions: write + pull-requests: write + with: + commit: ${{ needs.land.outputs.merge }} + line: ${{ needs.land.outputs.line }} diff --git a/.github/workflows/regenerate.yml b/.github/workflows/regenerate.yml index 2b1fb67b43..a381de13b0 100755 --- a/.github/workflows/regenerate.yml +++ b/.github/workflows/regenerate.yml @@ -16,7 +16,8 @@ # # A push to `regenerate/**` starts it from any commit, because GitHub # dispatches only a workflow its default branch carries. `cut.yml` calls it on -# the version commit of a release cut, naming the branch to deliver to. +# the version commit of a release cut, naming the branch to deliver to, and +# lands the cut once the gate passes on the head this returns (`head`). name: regenerate on: @@ -41,6 +42,10 @@ on: atlas: type: boolean default: false + outputs: + head: + description: The commit of `branch` the gate was dispatched on (the delivered head), or empty when nothing was delivered or dispatched + value: ${{ jobs.deliver.outputs.head }} permissions: contents: read @@ -350,6 +355,8 @@ jobs: contents: write actions: write pull-requests: read + outputs: + head: ${{ steps.deliver.outputs.head }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: @@ -359,6 +366,7 @@ jobs: name: regenerated-${{ inputs.ref || github.sha }} path: ${{ runner.temp }}/regenerated - name: Commit the regenerated tree to the pull request and run the gate there + id: deliver shell: bash env: GH_TOKEN: ${{ github.token }} diff --git a/.github/workflows/tag.yml b/.github/workflows/tag.yml index 1d4937c4a0..a48d856935 100644 --- a/.github/workflows/tag.yml +++ b/.github/workflows/tag.yml @@ -1,9 +1,18 @@ -# The tag of a cut (SPEC.md §9.4): a push to a release line whose first -# parent carried another workspace version is the merge of a cut (`cut.yml`). -# Once `ci.yml` has passed on that push, this tags it `vX.Y.Z`, dispatches -# `release.yml` on the tag (a tag pushed with the workflow token starts no -# run), and opens the pull request that carries the line to `main`, which -# receives a line at its tag, with auto-merge on. Any other push ends at the first step. +# The tag of a cut (SPEC.md §9.4): a commit on a release line whose first +# parent carried another workspace version is the merge of a cut. `cut.yml` +# calls this on the merge it made once the gate passed on the cut's head (a +# merge pushed with the workflow token starts no run); a push to a line, a +# person's merge of a cut, starts it too. Once the commit's tree is verified, +# this tags it `vX.Y.Z`, dispatches `release.yml` on the tag (a tag pushed with +# the workflow token starts no run), and opens the pull request that carries +# the line to `main`, which receives a line at its tag, and merges it when the +# line contains `main`. Any other commit ends at the first step. +# +# The tree is verified when `.github/release-gate.sh` finds the run of +# `ci.yml` that `release.yml` will attach: one on the commit, or, while it is +# a merge whose tree is its second parent's, on that parent (the cut's head). +# A push without such a run waits for its own push run; a call has none to +# wait for and stops. # # A gate that fails leaves the commit untagged; tag it by hand once a rerun # passes (`git tag -a vX.Y.Z -m "LexLean vX.Y.Z" && git push origin vX.Y.Z`), @@ -13,28 +22,45 @@ name: tag on: push: branches: ["release/**"] + workflow_call: + inputs: + commit: + description: The merge of a cut on its line, which `cut.yml` made + type: string + required: true + line: + description: The release line the commit is on, `release/vX.Y` + type: string + required: true permissions: contents: read -concurrency: - group: tag-${{ github.ref }} - cancel-in-progress: false - jobs: tag: name: tag a cut if: github.repository == 'UOR-Foundation/LexLean' runs-on: ubuntu-24.04 + # One per line, whether pushed or called (a called workflow's `github.ref` + # is its caller's). + concurrency: + group: tag-refs/heads/${{ inputs.line || github.ref_name }} + cancel-in-progress: false # The gate of a push that does not merge a verified tree runs for hours. timeout-minutes: 360 + env: + COMMIT: ${{ inputs.commit || github.sha }} + LINE: ${{ inputs.line || github.ref_name }} + CALLED: ${{ inputs.commit != '' }} permissions: contents: write actions: write - pull-requests: write + outputs: + version: ${{ steps.cut.outputs.version }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + ref: ${{ inputs.commit || github.sha }} fetch-depth: 2 - name: Is this push a cut id: cut @@ -57,7 +83,7 @@ jobs: exit 1 fi echo "version=$version" >> "$GITHUB_OUTPUT" - - name: Wait for the gate of this push + - name: Wait for the gate of this commit's tree if: steps.cut.outputs.version != '' shell: bash env: @@ -65,16 +91,23 @@ jobs: REPO: ${{ github.repository }} run: | set -euo pipefail + if SHA=$COMMIT OUT="$RUNNER_TEMP/gate-evidence.txt" .github/release-gate.sh; then + exit 0 + fi + if [ "$CALLED" = true ]; then + echo "::error::no run of ci.yml verified the tree of $COMMIT, and a merge made with the workflow token starts none" + exit 1 + fi for _ in $(seq 1 340); do - state=$(gh api "repos/$REPO/actions/workflows/ci.yml/runs?head_sha=$GITHUB_SHA&event=push&per_page=1" \ + state=$(gh api "repos/$REPO/actions/workflows/ci.yml/runs?head_sha=$COMMIT&event=push&per_page=1" \ --jq '.workflow_runs[0] | "\(.status) \(.conclusion) \(.html_url)"' 2>/dev/null || true) case "$state" in "completed success "*) echo "gate passed: ${state##* }"; exit 0 ;; - completed*) echo "::error::the gate of $GITHUB_SHA did not pass: $state"; exit 1 ;; + completed*) echo "::error::the gate of $COMMIT did not pass: $state"; exit 1 ;; esac sleep 60 done - echo "::error::the gate of $GITHUB_SHA did not finish in time" + echo "::error::the gate of $COMMIT did not finish in time" exit 1 - name: Tag, release, and carry the line to main if: steps.cut.outputs.version != '' @@ -90,19 +123,77 @@ jobs: tag -a "v$VERSION" -m "LexLean v$VERSION" git push origin "refs/tags/v$VERSION" gh workflow run release.yml --repo "$REPO" --ref "v$VERSION" - echo "Tagged v$VERSION at $GITHUB_SHA and dispatched release.yml" >> "$GITHUB_STEP_SUMMARY" - if [ -z "$(gh pr list --repo "$REPO" --base main --head "$GITHUB_REF_NAME" --state open --json number --jq '.[].number')" ]; then - gh pr create --repo "$REPO" --base main --head "$GITHUB_REF_NAME" \ + echo "Tagged v$VERSION at $COMMIT and dispatched release.yml" >> "$GITHUB_STEP_SUMMARY" + + # The line carried to `main` at its tag. `main` takes changes only through a + # pull request, and GitHub's merge binds the head (the tagged commit) but + # not the base, so the step that checks `main` and merges runs one at a time + # across every line, and the merge it made is checked after: its first + # parent must be the `main` checked and its tree the tagged commit's. + main: + name: carry the line to main + needs: tag + if: needs.tag.outputs.version != '' + runs-on: ubuntu-24.04 + timeout-minutes: 15 + concurrency: + group: tag-main + cancel-in-progress: false + env: + COMMIT: ${{ inputs.commit || github.sha }} + LINE: ${{ inputs.line || github.ref_name }} + VERSION: ${{ needs.tag.outputs.version }} + # Merging a pull request writes the base branch: contents, not only + # pull-requests. + permissions: + contents: write + actions: write + pull-requests: write + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ inputs.commit || github.sha }} + fetch-depth: 0 + - name: Merge the line into main at its tag + shell: bash + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + run: | + set -euo pipefail + if [ -z "$(gh pr list --repo "$REPO" --base main --head "$LINE" --state open --json number --jq '.[].number')" ]; then + gh pr create --repo "$REPO" --base main --head "$LINE" \ --title "Land v$VERSION on main" \ - --body "\`main\` receives \`$GITHUB_REF_NAME\` at its tag \`v$VERSION\` (SPEC.md §9.4; opened by \`tag.yml\`)." \ + --body "\`main\` receives \`$LINE\` at its tag \`v$VERSION\` (SPEC.md §9.4; opened by \`tag.yml\`)." \ || echo "::warning::no pull request into main opened" fi # A pull request opened with the workflow token starts no run, so the # gate is dispatched on the line: its plan finds the full run that # verified the tagged tree (the regenerated head of the cut, under - # equal-tree merges) and runs nothing again. The line contains - # `main`, so the merge lands that tree, and it merges itself once - # its checks pass. - gh workflow run ci.yml --repo "$REPO" --ref "$GITHUB_REF_NAME" - gh pr merge --repo "$REPO" "$GITHUB_REF_NAME" --auto --merge \ - || echo "::warning::auto-merge not enabled on the pull request into main" + # equal-tree merges) and runs nothing again. + gh workflow run ci.yml --repo "$REPO" --ref "$LINE" + # Only a line that contains `main` lands the verified tree unchanged; + # otherwise `main` has commits the line lacks, and the pull request + # waits for a person to reconcile them. + git fetch --quiet origin "+refs/heads/main:refs/remotes/origin/main" + base=$(git rev-parse refs/remotes/origin/main) + if ! git merge-base --is-ancestor "$base" "$COMMIT"; then + echo "::warning::main has commits $LINE lacks; the pull request into main waits for a person" + echo "\`main\` has commits \`$LINE\` lacks: the pull request into main is left for a person." >> "$GITHUB_STEP_SUMMARY" + exit 0 + fi + # Bound to the tagged commit: a line that moved past it is not what + # this run verified, and the merge is refused. + if ! gh pr merge --repo "$REPO" "$LINE" --merge --match-head-commit "$COMMIT"; then + echo "::warning::the pull request into main did not merge at $COMMIT; it waits for a person" + exit 0 + fi + merge=$(gh pr list --repo "$REPO" --base main --head "$LINE" --state merged --limit 1 \ + --json mergeCommit --jq '.[0].mergeCommit.oid') + git fetch --quiet origin "$merge" + if [ "$(git rev-parse "$merge^1")" != "$base" ] \ + || [ "$(git rev-parse "$merge^{tree}")" != "$(git rev-parse "$COMMIT^{tree}")" ]; then + echo "::error::main moved during the merge: $merge is not v$VERSION's tree on the main that was checked ($base); revert it by a pull request" + exit 1 + fi + echo "Merged \`$LINE\` into \`main\` as \`$merge\`, the tree of \`v$VERSION\`." >> "$GITHUB_STEP_SUMMARY" diff --git a/AGENTS.md b/AGENTS.md index 39de274e8c..132110311c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -118,8 +118,11 @@ The mechanical steps are workflows, not hand work. A tree that moves committed output is regenerated by pushing its head to `regenerate/`; when that head is an open pull request's, `regenerate.yml` commits the result to the pull request and restarts the gate there. A release `X.Y.Z` is cut by -`git push origin release/vX.Y:refs/heads/cut/vX.Y.Z`; merging the pull request -`cut.yml` opens tags and publishes it (`tag.yml`, `release.yml`). +`git push origin release/vX.Y:refs/heads/cut/vX.Y.Z`; that push is the whole +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. 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 1b88dae65c..1dbd517dba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -49,8 +49,12 @@ workspace carried at those versions without a tag. A release is cut by pushing the line's head to `cut/vX.Y.Z`: `cut.yml` runs the new `cargo xtask bump-version X.Y.Z` (every site of the workspace version, the changelog's `## Unreleased` heading, and `Cargo.lock`), opens the - pull request, and regenerates it; `tag.yml` tags the merge once its gate - passes, dispatches `release.yml`, and opens the pull request into `main`. + pull request, regenerates it, waits for the gate on the regenerated head, + merges the pull request at that head, and calls `tag.yml`, which tags the + merge, dispatches `release.yml`, and opens the pull request into `main`; no + person merges a cut. `tag.yml` still tags a person's merge of a cut, and + accepts the run that verified a merged head's tree without waiting for the + merge's own. - Decision regions (SPEC.md §17.12, `PF-24`, UOR-Foundation/PrismPM#605; no new diagnostic code; changes the language-1.2 identity). The runtime gains a sixth native module, `LexLeanRuntime.Regions`: a checker of local box diff --git a/README.md b/README.md index db42958671..70457345f5 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,13 @@ +
+ LexLean + +

One controlled language in. A canonical paper, a kernel checked Lean 4 program, and a certified Rust package out.

+
+ # LexLean +[Spec](SPEC.md) · [Conformance](CONFORMANCE.md) · [Diagnostics](ERRORS.md) · [Evidence](VERIFICATION.md) · [Changelog](CHANGELOG.md) · [MNIST model](https://github.com/UOR-Foundation/MNIST) + A closed-lexicon LaTeX-to-Lean 4 compiler whose canonical document and prose-free Lean program are generated from one semantic representation. The complete normative contract is [SPEC.md](SPEC.md) (`LEXLEAN-SPEC-1`). Every capability below is a claim in [`model/ids.toml`](model/ids.toml), carried at honesty level `build`: constructed here and validated against its oracle by the test named `conformance_`. The generated register is [CONFORMANCE.md](CONFORMANCE.md); the closed diagnostic registry is [ERRORS.md](ERRORS.md); the falsifiability evidence is in [VERIFICATION.md](VERIFICATION.md). diff --git a/SPEC.md b/SPEC.md index c2d7da9cc7..5424e11069 100644 --- a/SPEC.md +++ b/SPEC.md @@ -284,6 +284,8 @@ The completed repository MUST have this layout. Additional files are allowed onl │ └── workflows/ │ ├── ci.yml │ └── reproducibility.yml +├── assets/ +│ └── lexlean-logo.svg ├── AGENTS.md ├── CONFORMANCE.md ├── ERRORS.md @@ -693,7 +695,7 @@ Its image MUST install the pinned Rust and Lean toolchains at build, so that not **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. -**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`, 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. Merging that pull request is the decision to release. `tag.yml` runs on every push to a release line and stops at once unless the push changed the workspace version from its first parent's to one with no tag and a `## X.Y.Z` changelog entry; then it waits for this push's run of `ci.yml`, and only when that run passed 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 enables auto-merge, since the line contains `main` and the merge lands that tree. A tag pushed by hand starts `release.yml` itself; nothing here changes what a release publishes or what evidence it requires. +**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. @@ -713,7 +715,7 @@ The Intel host factory is separate from the normative BDD and Atlas partitions a `reproducibility.yml` MUST perform two builds in distinct absolute directories and compare every platform-independent artifact byte-for-byte after path normalization. -`regenerate.yml` is not part of the gate: it runs the write recipes of §9.2 on runners, so that a change which moves committed output is regenerated from a clean checkout rather than on a workstation. A push to a branch under `regenerate/`, or a `workflow_dispatch` on a ref, starts three jobs at once, each from its own clean checkout of that commit: `production-export-write`; `verify-write` over every example but UOR Atlas, or over every example when the branch is under `regenerate/atlas/` or the `atlas` input is set; and `golden-write fixtures-write calculus-write model-write`. They verify with the profile of the `examples` leg, which changes no byte of what is written (§22.11). Each returns what its recipes wrote as a binary patch, and the job `combine` applies the patches in turn to a clean checkout of the same commit, failing when two write one path. The job `finish` then applies that tree and writes what follows from it: the counts the bootstrap count cases assert, by `cargo xtask counts --write` over runs of the parts of `.github/bdd-parts.json` that hold a `crate::counts!` check under `LEXLEAN_COUNTS=fast`; the model documents, by `validate-model --write`; and the row of `tests/stack-bounds.json` of each recursive package of the bootstrap and stdlib exports that has none (`PD-08`), measured by a whole run under `LEXLEAN_MEASURE_STACK=all` of the case whose source names the package's root, which also checks the counts just written, while a row of a package no longer exported is dropped. It returns the result as one patch with the list of its paths, the counts the writer reported, and the commit it applies to. Its writers read the repository and write nothing to it (`contents: read`, no persisted credentials). The job `deliver` then commits the patch on the commit it was made from and pushes that commit, as a fast-forward, to the branch the commit heads: the head branch of the one open pull request of this repository whose head is the commit, or the branch a caller (`cut.yml`) names; a branch pushed again in the meantime rejects the push and is left alone. It dispatches `ci.yml` on that branch and deletes the `regenerate/` branch that started the run when that branch still names the commit. With no such pull request it pushes nothing and the patch stays the run's artifact. The delivered commit is reviewed in its pull request like any other written output (§28.3), and the gate then verifies the tree that carries it. +`regenerate.yml` is not part of the gate: it runs the write recipes of §9.2 on runners, so that a change which moves committed output is regenerated from a clean checkout rather than on a workstation. A push to a branch under `regenerate/`, or a `workflow_dispatch` on a ref, starts three jobs at once, each from its own clean checkout of that commit: `production-export-write`; `verify-write` over every example but UOR Atlas, or over every example when the branch is under `regenerate/atlas/` or the `atlas` input is set; and `golden-write fixtures-write calculus-write model-write`. They verify with the profile of the `examples` leg, which changes no byte of what is written (§22.11). Each returns what its recipes wrote as a binary patch, and the job `combine` applies the patches in turn to a clean checkout of the same commit, failing when two write one path. The job `finish` then applies that tree and writes what follows from it: the counts the bootstrap count cases assert, by `cargo xtask counts --write` over runs of the parts of `.github/bdd-parts.json` that hold a `crate::counts!` check under `LEXLEAN_COUNTS=fast`; the model documents, by `validate-model --write`; and the row of `tests/stack-bounds.json` of each recursive package of the bootstrap and stdlib exports that has none (`PD-08`), measured by a whole run under `LEXLEAN_MEASURE_STACK=all` of the case whose source names the package's root, which also checks the counts just written, while a row of a package no longer exported is dropped. It returns the result as one patch with the list of its paths, the counts the writer reported, and the commit it applies to. Its writers read the repository and write nothing to it (`contents: read`, no persisted credentials). The job `deliver` then commits the patch on the commit it was made from and pushes that commit, as a fast-forward, to the branch the commit heads: the head branch of the one open pull request of this repository whose head is the commit, or the branch a caller (`cut.yml`) names; a branch pushed again in the meantime rejects the push and is left alone. It dispatches `ci.yml` on that branch and deletes the `regenerate/` branch that started the run when that branch still names the commit. When the patch is empty and a caller named the branch, it dispatches `ci.yml` there all the same. With no such pull request it pushes nothing and the patch stays the run's artifact. The delivered commit is reviewed in its pull request like any other written output (§28.3), and the gate then verifies the tree that carries it. --- diff --git a/assets/lexlean-logo.png b/assets/lexlean-logo.png new file mode 100644 index 0000000000..1a50dc80fd Binary files /dev/null and b/assets/lexlean-logo.png differ diff --git a/assets/lexlean-logo.svg b/assets/lexlean-logo.svg new file mode 100644 index 0000000000..fb37c3fbd7 --- /dev/null +++ b/assets/lexlean-logo.svg @@ -0,0 +1,16 @@ + + LexLean + + + + + + + + + + LexLean + diff --git a/xtask/src/bump.rs b/xtask/src/bump.rs index be3ee8a24c..3099ddebe8 100644 --- a/xtask/src/bump.rs +++ b/xtask/src/bump.rs @@ -79,12 +79,12 @@ fn sites(old: &str, new: &str) -> Vec { format!("\"a {new} tree must refuse release"), 1, ), - // The unreleased entries become the release's (Keep a Changelog); the - // next landing opens a new `## Unreleased`. + // The unreleased entries become the release's (Keep a Changelog), under + // a fresh, empty `## Unreleased` that the next cut finds. site( "CHANGELOG.md", "\n## Unreleased\n".to_owned(), - format!("\n## {new}\n"), + format!("\n## Unreleased\n\n## {new}\n"), 1, ), ]