diff --git a/.github/scripts/await-gate.sh b/.github/scripts/await-gate.sh index 262bcb0d9d..1f9469d003 100755 --- a/.github/scripts/await-gate.sh +++ b/.github/scripts/await-gate.sh @@ -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. @@ -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 "*) diff --git a/.github/workflows/cut.yml b/.github/workflows/cut.yml index 3b3c1ed55c..cbbc65c7a5 100644 --- a/.github/workflows/cut.yml +++ b/.github/workflows/cut.yml @@ -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` @@ -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." diff --git a/AGENTS.md b/AGENTS.md index 377139945c..229580f5c0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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/.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. diff --git a/SPEC.md b/SPEC.md index 6db6ed089b..ff3aa562c9 100644 --- a/SPEC.md +++ b/SPEC.md @@ -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/.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/.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. diff --git a/changes/await-gate-approval-runs.md b/changes/await-gate-approval-runs.md new file mode 100644 index 0000000000..adf891ac07 --- /dev/null +++ b/changes/await-gate-approval-runs.md @@ -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). diff --git a/changes/changelog-fragments.md b/changes/changelog-fragments.md new file mode 100644 index 0000000000..9204abd2e2 --- /dev/null +++ b/changes/changelog-fragments.md @@ -0,0 +1,9 @@ +- Changelog fragments (SPEC.md §9.4). A pull request records its change as a + new file `changes/.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. diff --git a/xtask/src/audit.rs b/xtask/src/audit.rs index f24a92b1ca..862d60dd08 100644 --- a/xtask/src/audit.rs +++ b/xtask/src/audit.rs @@ -913,6 +913,7 @@ pub fn audit_deferral(root: &Path, model: &repo_model::Model) -> Result<(), Fail "tooling", ".github", ".devcontainer", + crate::bump::FRAGMENTS, ], &[ ".rs", diff --git a/xtask/src/bump.rs b/xtask/src/bump.rs index 3099ddebe8..084e5250a0 100644 --- a/xtask/src/bump.rs +++ b/xtask/src/bump.rs @@ -6,6 +6,13 @@ //! by `## Unreleased` in CHANGELOG.md until a release takes it. A cut moved each //! by hand; this moves all of them or none, and refuses when a site does not //! read as it expects, so a site that drifted is named rather than skipped. +//! +//! A pull request records its change as a fragment, `changes/.md`, and +//! never edits CHANGELOG.md: every pull request editing the one `## Unreleased` +//! list made each landing conflict with every open pull request, and each +//! re-merge restarted the gate. The cut folds the entries already under +//! `## Unreleased`, then every fragment in file-name order, into `## X.Y.Z` +//! under a fresh, empty `## Unreleased`, and deletes the fragments. //! What the version moves downstream (the lock's workspace rows, and every //! build oracle's `compiler.version`) is written by `cargo update --workspace` //! here and by the write recipes of `regenerate.yml` after it. @@ -79,17 +86,200 @@ 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), under - // a fresh, empty `## Unreleased` that the next cut finds. - site( - "CHANGELOG.md", - "\n## Unreleased\n".to_owned(), - format!("\n## Unreleased\n\n## {new}\n"), - 1, - ), ] } +/// The directory of changelog fragments, one `.md` per change. +pub const FRAGMENTS: &str = "changes"; +const CHANGELOG: &str = "CHANGELOG.md"; +const UNRELEASED: &str = "\n## Unreleased\n"; + +/// Why a fragment cannot be folded: it must hold an entry, a heading of level +/// one or two would open a section of CHANGELOG.md of its own, and a code +/// fence left open would swallow every section after it. Fences and ATX +/// headings are read as CommonMark does: up to three spaces of indentation, +/// a fence of three or more backticks or tildes closed only by a run of the +/// same character at least as long with nothing after it. +fn fragment_fault(text: &str) -> Option<&'static str> { + if text.trim().is_empty() { + return Some("is empty"); + } + // An indentation of at most three spaces, and the rest of the line. + fn block(line: &str) -> Option<&str> { + let rest = line.trim_start_matches(' '); + (line.len() - rest.len() <= 3).then_some(rest) + } + fn fence_run(rest: &str) -> Option<(char, usize)> { + let marker = rest.chars().next().filter(|c| *c == '`' || *c == '~')?; + let length = rest.chars().take_while(|c| *c == marker).count(); + (length >= 3).then_some((marker, length)) + } + let mut open: Option<(char, usize)> = None; + for line in text.lines() { + let Some(rest) = block(line) else { continue }; + match open { + Some((marker, length)) => { + if let Some((close, run)) = fence_run(rest) { + if close == marker && run >= length && rest[run..].trim().is_empty() { + open = None; + } + } + } + None => { + if let Some((marker, length)) = fence_run(rest) { + // A backtick fence's info string holds no backtick. + if marker != '`' || !rest[length..].contains('`') { + open = Some((marker, length)); + continue; + } + } + let hashes = rest.chars().take_while(|c| *c == '#').count(); + let after = &rest[hashes..]; + if (1..=2).contains(&hashes) + && (after.is_empty() || after.starts_with(' ') || after.starts_with('\t')) + { + return Some("holds a `#` or `##` heading"); + } + } + } + } + open.map(|_| "leaves a code fence open") +} + +/// Every fragment under `changes/`, in file-name order, as (published path, +/// text). A missing directory has none. Anything but `*.md` (and `.gitkeep`) +/// is refused, so a misnamed fragment is not silently left out of a release. +pub fn fragments(root: &Path) -> Result, Vec> { + let directory = root.join(FRAGMENTS); + let entries = match std::fs::read_dir(&directory) { + Ok(entries) => entries, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()), + Err(error) => return Err(vec![format!("{FRAGMENTS}/: {error}")]), + }; + let mut names = Vec::new(); + let mut faults = Vec::new(); + for entry in entries { + match entry { + Ok(entry) => names.push(entry.file_name().to_string_lossy().into_owned()), + Err(error) => faults.push(format!("{FRAGMENTS}/: {error}")), + } + } + names.sort(); + let mut found = Vec::new(); + for name in names { + let path = format!("{FRAGMENTS}/{name}"); + if name == ".gitkeep" { + continue; + } + if !name.ends_with(".md") || !root.join(&path).is_file() { + faults.push(format!("{path}: a fragment is a file `.md`")); + continue; + } + match std::fs::read_to_string(root.join(&path)) { + Ok(text) => match fragment_fault(&text) { + Some(fault) => faults.push(format!("{path}: {fault}")), + None => found.push((path, text)), + }, + Err(error) => faults.push(format!("{path}: {error}")), + } + } + if faults.is_empty() { + Ok(found) + } else { + Err(faults) + } +} + +/// `validate-model`: every fragment folds, so a bad one fails its own pull +/// request rather than the cut. +pub fn check_fragments(root: &Path) -> Result<(), Fail> { + match fragments(root) { + Ok(found) => { + println!( + "changelog fragments: {} fold under the next release", + found.len() + ); + Ok(()) + } + Err(faults) => Err(format!( + "§9.4: the changelog fragments do not fold:\n {}", + faults.join("\n ") + ) + .into()), + } +} + +/// CHANGELOG.md with its unreleased entries, then each fragment's text in the +/// order given, under `## {version}`, below a fresh, empty `## Unreleased`. +fn fold(changelog: &str, version: &str, fragments: &[(String, String)]) -> Result { + let found = changelog.matches(UNRELEASED).count(); + if found != 1 { + return Err(format!( + "{CHANGELOG}: {UNRELEASED:?} occurs {found} times, not 1" + )); + } + let (head, rest) = changelog.split_once(UNRELEASED).expect("counted once"); + let (entries, tail) = match rest.find("\n## ") { + Some(end) => rest.split_at(end), + None => (rest, ""), + }; + let pieces: Vec<&str> = std::iter::once(entries.trim()) + .chain(fragments.iter().map(|(_, text)| text.trim())) + .filter(|piece| !piece.is_empty()) + .collect(); + let mut out = format!("{head}{UNRELEASED}\n## {version}\n"); + if !pieces.is_empty() { + out.push('\n'); + out.push_str(&pieces.join("\n\n")); + out.push('\n'); + } + out.push_str(tail); + Ok(out) +} + +/// Write `texts`, delete `removed`, then run `last`; if any step fails, put +/// back every file this touched (each of `texts`, each removed fragment, and +/// `also`), so the whole move is all or nothing. +fn commit( + root: &Path, + texts: &[(String, String)], + removed: &[String], + also: &[&str], + last: impl FnOnce() -> Result<(), String>, +) -> Result<(), Fail> { + let originals: Vec<(&str, Vec)> = texts + .iter() + .map(|(path, _)| path.as_str()) + .chain(removed.iter().map(String::as_str)) + .chain(also.iter().copied()) + .map(|path| std::fs::read(root.join(path)).map(|bytes| (path, bytes))) + .collect::>()?; + let restore = |cause: String| -> Fail { + if !removed.is_empty() { + if let Err(error) = std::fs::create_dir_all(root.join(FRAGMENTS)) { + return format!("{cause}; restoring {FRAGMENTS}/ failed too: {error}").into(); + } + } + for (path, bytes) in &originals { + if let Err(error) = std::fs::write(root.join(path), bytes) { + return format!("{cause}; restoring {path} failed too: {error}").into(); + } + } + format!("{cause}; every file is restored").into() + }; + for (path, text) in texts { + if let Err(error) = std::fs::write(root.join(path), text) { + return Err(restore(format!("writing {path}: {error}"))); + } + } + for path in removed { + if let Err(error) = std::fs::remove_file(root.join(path)) { + return Err(restore(format!("deleting {path}: {error}"))); + } + } + last().map_err(restore) +} + /// Move every site from the workspace version to `new`, then the lock's /// workspace rows. Nothing is written unless every site reads as expected. pub fn bump_version(root: &Path, arguments: &[String]) -> Result<(), Fail> { @@ -105,13 +295,16 @@ pub fn bump_version(root: &Path, arguments: &[String]) -> Result<(), Fail> { if to <= from { return Err(format!("§2.3: `{new}` does not follow `{old}`").into()); } - let mut texts: Vec<(&'static str, String)> = Vec::new(); + let mut texts: Vec<(String, String)> = Vec::new(); let mut unmet = Vec::new(); for site in sites(&old, new) { let index = match texts.iter().position(|(path, _)| *path == site.path) { Some(index) => index, None => { - texts.push((site.path, std::fs::read_to_string(root.join(site.path))?)); + texts.push(( + site.path.to_owned(), + std::fs::read_to_string(root.join(site.path))?, + )); texts.len() - 1 } }; @@ -126,6 +319,21 @@ pub fn bump_version(root: &Path, arguments: &[String]) -> Result<(), Fail> { )); } } + let fragments = match fragments(root) { + Ok(found) => found, + Err(faults) => { + unmet.extend(faults); + Vec::new() + } + }; + match fold( + &std::fs::read_to_string(root.join(CHANGELOG))?, + new, + &fragments, + ) { + Ok(text) => texts.push((CHANGELOG.to_owned(), text)), + Err(fault) => unmet.push(fault), + } if !unmet.is_empty() { return Err(format!( "bump-version {old} -> {new} wrote nothing; the sites do not read as expected:\n {}", @@ -134,54 +342,162 @@ pub fn bump_version(root: &Path, arguments: &[String]) -> Result<(), Fail> { .into()); } // The lock is moved last and may fail; on failure every file this wrote, - // and the lock, are put back, so the command is all or nothing. - let originals: Vec<(&str, Vec)> = texts - .iter() - .map(|(path, _)| *path) - .chain(std::iter::once("Cargo.lock")) - .map(|path| std::fs::read(root.join(path)).map(|bytes| (path, bytes))) - .collect::>()?; - let restore = |cause: String| -> Fail { - for (path, bytes) in &originals { - if let Err(error) = std::fs::write(root.join(path), bytes) { - return format!("{cause}; restoring {path} failed too: {error}").into(); - } - } - format!("{cause}; every file is restored").into() - }; - for (path, text) in &texts { - if let Err(error) = std::fs::write(root.join(path), text) { - return Err(restore(format!("writing {path}: {error}"))); - } - } - let cargo = std::env::var("CARGO").unwrap_or_else(|_| "cargo".to_owned()); - match std::process::Command::new(cargo) - .current_dir(root) - .args(["update", "--workspace", "--offline"]) - .status() - { - Ok(status) if status.success() => {} - Ok(status) => { - return Err(restore(format!( + // every fragment it deleted, and the lock are put back. + let removed: Vec = fragments.into_iter().map(|(path, _)| path).collect(); + commit(root, &texts, &removed, &["Cargo.lock"], || { + let cargo = std::env::var("CARGO").unwrap_or_else(|_| "cargo".to_owned()); + match std::process::Command::new(cargo) + .current_dir(root) + .args(["update", "--workspace", "--offline"]) + .status() + { + Ok(status) if status.success() => Ok(()), + Ok(status) => Err(format!( "cargo update --workspace --offline exited {status}" - ))) - } - Err(error) => { - return Err(restore(format!( + )), + Err(error) => Err(format!( "cargo update --workspace --offline did not run: {error}" - ))) + )), } - } + })?; println!( - "bump-version: {old} -> {new} in {} files and Cargo.lock", - texts.len() + "bump-version: {old} -> {new} in {} files and Cargo.lock; {} changelog fragments folded", + texts.len(), + removed.len() ); Ok(()) } #[cfg(test)] mod tests { - use super::parse; + use super::{commit, fold, fragment_fault, fragments, parse, CHANGELOG}; + + const BEFORE: &str = + "# Changelog\n\nPreamble.\n\n## Unreleased\n\n- Existing entry.\n\n## 0.4.0\n\n- Old.\n"; + const AFTER: &str = "# Changelog\n\nPreamble.\n\n## Unreleased\n\n## 0.4.2\n\n- Existing entry.\n\n- Alpha.\n More of alpha.\n\n- Beta.\n\n## 0.4.0\n\n- Old.\n"; + + fn tree() -> tempfile::TempDir { + let dir = tempfile::tempdir().expect("tempdir"); + std::fs::write(dir.path().join(CHANGELOG), BEFORE).expect("write"); + std::fs::create_dir(dir.path().join("changes")).expect("mkdir"); + // Written out of name order: the fold orders by name, not by creation. + std::fs::write(dir.path().join("changes/b-beta.md"), "- Beta.\n").expect("write"); + std::fs::write( + dir.path().join("changes/a-alpha.md"), + "\n- Alpha.\n More of alpha.\n\n", + ) + .expect("write"); + dir + } + + fn fold_tree(root: &std::path::Path, last: Result<(), String>) -> Result<(), crate::Fail> { + let found = fragments(root).expect("fragments fold"); + let text = fold( + &std::fs::read_to_string(root.join(CHANGELOG)).unwrap(), + "0.4.2", + &found, + ) + .expect("fold"); + let removed: Vec = found.into_iter().map(|(path, _)| path).collect(); + commit(root, &[(CHANGELOG.to_owned(), text)], &removed, &[], || { + last + }) + } + + #[test] + fn the_cut_folds_unreleased_entries_then_fragments_by_name() { + let dir = tree(); + fold_tree(dir.path(), Ok(())).expect("the fold lands"); + assert_eq!( + std::fs::read_to_string(dir.path().join(CHANGELOG)).unwrap(), + AFTER + ); + assert_eq!( + std::fs::read_dir(dir.path().join("changes")) + .unwrap() + .count(), + 0, + "the fragments are gone" + ); + // The next cut finds the empty `## Unreleased` and moves nothing into it. + assert_eq!( + fold(AFTER, "0.4.3", &[]).unwrap(), + AFTER.replace("## Unreleased\n\n", "## Unreleased\n\n## 0.4.3\n\n") + ); + } + + #[test] + fn a_failed_cut_restores_the_changelog_and_every_fragment() { + let dir = tree(); + let error = fold_tree(dir.path(), Err("lock".to_owned())).expect_err("the last step fails"); + assert!( + error.to_string().contains("every file is restored"), + "{error}" + ); + assert_eq!( + std::fs::read_to_string(dir.path().join(CHANGELOG)).unwrap(), + BEFORE + ); + assert_eq!( + std::fs::read_to_string(dir.path().join("changes/b-beta.md")).unwrap(), + "- Beta.\n" + ); + assert!(dir.path().join("changes/a-alpha.md").is_file()); + } + + #[test] + fn fragments_hold_an_entry_and_no_section_heading() { + let dir = tempfile::tempdir().expect("tempdir"); + assert_eq!( + fragments(dir.path()), + Ok(Vec::new()), + "no directory, no fragments" + ); + let changes = dir.path().join("changes"); + std::fs::create_dir(&changes).unwrap(); + std::fs::write(changes.join(".gitkeep"), "").unwrap(); + std::fs::write( + changes.join("fine.md"), + "- Fine.\n\n```\n## inside a fence\n```\n### Sub\n", + ) + .unwrap(); + assert_eq!(fragments(dir.path()).map(|found| found.len()), Ok(1)); + std::fs::write(changes.join("empty.md"), " \n\n").unwrap(); + std::fs::write(changes.join("heading.md"), "## 0.9.0\n- Smuggled.\n").unwrap(); + std::fs::write(changes.join("typo.txt"), "- Lost.\n").unwrap(); + let faults = fragments(dir.path()).expect_err("three faults"); + assert_eq!(faults.len(), 3, "{faults:?}"); + assert!(faults[0].starts_with("changes/empty.md")); + assert!(faults[1].starts_with("changes/heading.md")); + assert!(faults[2].starts_with("changes/typo.txt")); + for (text, fault) in [ + ("- Entry.\n```\n## 0.9.0\n", "leaves a code fence open"), + ( + "- Entry.\n````\n```\n## 0.9.0\n", + "leaves a code fence open", + ), + ( + "- Entry.\n````\n```\n````\n ## 0.9.0\n", + "holds a `#` or `##` heading", + ), + ("- Entry.\n ## 0.9.0\n", "holds a `#` or `##` heading"), + ("- Entry.\n~~~\n## x\n```\n", "leaves a code fence open"), + ] { + assert_eq!(fragment_fault(text), Some(fault), "{text:?}"); + } + for text in [ + "- Entry.\n````\n```\n## inside\n```\n````\n", + "- Entry.\n~~~ text\n## inside\n~~~\n", + "- Entry.\n ## indented code, not a heading\n", + "- Entry.\n#hashtag, not a heading\n### Sub\n", + ] { + assert_eq!(fragment_fault(text), None, "{text:?}"); + } + assert!( + fold("# Changelog\n", "0.4.2", &[]).is_err(), + "no `## Unreleased` refuses" + ); + } #[test] fn versions_are_three_plain_numbers() { diff --git a/xtask/src/codegen.rs b/xtask/src/codegen.rs index 83ef3a5615..f421c6403c 100644 --- a/xtask/src/codegen.rs +++ b/xtask/src/codegen.rs @@ -68,6 +68,7 @@ pub fn check_model(root: &Path, write: bool) -> Result<(), Fail> { crate::audit::audit_production_exhaustive(root)?; crate::audit::audit_classifications(root)?; crate::audit::audit_oracle_isolation(root)?; + crate::bump::check_fragments(root)?; println!( "validate-model: documents current, {} ids, {} codes, meta-gate and audits clean (R1)", model.ids.id.len(),