canvas-pilot/docs/development/releases.md

288 lines
16 KiB
Markdown

# Release preparation
## Published prerelease: v0.10.0-rc.18
[Download v0.10.0-rc.18](https://proxy.dandaedre.com/gitea/idle-org/canvas-pilot/releases/tag/v0.10.0-rc.18)
was published on 2026-11-19 from annotated tag `v0.10.0-rc.18`, source commit
`171a9198b693fcce4111f3d88726984691c92754`. See the
[release notes](release-notes/v0.10.0-rc.18.md). This publication record does not
move the tag.
The prerelease contains 18 assets: four portable bundles, four canonical
cargo-binstall archives, four raw binaries, the artifact manifest and primary
checksums, `classic-themes.zip`, `video-game-themes.zip`, `language-pack.zip`, and
`EXTRAS-SHA256SUMS.txt`. The release fixes decorative canvas text at extreme zoom,
keeps precise canvas zoom responsive, and gives mouse positioning and scaling a
soft preference for quarter-pixel positions that place edges on whole pixels. Its
lockfile also replaces three yanked transitive package versions.
Every draft asset was downloaded before publication. Both checksum files verified
all generated payloads and supplemental packs, every archive passed an integrity
check, and the raw binaries were identified as ELF x86-64, PE x86-64, Mach-O arm64
and Mach-O x86-64. After publication, anonymous API access resolved the annotated
tag to the source commit above and all 18 public asset URLs returned HTTP 200. An
isolated cargo-binstall fetched the public Linux archive and installed a binary
identical to the published raw executable
(`b1fce938eb4a9ea0b6b9a760652f1c662c10f1c6a0456ca680d2e86a1d2fda84`).
rust_realease 0.1.6-rc.3 built Linux and Windows with Cross and both Apple targets
with the validated local Rust 1.100.0 image. The checked-in Apple image still has
Rust 1.93, which is too old for the locked CAD dependencies. Linux, Windows and
Apple ARM outputs were retained after the release command detached while the Apple
ARM container completed; Apple Intel was then built separately. The four output
hashes were registered against the same tagged commit and the release tool reused
them for its normal packaging, manifest and validation stages. Portable tree,
embedded-file hash and architecture checks passed for every target; both macOS
binaries also passed macOS 13.0 deployment-minimum, system-library, archive-layout
and checksum validation. Native Windows and macOS runtime acceptance remains
outstanding.
Formatting, both Clippy configurations, all required Rust test configurations,
rustdoc, all 33 Python checks, the theme-pack consistency check and the pinned
manual build passed before tagging. Whole-application line coverage is 91.69%.
The exact locked `cargo install` path also passed without yanked-package warnings.
No device writes were performed. Generated archives, credentials and build caches
are not committed to Git.
## Published prerelease: v0.10.0-rc.16
[Download v0.10.0-rc.16](https://proxy.dandaedre.com/gitea/idle-org/canvas-pilot/releases/tag/v0.10.0-rc.16)
was published on 2026-11-19 from annotated tag `v0.10.0-rc.16`, source commit
`72dc29837a3430da64351a922da1e6b4af9f72a1`. See the
[release notes](release-notes/v0.10.0-rc.16.md). Publication records after that
commit do not move the tag.
The prerelease contains 18 assets: four portable bundles, four canonical
cargo-binstall archives, four raw binaries, the artifact manifest and primary
checksums, `classic-themes.zip`, `video-game-themes.zip`, `language-pack.zip`, and
`EXTRAS-SHA256SUMS.txt`. The two theme collections contain the 17 distributed
example themes. The language bundle is the format-2, revision-1 Ukrainian/Bhojpuri
teaching example; both translations remain partial and unreviewed.
All draft assets were downloaded before publication. The primary checksum file
verified every generated payload and manifest, all archives passed integrity
checks, and the raw binaries were identified as ELF x86-64, PE x86-64, Mach-O
arm64 and Mach-O x86-64. The separately downloaded theme and language ZIPs matched
their extras checksum file and passed ZIP integrity checks. Anonymous API access
then confirmed the public prerelease and its exact tagged commit, and anonymous
downloads of all three pack ZIPs reproduced their recorded hashes. An isolated
cargo-binstall fetched the public Linux archive and installed a binary identical to
the published raw executable (`c3adf1a0e5c57b9d6a514d8f39b9a548569776dc438a17d2c03adafdcf9c1cb6`).
rust_realease 0.1.6-rc.3 built all four targets from a fresh work directory.
Portable tree, embedded-file hash and architecture checks passed for every target;
both macOS binaries also passed macOS 13.0 deployment-minimum, system-library,
archive-layout and checksum validation. The validated local Apple builder used
Rust 1.100.0. Native GUI runtime was not configured in the release tool, and no
compatible Windows or macOS runner was available, so native runtime acceptance
remains outstanding.
Formatting, both Clippy configurations, all required Rust test configurations,
rustdoc, all 33 Python checks, the theme-pack consistency check and the pinned
manual build passed before tagging. Whole-application line coverage is 91.65%.
No device writes were performed for this release. Generated archives, credentials
and build caches are not committed to Git.
## Earlier source checkpoint: v0.10.0-rc.1
Annotated tag `v0.10.0-rc.1` marks the first candidate for the 0.10 minor release.
See the [candidate notes](release-notes/v0.10.0-rc.1.md). This is a source checkpoint;
no binaries have been built or published for this candidate, and the tag has not
been pushed.
## Published release: v0.9.34
[Download v0.9.34](https://proxy.dandaedre.com/gitea/idle-org/canvas-pilot/releases/tag/v0.9.34)
was published on 2026-11-17 from annotated tag `v0.9.34`, source commit
`952f409e52b617f7ed21325347977acc19c82bd5`. The source changes, theme and language
pack files, and tag were pushed to Gitea. Publication records do not move the tag.
See the [release notes](release-notes/v0.9.34.md).
The release contains 24 assets: four portable bundles, four canonical cargo-binstall
archives, four raw binaries, the artifact manifest/checksums, and ten extras.
The extras include all four theme packs (Tokyo Night, Catppuccin Mocha, Detroit:
Become Human and Minecraft Overworld), `language-pack.zip`, extras checksums,
effective build configuration, compiler recipe, build instructions and the
release-tool patch. The language pack is the existing format-2, revision-1
Ukrainian/Bhojpuri teaching example; translations remain partial and unreviewed.
Theme ZIPs match their tracked manifests and include their attribution notices.
All 24 assets were downloaded and SHA-256 checked before publication and again
anonymously afterward. cargo-binstall retrieved all four targets; each installed
binary matched the built release artifact. The packaged Linux executable passed
an isolated GUI startup/render check with an empty log. Portable tree/hash and
architecture checks passed for all targets; both macOS targets also passed macOS
13.0 deployment-minimum and system-library checks. Native Windows/macOS runtime
acceptance remains outstanding.
Formatting, both Clippy configurations, all required Rust test configurations,
rustdoc, all 27 Python checks and the pinned manual build passed. Whole-application
line coverage is 92.14%. The source tests were reused for the upload step, which
reused the completed builds for the exact tagged commit. No device writes were
performed for this release.
Packaging used the same locally patched rust_realease 0.1.6-rc.3 and immutable
Apple compiler image as v0.9.18 below. Linux/Windows used Rust 1.102.0-nightly
(`5df8c02af`, 2026-11-16), and macOS used Rust 1.100.0. Rebuild from the clean tag
using the attached `BUILDING-v0.9.34.md`, `rust-release-v0.9.34.toml`, compiler recipe
and release-tool patch. Generated archives, credentials and build caches are not
committed to Git.
## Previous release: v0.9.18
[Download v0.9.18](https://proxy.dandaedre.com/gitea/idle-org/canvas-pilot/releases/tag/v0.9.18)
was published on 2026-11-17 from annotated tag `v0.9.18`, source commit
`f3761206a8b901eb934f4f8fcb5c655d851e0173`. Publication records after that commit do
not move the tag. See the [release notes](release-notes/v0.9.18.md).
The release contains 20 assets: four portable bundles, four canonical cargo-binstall
archives, four raw binaries, the artifact manifest/checksums, and six extras:
`language-pack.zip`, its accompanying extras checksums, effective configuration,
compiler recipe, build instructions and the release-tool patch. The language pack
is the unchanged format-2, revision-1 Ukrainian/Bhojpuri teaching pack; both
translations are partial and unreviewed. All 20 assets were downloaded and
SHA-256 checked before publication and again anonymously afterward. cargo-binstall
retrieved all four targets; each installed binary matched its release artifact.
All four builds and archive checks passed. The Linux binary passed an isolated GUI
startup/render check with an empty log. Both macOS targets passed architecture,
macOS 13.0 deployment minimum and system-library validation. Native Windows/macOS
runtime acceptance remains outstanding. Source validation passed 464 default and
458 tests in each restricted configuration, Clippy, rustdoc, formatting, all 26
Python tests and the pinned manual build; whole-application coverage is 91.70%.
Linux/Windows used Rust 1.102.0-nightly (`5df8c02af`, 2026-11-16); macOS used the
existing compiler recipe with Rust 1.100.0. The installed rust_realease rc.2 omitted
portable bundles, so rc.3 was built locally. Its bundle checker did not recognize
Mach-O and its Apple validator rejected named bundles. The attached patch adds
architecture/executable checks and applies the existing deployment/dependency
validator to executable entries in verified Apple ZIPs. The temporary tool passed
66 tests (3 pre-existing ignored tests). Application source/binaries were unchanged
by the packaging fix. Rebuild instructions, patch and effective image digest are
attached; no globally installed release tool was replaced.
## Previous milestone: v0.8.0
[Download v0.8.0](https://proxy.dandaedre.com/gitea/idle-org/canvas-pilot/releases/tag/v0.8.0).
The annotated tag identifies source commit `eb82dc7cc91105793d2d31552da71763d2218df5`;
subsequent publication documentation does not move that tag. The release has 21
assets: four portable bundles, four canonical cargo-binstall archives, four raw
binaries, the artifact manifest/checksums, and seven manual/template/build extras.
The [release notes](release-notes/v0.8.0.md) describe compatibility and downloads.
All four builds passed. Linux GUI startup/render passed with isolated settings.
Both macOS binaries passed Mach-O architecture, minimum macOS 13.0, system-library,
archive-layout and checksum checks. Native Windows/macOS runtime testing was not
available. All 21 assets were downloaded and hash-checked before publication and
again anonymously after publication. cargo-binstall retrieved all four targets
from the public release; each installed binary matched the built artifact SHA-256.
### Required macOS compiler override
The original pinned SDK image contains Rust 1.93, but the locked CAD dependencies
require Rust 1.95 or newer. The first real release build exposed this mismatch;
the earlier dry run could not detect it. v0.8.0 keeps its application source and
lockfile unchanged and uses Rust 1.100.0 for all targets.
The [compiler recipe](../../scripts/release/Containerfile.apple) extends the original
immutable image with Rust 1.100.0 and both Apple target libraries. Its built digest,
Cross image digests and validation boundaries are in the release's
`build-provenance.json`. The macOS configuration used is attached as
`rust-release-v0.8.0.toml`; the image is locally built, not a public registry upload.
For a fresh build host, download `Containerfile.apple`, `BUILDING-v0.8.0.md` and
`rust-release-v0.8.0.toml` from the release. Build the recipe, then set the supplied
configuration's `build.apple.image` to your local image's immutable digest, as
explained in the build instructions. A rebuilt image's digest can differ because
of build timestamps. From a clean tagged checkout:
```sh
rust_realease . --package canvas-pilot --tag v0.8.0 --dry-run --config /path/to/rust-release-v0.8.0.toml
rust_realease . --package canvas-pilot --tag v0.8.0 --compile-only --artifact-format both --config /path/to/rust-release-v0.8.0.toml
```
Keep default features enabled for vendor formats. The second command builds and
packages all targets without publishing. For this publication, the successful
Linux/Windows binaries were retained after the first macOS failure; macOS was
rerun with the compatible compiler. Retained binaries were packaged to the same
configured layouts with entry/hash/permission/architecture verification. The
combined artifact manifest records this rather than claiming one uninterrupted run.
Release assets were uploaded as a draft using the authorized token, verified, then
published through Gitea. Credentials and generated archives remain outside Git.
Do not replace existing public assets or move the release tag for future fixes;
prepare a new version instead.
## Packaging configuration
`rust-release.toml` configures portable Windows and Linux builds through Cross and
Apple Silicon/Intel macOS 13+ builds through the pinned cargo-zigbuild container.
Run release preparation from the repository root with the separately installed
`rust_realease` tool; the configuration packages the application, icons,
launcher helper and MIT notices. No FFprobe is needed. This is a manually invoked
workflow, separate from Jenkins; keep generated archives and binaries untracked.
Review bundles on their target platforms before publishing a release.
```sh
# Inspect the release plan without publishing.
rust_realease . --package canvas-pilot --dry-run --stop-after inspect
```
## Lightweight readiness check
```sh
rust_realease . --package canvas-pilot --dry-run
```
Unlike `--stop-after inspect`, the full dry run checks required metadata, build
prerequisites and the release tag. It does not compile, edit manifests, create tags
or publish. An exit failure for a missing tag is expected before release preparation.
`--compile-only` is **not** a lightweight check: it runs the actual builds and packages
artifacts. Run it later on a capable build host:
```sh
rust_realease . --package canvas-pilot --compile-only
```
### Historical readiness audit — 2026-11-16 (before the milestone)
Checked with `rust_realease 0.1.6-rc.3`, without compiling or publishing:
| Check | Result |
| --- | --- |
| Package/version and target plan | `canvas-pilot` 0.7.0; Linux, Windows, Apple Silicon and Intel macOS |
| Required cargo-binstall metadata | Added; matches the canonical `.tgz` archive layout |
| Portable bundle inputs | Icons, launcher scripts, MIT license and standalone quick-start file present |
| Cargo manifest/lock | Locked offline metadata inspection succeeds |
| Host prerequisites | Cross, cargo-binstall and a working Podman backend available |
| Apple image | Pinned registry manifest exists and its SHA-256 matches |
| Full dry run after metadata repair | Only reported prerequisite failure: missing `v0.7.0` tag |
No release tag was created. Choose the intended release version, commit the final
sources, then explicitly prepare its matching tag on that commit when authorizing
a release. A publishing run requires a clean checkout. Use the configured Gitea
token environment variable or the tool's `--token-file` option; keep credentials
outside Git. No authenticated release creation/upload was exercised by this audit.
This establishes configuration readiness, not successful cross-platform binaries.
Cross compilation, linker/SDK compatibility, packaged application startup and
post-upload cargo-binstall verification still require the actual build/release
workflow. Prior native tests are recorded in the handoff. The pinned Apple image
was not cached locally at this audit; its compressed layers total about 1,440 MiB
before any layer reuse. Image pulls and four target builds should run on a capable
host rather than as a quick check on an underpowered laptop.
The portable archive uses `docs/canvas-pilot/portable-quickstart.txt` instead of the
repository README, so it does not depend on unbundled relative documentation links.
The canonical cargo-binstall archives remain separate from the named portable bundles.
For a local launcher after `cargo build --release --locked`:
```sh
python3 scripts/create-desktop-launcher.py canvas-pilot --binary "$PWD/target/release/canvas-pilot" --output "$HOME/.local/share"
```
On macOS add `--platform macos --output "$HOME/Applications"`. Existing launchers
are never overwritten. Regenerate icons with `scripts/build-icons.py` (ImageMagick).
Artwork provenance is in `icon-prompts.json`.