Tell people when a newer release is out (#1100)

At start, and at most once a day, a background thread asks GitHub for the latest stable release (one HTTPS GET to releases/latest, nothing else sent; 15 s timeout; silent when offline; GitHub's rate limit respected). When it is newer than this build, an Update button appears next to Report a bug. It opens a window with the version, the release notes and Download (the asset that fits this installation), Skip this version and Remind me later. - Versions compare as semver; a nightly counts as the release it was built after, so it is offered only a newer stable release. - The installation is detected (AppImage, Flatpak, Snap from the store or a file, deb, rpm, tar.gz, Windows MSI/portable/exe, macOS app); Download picks the fixed-name asset. Development builds and the Flatpak (no network permission) never check. - Preferences > General > Updates: Check for updates automatically (on) and Check now. - HTTP via ureq + rustls with the operating system's certificates (desktop app only). - docs: Updates and privacy page. Co-authored-by: Claude Opus 5.5 <[email protected]>
2026-10-14 10:36:56 -04:00
1 parent 88432d226a
commit a6928abf48
@@ -14,6 +14,7 @@
 - [Plastic parts](guide/plastic.md)
 - [Import and export](guide/files.md)
 - [Keyboard shortcuts](guide/shortcuts.md)
+- [Updates and privacy](guide/updates.md)
 - [Driving SolidCraft with an AI agent (MCP)](guide/mcp.md)

 # Developer guide
@@ -0,0 +1,69 @@
+# Updates and privacy
+
+SolidCraft tells you when a newer release is out. It never updates itself without asking, and
+the check sends nothing about you or your designs.
+
+## What you see
+
+When a newer stable release exists, an **Update** button appears in the title bar next to
+**Report a bug**. It opens a small window with the new version, its release notes and three
+choices:
+
+- **Download** opens the file that fits your installation (see the table below) in your
+  browser, or the release page when there isn't one.
+- **Skip this version** hides the button until an even newer release comes out.
+- **Remind me later** hides it for three days.
+
+**Preferences ▸ General ▸ Updates** has **Check for updates automatically** (on by default) and
+**Check now**, which checks right away and shows the window even for a version you skipped.
+
+## What is sent
+
+One HTTPS request, at start and at most once a day while SolidCraft runs:
+
+```text
+GET https://api.github.com/repos/bherbruck/solidcraft/releases/latest
+User-Agent: SolidCraft-update-check
+Accept: application/vnd.github+json
+X-GitHub-Api-Version: 2022-11-28
+```
+
+That's all: no version number, no machine or user identifier, no usage data, no cookies. GitHub
+sees the request like any other visit to the API (your IP address, the time); see
+[GitHub's privacy statement](https://docs.github.com/site-policy/privacy-policies/github-general-privacy-statement).
+SolidCraft compares the answer with its own version on your computer.
+
+- Offline, or GitHub doesn't answer within 15 seconds: nothing is shown, and the check is tried
+  again an hour later.
+- GitHub's rate limit for anonymous requests (60 an hour per address) is respected: when GitHub
+  says to wait, SolidCraft waits that long, Check now included.
+- Turning off **Check for updates automatically** stops the checks; only **Check now** asks.
+- Setting the environment variable `SOLIDCRAFT_UPDATE_CHECK=0` turns all checks off, for
+  example on managed machines.
+
+Builds you compile yourself, the Flatpak and the browser app (which updates itself) never check.
+
+## Which file Download gets
+
+Releases attach the main packages under fixed names (see [releasing](https://github.com/bherbruck/solidcraft/blob/main/docs/releasing.md)),
+and SolidCraft picks the one matching how it was installed:
+
+| Installed as | Detected by | Download | How to update |
+|---|---|---|---|
+| AppImage | `APPIMAGE` is set | `solidcraft-linux-<arch>.AppImage` | Replace the old AppImage with the new one |
+| Flatpak | `FLATPAK_ID` is set | doesn't check (see below) | `flatpak update ai.storyteller.solidcraft` |
+| Snap from the Snap Store | `SNAP` is set | release page | `sudo snap refresh solidcraft` (snapd also refreshes by itself) |
+| Snap from a downloaded file | `SNAP_REVISION` starts with `x` | `solidcraft-linux-<arch>.snap` | `sudo snap install --dangerous ./solidcraft-linux-<arch>.snap` |
+| `.deb` | under `/usr`, dpkg knows `solidcraft` | `solidcraft-linux-<arch>.deb` | `sudo apt install ./solidcraft-linux-<arch>.deb` |
+| `.rpm` | under `/usr`, an rpm database exists | `solidcraft-linux-<arch>.rpm` | `sudo dnf install ./solidcraft-linux-<arch>.rpm` |
+| `.tar.gz` | anywhere else on Linux | `solidcraft-<version>-linux-<arch>.tar.gz` | Unpack over the old copy |
+| Windows installer | under Program Files | `solidcraft-windows-<arch>.msi` | Run the installer |
+| Windows portable | `solidcraft-cli.exe` beside it | `solidcraft-windows-<arch>-portable.zip` | Unzip over the old copy |
+| Windows `.exe` | anywhere else on Windows | `SolidCraft-<version>-windows-x64.exe` | Replace the old `.exe` |
+| macOS | inside `SolidCraft.app` | `solidcraft-macos-universal.dmg` | Drag the new app to Applications |
+
+The window shows the command for Snap, `.deb` and `.rpm` installations, with a Copy button. The
+Flatpak has no network permission and Flatpak itself (or your software center) offers its
+updates, so it never checks. Release builds compare versions as [semver](https://semver.org): a nightly build counts
+as the release it was built after, so it's offered only a newer stable release, and release
+candidates are offered their final release.
@@ -123,7 +123,7 @@ unit regardless of the design, pass an expression with one: `"value": "50 mm"` o
 | `ui.home` | `open?`: bool; `sample?`: index | the start page: show or hide it, open a built-in sample (once built); returns `open` and the recent designs |
 | `ui.shortcut` | `command`, `key?`, `replace?` | a command's key, or rebinds it (`""` clears; a key another command uses is refused unless `replace`) |
 | `ui.help` | `item?`: `about`, `shortcuts` (read only), `report` (copies diagnostics), `crashes` (the Crash Reports window) | the version, commit, build date and diagnostic text |
-| `ui.prefs` | any of `default_units`, `nav` (`fusion`, `solidworks`, `inventor`, `alias`, `tinkercad`, `openscad`), `zoom_reverse`, `zoom_to_cursor`, `smooth_wheel_zoom` (default true), `trackpad_pan` (default true: two-finger scroll pans, pinch zooms), `orbit_cursor`, `look_at_anim`, `look_at_speed`, `middle_double_click` (`home` (default), `fit`, `off`), `msaa`, `length_decimals`, `angle_decimals`, `theme` (`dark`, `light`, `system`), `language` (`en`, `ja`, `de`, `ko`, `zh`; see [localization](localization.md)), `ui_scale`, `up_axis` (`z`, `y`), `offer_stand_up`; `open` (a page: General, Navigation, Keyboard Shortcuts, Design, Graphics, Sketch, Selection) opens the Preferences dialog there; `button`: `ok`, `cancel`, `apply`, `defaults`; `stand_up: true` stands up a just-opened Y-up file | sets preferences (kept between runs), returns them all plus `dialog` (the open page or null), `dark` and `stand_up_offer` |
+| `ui.prefs` | any of `default_units`, `nav` (`fusion`, `solidworks`, `inventor`, `alias`, `tinkercad`, `openscad`), `zoom_reverse`, `zoom_to_cursor`, `smooth_wheel_zoom` (default true), `trackpad_pan` (default true: two-finger scroll pans, pinch zooms), `orbit_cursor`, `look_at_anim`, `look_at_speed`, `middle_double_click` (`home` (default), `fit`, `off`), `msaa`, `length_decimals`, `angle_decimals`, `theme` (`dark`, `light`, `system`), `language` (`en`, `ja`, `de`, `ko`, `zh`; see [localization](localization.md)), `ui_scale`, `up_axis` (`z`, `y`), `offer_stand_up`, `check_updates` (default true; [updates](book/src/guide/updates.md)); `open` (a page: General, Navigation, Keyboard Shortcuts, Design, Graphics, Sketch, Selection) opens the Preferences dialog there; `button`: `ok`, `cancel`, `apply`, `defaults`; `stand_up: true` stands up a just-opened Y-up file | sets preferences (kept between runs), returns them all plus `dialog` (the open page or null), `dark` and `stand_up_offer` |
 | `ui.capture` | `action?`: `capture`, `revert`, `cancel` | answers the Capture Position question (asked when a command starts or the design is saved while components were moved without capturing); without `action`, what waits |
 | `ui.window` | `action`: minimize, maximize, restore, toggle, close | what the title bar's caption buttons do (on Windows and Linux the application bar is the title bar); close asks about unsaved designs first |
 | `ui.agent_cursor` | `show` (bool), `speed`: a number from 1 to 5 (times the normal speed) or `"instant"` (no animation: the command runs at once and the pointer jumps to where it acted), `follow_camera` (bool); all optional | the settings. While the cursor is shown, `engine.execute` first glides to the command's toolbar button and to each pick, then runs and replies; later requests wait their turn. `"animate": false` on a call skips it |
@@ -20,7 +20,8 @@ also attached without the version in their names, for example `solidcraft-window
 `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.
+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