Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions .github/scripts/await-gate.sh
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,9 @@
# 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.
# so re-running the cut's failed jobs waits for it afresh. A run that waits
# for approval (`action_required`, as the `pull_request` runs a workflow-token
# push to the cut's branch start) never ran the gate and is passed over.
#
# Inputs, from the environment: REPO, HEAD_SHA, WAIT_MINUTES, FINAL. `gh`
# reads the runs and jobs (`actions: read`); the checkout is HEAD_SHA.
Expand All @@ -28,7 +30,7 @@ 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)\"" \
--jq "[.workflow_runs[] | select(.head_repository.full_name == \"$repo\") | select(.event == \"pull_request\" or .event == \"workflow_dispatch\") | select(.conclusion != \"action_required\")][0] // empty | \"\(.status) \(.conclusion) \(.html_url)\"" \
2>/dev/null || true)
case "$state" in
"completed success "*)
Expand Down
7 changes: 4 additions & 3 deletions .github/workflows/cut.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@
# git push origin release/vX.Y:refs/heads/cut/vX.Y.Z
#
# `version` moves every site of the workspace version to X.Y.Z
# (`cargo xtask bump-version`), the `## Unreleased` changelog entries becoming
# `## X.Y.Z`, commits that on the pushed commit, and opens the pull request
# (`cargo xtask bump-version`), the `## Unreleased` changelog entries and the
# fragments under `changes/` becoming `## X.Y.Z` (the fragments deleted),
# 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. `gate` and `gate-more`
Expand Down Expand Up @@ -90,7 +91,7 @@ jobs:
git -c user.name='github-actions[bot]' \
-c user.email='41898282+github-actions[bot]@users.noreply.github.com' \
commit --quiet -m "Cut LexLean $VERSION" \
-m "cargo xtask bump-version $VERSION: the workspace version, SPEC.md §2.3, RP-01, Cargo.lock, and the changelog's unreleased entries."
-m "cargo xtask bump-version $VERSION: the workspace version, SPEC.md §2.3, RP-01, Cargo.lock, and the changelog's unreleased entries and fragments."
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. 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."
Expand Down
6 changes: 6 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,12 @@ 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 records its change in a new file `changes/<slug>.md` (one
Keep a Changelog entry, Markdown with no `#` or `##` heading; the slug is
usually the branch name) and never edits CHANGELOG.md: the cut
(`cargo xtask bump-version`) folds every fragment, in file-name order, under
the release's heading and deletes them (SPEC.md §9.4). A shared
`## Unreleased` list made every landing conflict with every open pull request.
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.
Expand Down
4 changes: 3 additions & 1 deletion SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -697,7 +697,9 @@ 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` 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.
**Changelog fragments.** A pull request records its change as one new file `changes/<slug>.md` (a Keep a Changelog entry, Markdown with no `#` or `##` heading) and never edits `CHANGELOG.md`, which only a cut writes: pull requests that all edited the one `## Unreleased` list each conflicted with every other open one at every landing, and each re-merge restarted the gate. `cargo xtask validate-model` refuses a fragment the cut could not fold.

**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` section, whose entries and then the text of every changelog fragment `changes/<slug>.md` in file-name order become `## X.Y.Z` under a new empty `## Unreleased`, the fragments being deleted, and the workspace rows of `Cargo.lock`), refuses to write anything when a site does not read as it expects, a fragment is empty, holds a `#` or `##` heading or is not a `.md` file, or the version does not follow the workspace's, and puts every file back, the deleted fragments too, 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.

Expand Down
4 changes: 4 additions & 0 deletions changes/await-gate-approval-runs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
- `cut.yml`'s wait for the gate passes over runs waiting for approval
(`action_required`): the `pull_request` runs that the workflow-token push of
a cut's regenerated patch starts never run the gate, and the wait took one
as the gate's failure (SPEC.md §9.4).
9 changes: 9 additions & 0 deletions changes/changelog-fragments.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
- Changelog fragments (SPEC.md §9.4). A pull request records its change as a
new file `changes/<slug>.md` and no longer edits CHANGELOG.md, so a landing
no longer makes every open pull request conflict on the `## Unreleased`
list and restart its gate. `cargo xtask bump-version` folds the
`## Unreleased` entries and then every fragment, in file-name order, under
`## X.Y.Z`, leaves an empty `## Unreleased`, and deletes the fragments, all
or nothing. `cargo xtask validate-model` refuses a fragment that is empty,
holds a `#` or `##` heading, or is not a `.md` file, and the deferral audit
scans the fragments as it scans CHANGELOG.md.
1 change: 1 addition & 0 deletions xtask/src/audit.rs
Original file line number Diff line number Diff line change
Expand Up @@ -913,6 +913,7 @@ pub fn audit_deferral(root: &Path, model: &repo_model::Model) -> Result<(), Fail
"tooling",
".github",
".devcontainer",
crate::bump::FRAGMENTS,
],
&[
".rs",
Expand Down
Loading
Loading