diff --git a/.claude/skills/upgrade-dependencies/SKILL.md b/.claude/skills/upgrade-dependencies/SKILL.md index 8a6a4fe..c270ae8 100644 --- a/.claude/skills/upgrade-dependencies/SKILL.md +++ b/.claude/skills/upgrade-dependencies/SKILL.md @@ -30,14 +30,17 @@ what to take. ## 2. One dependency at a time On `deps-YYYY-MM-DD`, from `main`, one commit per dependency, or per family -that moves together (`windows` and `windows-registry`): +that moves together. The windows-rs crates (`windows`, `windows-registry`) +are one family: one does not move without the other ([Lot 21](../../../docs/design/21-windows-rs-0100.md)). 1. **Read the upgrade path first**: the changelog, release notes or migration guide of every version between the locked one and the target, from the publisher — the crate's repository, docs.rs, the action's releases. Note each breaking change this code meets. 2. Raise the requirement in `Cargo.toml`, or the tag in the workflow, then - `cargo update -p `. + `cargo update -p `. A dependency that needs a newer Rust than + `rust-version` raises `rust-version` in the same commit; it is never held + back for that. 3. Fix each break **the way the guide says**: the new API, the replacement it names. Never: a lint silenced (`#[allow(deprecated)]` and the like), a `[patch]` or a fork, a version held below the target, the old code copied diff --git a/docs/design/20-build-chain.md b/docs/design/20-build-chain.md index 5b3817d..e5d97f7 100644 --- a/docs/design/20-build-chain.md +++ b/docs/design/20-build-chain.md @@ -1,7 +1,8 @@ # Lot 20 — The build chain, official and kept current -**Status: decided 2026-10-17; part 1 built the same day**, its attestation to -be seen at the next release. Taken while Lot 19's spike waits for an Office +**Status: decided and built 2026-10-17.** Seen the same day: Dependabot's +first PR, two crate patches, merged itself once CI had passed. Still to see: +an update that waits for the maintainer, and the first attested release. Taken while Lot 19's spike waits for an Office update. Two parts, in this order: Dependabot keeps current whatever the first part settles on. diff --git a/docs/design/21-windows-rs-0100.md b/docs/design/21-windows-rs-0100.md new file mode 100644 index 0000000..077edc3 --- /dev/null +++ b/docs/design/21-windows-rs-0100.md @@ -0,0 +1,46 @@ +# Lot 21 — Moving to windows-rs 0.100 + +**Status: proposed 2026-10-17, waiting for `windows` 0.100 on crates.io.** +windows-rs moved its smaller crates to 0.100.0 on 2026-09-03 (its release +74) and held back `windows` and `windows-sys` while it tests their new +metadata ([microsoft/windows-rs#4867](https://github.com/microsoft/windows-rs/issues/4867)). +The program uses `windows` 0.62 throughout and `windows-registry` 0.6; they +move together, once, following the `upgrade-dependencies` skill. + +## Why a lot of its own + +The 0.100 bindings come from the Windows SDK headers instead of the +Win32Metadata project, and the publisher lists what that breaks: + +- features and modules renamed after SDK headers (`Win32_*` become lowercase + header names): every feature in `Cargo.toml` and every import; +- signatures as the headers declare them: raw pointer and count parameters, + `BOOL` and `HRESULT` returned as such; +- generated enum and ownership types removed where the SDK has primitives — + `HLOCAL`, for one, no longer frees itself; +- record layouts as the headers lay them out. + +Nearly every `unsafe` call and its `// SAFETY:` comment is touched, so this is +the riskiest dependency change the program has had. + +## Until then + +`windows-registry` stays at 0.6. Tried on 2026-10-17: 0.100 builds with no +change to the code and adds about 1.5 KB, but brings a second generation of +`windows-result`, `windows-strings` and `windows-link` beside the ones +`windows` 0.62 uses, and needs Rust 1.95 where `rust-version` says 1.88 — +for nothing the program uses. Decided with the maintainer the same day: wait. + +## When `windows` 0.100 lands + +- Read the publisher's migration notes and the crates' documentation first. +- One commit per area of the program, each through `build.ps1 test`; no + workaround, as the skill says. `rust-version` follows the family's minimum. +- In the field, every path that calls Windows: detection and the presence + writer's wait, the games marked by hand, the GPU counters, the icon, menu + and notifications, the session end, the update and `purge`. +- The watcher measured at rest and in a game against 0.4.0. + +**Done when** the program builds on `windows` and `windows-registry` 0.100 +with no crate of the 0.62 generation left, every check passes, a field +session has exercised each path above, and the footprint is recorded. diff --git a/docs/design/README.md b/docs/design/README.md index f6a2a8f..340ccaf 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -30,7 +30,8 @@ the pages keep the history. | 17 | [A log that turns over each day](17-log-rotation.md) | done 2026-09-26; the zip's update path to see at the next release | | 18 | [When the game is gone and nobody is there](18-game-gone-nobody-there.md) | proposed, not decided | | 19 | [Starting from Windows' Startup list](19-startup-list.md) | proposed; a spike first | -| 20 | [The build chain, official and kept current](20-build-chain.md) | part 1 built 2026-10-17; Dependabot next | +| 20 | [The build chain, official and kept current](20-build-chain.md) | built 2026-10-17; the first wait and the first attested release to see | +| 21 | [Moving to windows-rs 0.100](21-windows-rs-0100.md) | proposed; waiting for `windows` 0.100 | Logging came before the icon, so the icon was written in the final log vocabulary; the windowless build came before it too, so the window and message