* File format families: drawings share the design format's versioning (#3890) The format code works for a family of files: its own tag, its own numbers and its own folder of change files, with one reading of a file's format, one refusal of a file a newer build saved and one upgrade for every family. Designs (solidcraft/N) are one family and keep everything they had: FORMAT and FORMATS are as they were, and pending_names, format_string, version_of and read mean what they did. Drawings (solidcraft-drawing/N) are the other, with format 1 as their first record and each later change one file in crates/doc/src/drawing/format/pending/, as design changes are. Nothing saved changes. A design tag never reads as a drawing's or the other way round, and a file that names no format is a design from before format strings, never a drawing. Every refusal names its family; a design's read word for word as before. A design listing a pending change this build doesn't have is now refused as a newer build's before its content is checked, as a newer number already was, so a newer build's fields never read as damage. The list reader is take_names(v, key, noun), the shape #4811 uses for its own list. For the maintainer, the release step changes: scripts/fold-format-pending.sh now folds every family that crates/doc/build.rs lists (FAMILIES), each into its own next number: designs into crates/doc/src/format/v<N>/ as before, drawings into crates/doc/src/drawing/format/v<N>/ from 2. With nothing pending in a family it says so and moves nothing. Its test folds a drawing change into v2 beside the design changes. docs/releasing.md, CONTRIBUTING.md and AGENTS.md say so. build.rs lists each family's changes from its own folder, each folder's versions contiguous from its own base. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Drawing record: format 1 of the drawing family (#3890) A drawing is now a record of its own (crates/doc/src/drawing.rs): its name, the designs it draws (sources: an id and the design file's path, relative to the drawing's folder as a linked design's is), its properties under the design metadata's rules, its units (each design's own, or one length unit of the expression unit table), its content language (a BCP 47 tag) and its sheets. A sheet holds its paper, a copy of its drawing border's profile, the resolution its pictures are rendered at (300 dpi unless it says, 25 to 2400), the component it documents and whether it is left out of the sheet count or of printing. This is format 1 of the drawing family; each later kind of record adds one file in crates/doc/src/drawing/format/pending/. The rules: one id counter for every object, raised above the largest id when a file is read and never rewound; every reference is an id that must resolve, or the file is damaged and refused, never patched; 1 to 1,000 sheets, at most 64 sources, names of 1 to 256 bytes, paths of 1 to 4,096 bytes without NUL. The same drawing always saves as the same bytes. Drawing::from_json reads at most 16 MiB of text, then runs the family's format check, the number check, the upgrade, the typed record (unknown fields refused everywhere) and Drawing::validate. The number check is now one function every family calls, Family::check_numbers, told which field holds other tools' data; a design's refusals read as before. Nothing saves or opens a drawing yet: the container is the next step. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Drawing ids: random and collision-free from format 1 (#3890) A drawing's objects now take random ids, the form jyviko chose on #3890 from #1017: no counter, so objects added on two branches never share an id and never edit one line. The allocator is one module for drawings now and designs later (#626 Phase 3), crates/doc/src/ids.rs: an IdSource gives nonzero u64s by splitmix64 from a seed, each checked against the ids in use and drawn again when it is one, or when it is 0. A run never draws a number twice, so at most one draw per id in use comes before a free one, and a seeded run over a file the same seed made still gets a new id. IdSource::seeded gives the same ids for tests and replays; IdSource::from_entropy seeds a session from the standard library's hash keys, the time and a count, with no new dependency. In a file an id is 13 characters of Crockford base32, lowercase (0000000000001 to fzzzzzzzzzzzz): ids::encode writes it and ids::decode reads only that spelling, case-sensitive, so an id has one form to search for. Anything else, 0 included, makes the drawing damaged. The drawing loses next_id (a file that holds one is refused), and Drawing::new and allocate_id take the IdSource. Messages name ids as the file writes them. The component a sheet documents stays its design's own number until designs move over. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Drawing record: a drawing too large to reopen isn't saved (#3890) from_json reads at most MAX_DRAWING_BYTES (16 MiB), but to_json had no limit. Other tools' properties are kept as they came, and indenting them can grow a drawing read in at about 4 MB past 16 MiB (two million zeros in one array), so the next read refused what the save had just written. 0xlillith found it in review of #3891. to_json now returns a Result and refuses JSON longer than a read takes ("drawing too large to save (at most 16 MiB)"), so every drawing saved opens again. Nothing writes drawing files yet, so the error reaches the future file writer before it publishes anything. Test: that case is refused, and a smaller compact drawing saves and reopens unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Drawing files: a drawing saved as a container or as plain JSON, never read as a design (#3890) K3 of the drawing storage plan (W11.2): the file a drawing is saved in. Nothing writes one from a command yet; opening and saving come with K5. - A drawing container is a design container holding `drawing.json` (Deflate, as `document.json`) in place of `document.json`, and `container.json` says so: {"content": "drawing", "format": "solidcraft-container/1"}. A design's `container.json` is as it was, with no `content`. The plain JSON form is the drawing's own text. Both give the same bytes every save, so a drawing can live in version control as text. - `io::file_kind` tells a design from a drawing by `container.json` or by the JSON's format. The design reader refuses a drawing ("this file is a SolidCraft drawing, not a design: open it as a drawing") and the drawing reader a design; plain JSON only asks when it isn't a design, so reading a design costs nothing more. A container's content this build doesn't know, or a drawing container that also holds a design's `document.json`, is refused. - `read_drawing` (bytes, either form), `read_drawing_file` (one seekable handle, the design reader's checks) and `write_drawing_container`; `DRAWING_EXT` (`scdwg`) and `is_drawing_path` beside the design's. - The container writer's set-up and finish, the file opening and the container sniffing move into one function each, which designs and drawings both use. The container's own checks (budgets, entries, the ZIP directory) are the design container's, word for word. Tests: a drawing round-trips through both forms byte for byte, and the container holds exactly `container.json` and `drawing.json`; `file_kind` on both forms of both kinds; each reader refuses the other's file; unknown content, a stray `document.json`, a missing drawing, an unknown container version and a damaged drawing refused; both forms from disk, and a directory refused; mutation fuzz of both forms (an error or a drawing, never a panic). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
300 lines
17 KiB
Markdown
300 lines
17 KiB
Markdown
# Releasing SolidCraft
|
|
|
|
Releases are deliberate operations that an agent can complete end to end. Development lands
|
|
on `main`; pushing the selected commit to `release` builds all packages and creates a **draft**
|
|
GitHub Release. Publishing that verified draft is a separate operation. Pushing to `main` or
|
|
pushing a tag does not start the release workflow. There is no automatic commit-message-based
|
|
version bump and no patch release for every merge.
|
|
|
|
## Names and deployment
|
|
|
|
Every release asset, binary, installer product name and package uses the SolidCraft name
|
|
(`solidcraft-<version>-linux-<arch>.AppImage`, `SolidCraft-<version>-windows-x64.exe`,
|
|
`solidcraft-cli` archives, …). The old name survives only in the shims listed in
|
|
[compatibility.md](compatibility.md) (the end-of-life Flatpak refs of the old Linux app ID, the legacy `.zsync` and `.flatpakrepo`
|
|
copies, the deprecated old-name CLI alias); keep them until that document says they can go. Do not
|
|
rewrite published assets, checksums, tags or historical release notes of earlier versions.
|
|
|
|
The main installers (`.msi`, portable `.zip`, `.dmg`, `.AppImage`, `.deb`, `.rpm`, `.flatpak`, `.snap`) are
|
|
also attached without the version in their names, for example `solidcraft-windows-x64.msi` and
|
|
`solidcraft-linux-x86_64.AppImage`, and listed in `SHA256SUMS.txt`. The README's Download section
|
|
links to `https://github.com/bherbruck/solidcraft/releases/latest/download/<name>`, which follows
|
|
the release marked latest; nightlies never are. Keep these names stable: renaming one breaks the
|
|
README links and the in-app update check, which picks them by name (`crates/ui-egui/src/update.rs`;
|
|
[updates and privacy](book/src/guide/updates.md)).
|
|
|
|
Project Pages publishes the documentation, browser app and published-release Flatpak
|
|
repository under `/solidcraft/`. Do not add a separate owner-site publisher or permanent
|
|
old-name Pages/Flatpak aliases. GitHub repository redirects are separate from Pages hosting;
|
|
verify the new project URLs after deployment.
|
|
|
|
The browser app keeps itself for offline use (`apps/solidcraft-web/sw.js`). Browsers keep that
|
|
service worker after the code that registered it is gone, so to switch it off deploy
|
|
`apps/solidcraft-web/sw.js` unbuilt (as `trunk serve` builds do): it deletes what it kept and
|
|
unregisters. A site without `build.json` is also safe: launches then go to the network.
|
|
|
|
## Nightly prereleases
|
|
|
|
`release.yml` also runs at midnight in `America/New_York` (Eastern time, following daylight
|
|
saving time). GitHub may start scheduled runs later when its runners are busy.
|
|
Before building, it compares the exact scheduled `main` commit with the tag of the most
|
|
recently published release, including prereleases. If the commits match, all packaging and
|
|
publication jobs are skipped: no new version, tag, or release is created. Drafts do not count
|
|
as published releases, so a failed build or publication can be retried the following night.
|
|
|
|
Changed commits use the existing package build and validation jobs. Only after all jobs
|
|
succeed, the workflow stages the assets in a draft and publishes a prerelease named
|
|
`v<workspace-version>-nightly.<YYYYMMDD>.<run-number>.<run-attempt>` with checksums and generated
|
|
notes. Any existing workspace prerelease suffix is replaced by the nightly suffix. Dates
|
|
use Eastern time; package versions are overridden without changing Cargo.toml or Cargo.lock,
|
|
so the binaries' embedded Cargo version remains the workspace version. Nightlies do not
|
|
replace the latest stable release or advance the `release` branch. The normal deliberate
|
|
release process below continues to create drafts for separate verification and publication.
|
|
|
|
Nightly publication uses `GITHUB_TOKEN`, so it does not trigger the downstream Flatpak Pages
|
|
deployment. The stable Flatpak repository is not automatically updated with nightly builds.
|
|
|
|
## Choose and prepare the version
|
|
|
|
1. Fetch `origin` and its tags. Inspect the previous published release and the changes since
|
|
it. Choose one version for the complete batch, based on user-visible behavior:
|
|
- Patch: compatible fixes, reliability improvements, and packaging corrections.
|
|
- Minor: new compatible capabilities. While on `0.x`, also use a minor bump for breaking
|
|
changes and explain the break and any migration in the notes.
|
|
- Major: incompatible public behavior or file-format/API changes after `1.0`. Moving to
|
|
`1.0` is an explicit product decision, not something inferred from a commit prefix.
|
|
- Use `-rc.1`, `-rc.2`, etc. when a release candidate is requested.
|
|
Documentation-only changes normally wait for the next release. State the reason for the
|
|
chosen bump in the release notes. Follow any version or release scope specified by the owner.
|
|
2. Update `[workspace.package] version` in root `Cargo.toml`. Then run
|
|
`cargo update --workspace --offline` to refresh the workspace packages' versions in
|
|
`Cargo.lock` (it changes only our own crates, never dependency versions, and needs no
|
|
network). Inspect the diff: only `version = ` lines of workspace crates should change.
|
|
SolidCraft does not currently implement `cargo xtask version set`.
|
|
3. Fix the file format numbers: run `scripts/fold-format-pending.sh`. It moves the pending
|
|
format changes of designs (`crates/doc/src/format/pending/*.rs`) and of drawings
|
|
(`crates/doc/src/drawing/format/pending/*.rs`) into each one's next `v<N>/` folder, so the
|
|
release writes and reads those numbers for good, and does nothing for a family with nothing
|
|
pending. Commit the move with the version files. (CONTRIBUTING.md, "Changing the design
|
|
file format".)
|
|
4. Run `cargo xtask ci` and the packaging checks in `.github/workflows/packaging-lint.yml`.
|
|
Commit the version files through the normal review flow and land them on `main`.
|
|
Do not use `[skip ci]`. Record the exact commit SHA to release. If it changes, revalidate it.
|
|
|
|
## Build the draft
|
|
|
|
Use an authenticated maintainer account or GitHub App with the repository's normal release
|
|
permissions. Follow branch rules; never force-push or bypass required checks.
|
|
|
|
```sh
|
|
git fetch origin --tags
|
|
git switch release
|
|
git merge --ff-only origin/release
|
|
git merge --ff-only origin/main
|
|
git push origin release
|
|
```
|
|
|
|
For the first release, after this workflow has landed on `main`, create `release` from the
|
|
validated `origin/main` commit (`git switch -c release origin/main`) and push it. If the branch
|
|
already exists, use the commands above. Do not create the branch from unrelated work. If a
|
|
fast-forward fails, inspect and resolve the divergence through the normal review flow.
|
|
|
|
Find the `release.yml` Actions run for the recorded SHA and `release` branch, and monitor that
|
|
specific run. The workflow builds Linux (both architectures, including Flatpak), macOS,
|
|
Windows, FreeBSD, and web packages. Once every required job succeeds it creates a draft
|
|
`SolidCraft v<version>` with the artifacts, `SHA256SUMS.txt`, install notes, and generated changes.
|
|
|
|
A second push with the same untagged version can rebuild and replace that draft's complete
|
|
asset set. Existing release notes are preserved on rebuild; refresh their changes section if
|
|
new commits were added. An existing tag or published release is never overwritten. Use a new
|
|
version after publication. Do not push the version tag yourself: publishing the draft creates
|
|
it at the draft's target commit.
|
|
|
|
## Notes for the next release
|
|
|
|
Items to carry into the next release's notes (step 3 below), then remove from here:
|
|
|
|
- None yet.
|
|
|
|
## Verify and publish
|
|
|
|
When the task authorizes shipping a release, agents should complete these steps without
|
|
requiring the owner to click through the GitHub UI. A request only to prepare a release or
|
|
change release infrastructure does not itself request publication of the application.
|
|
|
|
1. Confirm that the workflow run succeeded for the intended SHA and that the matching release
|
|
is still a draft targeting that SHA. Avoid publishing while another release build is active.
|
|
2. Download all assets to a fresh directory. Run `sha256sum --check SHA256SUMS.txt` and check
|
|
that every expected platform/architecture is present. Smoke-test the built CLI's `--version`
|
|
and an example model on an available platform. Inspect the package-check job output for
|
|
other platforms; report any platform you could not exercise yourself.
|
|
3. Review the generated notes. Add a concise description of features, fixes, breaking changes,
|
|
and known limitations. Keep the installation instructions. Packages are currently unsigned;
|
|
do not claim otherwise. Resolve failed checks or missing artifacts before publication.
|
|
4. Publish the verified draft using `gh` or the equivalent GitHub release API. For example:
|
|
|
|
```sh
|
|
# Substitute the version that was actually built and verified.
|
|
gh release edit v0.2.0 --draft=false --latest
|
|
# For a release candidate instead:
|
|
gh release edit v0.2.0-rc.1 --draft=false --prerelease --latest=false
|
|
```
|
|
|
|
5. Confirm that the release is public and its tag resolves to the recorded SHA. Report the
|
|
release URL, version, checks performed, and any remaining limitations.
|
|
|
|
## Dry runs and retries
|
|
|
|
`gh workflow run release.yml --ref <branch> -f draft=false` builds packages and uploads the
|
|
`release-assets` Actions artifact without creating or publishing a release. For an explicit
|
|
retry that creates/updates a draft, use `--ref release -f draft=true`. Draft creation from
|
|
another branch is rejected. A rerun must still use an unpublished, untagged version.
|
|
|
|
## Flatpak repository coordination
|
|
|
|
The Flatpak repository proposed in PR #39 consumes **published** releases, not these drafts.
|
|
Keep that deployment separate from building the application. A publication made with an
|
|
Actions `GITHUB_TOKEN` does not trigger downstream `release: published` workflows; in that
|
|
case explicitly dispatch the Flatpak workflow with the published tag, or use an appropriately
|
|
authorized maintainer/App token for publication. Do not assume the repository updated: check
|
|
the deployment run. The Flatpak workflow requests the shared Pages workflow with that tag;
|
|
Pages assembles the documentation, browser app, and Flatpak repository together. Ordinary
|
|
docs updates include the latest stable Flatpak release too. Verify the resulting Pages run,
|
|
not only the dispatch job, so a release cannot erase the docs or app and docs updates cannot
|
|
erase the package repository.
|
|
|
|
## Snap package and Snap Store
|
|
|
|
Every release and nightly attaches `solidcraft-<version>-linux-<arch>.snap` for x86_64 and
|
|
aarch64 (`packaging/linux/snap-pack.sh`, manifest `packaging/linux/snap/snapcraft.yaml`). Like the
|
|
Flatpak, it repackages the Linux job's tarball. The `snap` job installs it with `--dangerous`,
|
|
starts the confined app on headless X11 and Wayland (`packaging/linux/snap-smoke.py`), models a
|
|
box over the control channel and keeps the captured frames as the `snap-smoke-<arch>` artifact.
|
|
|
|
The Snap Store steps run only when the `SNAPCRAFT_STORE_CREDENTIALS` repository secret exists;
|
|
without it they are skipped and the `.snap` files are still attached to the release:
|
|
|
|
- nightlies are uploaded to `latest/edge`;
|
|
- release drafts (pushes to `release`) are uploaded to `latest/candidate`, after every package
|
|
built and the draft was staged;
|
|
- publishing a non-prerelease GitHub release runs `snap-store.yml`, which promotes
|
|
`latest/candidate` to `latest/stable`. As with the Flatpak repository, a publication made with
|
|
`GITHUB_TOKEN` doesn't trigger it: then run `gh workflow run snap-store.yml`.
|
|
|
|
To enable the Snap Store once (owner):
|
|
|
|
1. Sign in at <https://snapcraft.io> with an Ubuntu One account and register the name at
|
|
<https://snapcraft.io/register-snap> (or `snapcraft login` then `snapcraft register solidcraft`).
|
|
2. On a machine with snapcraft (`sudo snap install snapcraft --classic`), export upload-only
|
|
credentials for this snap:
|
|
|
|
```sh
|
|
snapcraft export-login --snaps=solidcraft \
|
|
--channels=edge,candidate,stable \
|
|
--acls=package_access,package_push,package_update,package_release \
|
|
--expires=2027-10-01 solidcraft-store-credentials.txt
|
|
```
|
|
|
|
3. Store them as the repository secret and delete the file:
|
|
|
|
```sh
|
|
gh secret set SNAPCRAFT_STORE_CREDENTIALS -R bherbruck/solidcraft < solidcraft-store-credentials.txt
|
|
rm solidcraft-store-credentials.txt
|
|
```
|
|
|
|
4. Optional: fill in the store listing at <https://snapcraft.io/solidcraft/listing> (the icon,
|
|
summary and description come from the snap; add screenshots and the category "Art and design").
|
|
5. The next nightly fills `edge` and the next release fills `candidate`, then `stable` on
|
|
publication. To fill `stable` from an already published release right away, download its
|
|
`.snap` files and run `snapcraft upload --release=stable <file>` for each.
|
|
|
|
Renew the credentials before `--expires` by repeating steps 2 and 3. The snap uses strict
|
|
confinement and only plugs that connect automatically, apart from `removable-media`, which users
|
|
connect with `sudo snap connect solidcraft:removable-media` (getting-started.md).
|
|
|
|
## WinGet (Windows Package Manager)
|
|
|
|
SolidCraft is in [winget-pkgs](https://github.com/microsoft/winget-pkgs) as
|
|
`bherbruck.SolidCraft` (`winget install bherbruck.SolidCraft`). Publishing a non-prerelease
|
|
GitHub release runs `winget.yml`, which uses [Komac](https://github.com/russellbanks/Komac)
|
|
(a pinned, checksum-verified binary) to open a pull request at microsoft/winget-pkgs from the
|
|
owner's fork `bherbruck/winget-pkgs`. It submits the three versioned MSIs
|
|
(`solidcraft-<version>-windows-{x64,x86,arm64}.msi`, never the fixed-name copies), reads their
|
|
product codes, links the release notes and keeps the other fields from the previous version's
|
|
manifest. The winget-pkgs bots validate it and a moderator merges it, usually within a day or two.
|
|
|
|
The job does nothing, successfully, while the `WINGET_TOKEN` repository secret is missing or
|
|
before the package's first version is merged into winget-pkgs. Like `snap-store.yml`, a
|
|
publication made with `GITHUB_TOKEN` doesn't trigger it: then run
|
|
`gh workflow run winget.yml -R bherbruck/solidcraft -f tag=v<version>`.
|
|
|
|
To enable it once (owner):
|
|
|
|
1. Create a **classic** personal access token at <https://github.com/settings/tokens/new>
|
|
(Settings > Developer settings > Personal access tokens > Tokens (classic)): note
|
|
"solidcraft winget", an expiry such as one year, and only the **`public_repo`** scope.
|
|
Fine-grained tokens can't open pull requests on microsoft/winget-pkgs.
|
|
2. Store it as the repository secret (paste the token when asked):
|
|
|
|
```sh
|
|
gh secret set WINGET_TOKEN -R bherbruck/solidcraft
|
|
```
|
|
|
|
3. Keep the fork `bherbruck/winget-pkgs` (Komac pushes its branches there). Its default branch
|
|
doesn't need syncing.
|
|
|
|
When the token expires, create a new one the same way and run step 2 again. If a release was
|
|
published while the secret was missing or expired, submit it afterwards with
|
|
`gh workflow run winget.yml -R bherbruck/solidcraft -f tag=v<version>`.
|
|
|
|
## Update signing
|
|
|
|
The app's **Update now** (docs/book/src/guide/updates.md) only installs a package whose SHA-256
|
|
matches the release's `SHA256SUMS.txt`, fetched over HTTPS. That protects against corrupted and
|
|
tampered downloads in transit, but not against someone who can upload release assets. Signing
|
|
the checksum list closes that gap: once `PUBLIC_KEY` in `crates/ui-egui/src/update/install.rs`
|
|
is set, the app also requires `SHA256SUMS.txt.minisig`, a [minisign](https://jedisct1.github.io/minisign/)
|
|
signature by that key whose trusted comment names the release (`SolidCraft v<version>`), and
|
|
refuses to update in place otherwise. The release workflow signs the list when the
|
|
`UPDATE_SIGNING_KEY` secret exists, and fails when the app expects signatures but the secret is
|
|
missing.
|
|
|
|
To turn it on once (owner):
|
|
|
|
1. On a trusted machine with minisign (`sudo apt install minisign`, `brew install minisign` or
|
|
`winget install minisign`), make a key pair without a password (the workflow can't type one):
|
|
|
|
```sh
|
|
minisign -G -W -p solidcraft-update.pub -s solidcraft-update.key
|
|
```
|
|
|
|
2. Store the secret key as the repository secret and keep an offline backup of it (a lost key
|
|
means a new key and an app release that carries it; a leaked key means the same, quickly):
|
|
|
|
```sh
|
|
gh secret set UPDATE_SIGNING_KEY -R bherbruck/solidcraft < solidcraft-update.key
|
|
```
|
|
|
|
3. Put the public key (the second line of `solidcraft-update.pub`, starting with `RW`) into
|
|
`crates/ui-egui/src/update/install.rs`:
|
|
|
|
```rust
|
|
pub const PUBLIC_KEY: Option<&str> = Some("RW…");
|
|
```
|
|
|
|
and land that through a PR. Builds from then on refuse unsigned updates; releases built
|
|
from then on carry `SHA256SUMS.txt.minisig`.
|
|
4. Delete `solidcraft-update.key` from the machine once the backup is safe.
|
|
|
|
Older builds without the key keep updating with the SHA-256 check alone.
|
|
|
|
## Repository setup
|
|
|
|
The `release` branch is advanced only for intentional release batches. Restrict its writers to
|
|
maintainers/release agents through repository rules if required by the owner's policy. The
|
|
workflow needs `contents: write` only in its draft-creation job. It does not push commits,
|
|
calculate versions, or require a semantic-release bot to bypass `main` protections.
|
|
|
|
This workflow replaces the every-push-to-main semantic-release proposal in PR #38; do not
|
|
merge that automation alongside this release model without redesigning its triggers.
|