From e56e055fa1fe27583a7c58bd987243772b9588cd Mon Sep 17 00:00:00 2001 From: bherbruck Date: Mon, 12 Oct 2026 17:25:27 -0400 Subject: [PATCH] README: put a Download section with per-platform installers at the top (#411) Badges and one-line instructions for Windows, macOS, Linux and the web app, right after the tagline and demo. The links use releases/latest/download with version-less file names, which release.yml now attaches (and checksums) alongside the versioned installers. The Flatpak note and the name/compatibility section move into the book's Getting started page. Claude-Session: https://claude.ai/code/session_01RjGw4gA5ZvKrU8MQP6sBgT Co-authored-by: Claude Opus 5.5 --- .github/release-notes.md | 2 + .github/workflows/release.yml | 22 ++++++++++ README.md | 60 ++++++++++++++++++-------- docs/book/src/guide/getting-started.md | 15 ++++++- docs/releasing.md | 7 +++ 5 files changed, 88 insertions(+), 18 deletions(-) diff --git a/.github/release-notes.md b/.github/release-notes.md index f323c731..458154d6 100644 --- a/.github/release-notes.md +++ b/.github/release-notes.md @@ -36,6 +36,8 @@ old-name Pages addresses are not permanent aliases. - **FreeBSD:** `tar -xzf solidcraft-{version}-freebsd-x86_64.tar.gz --strip-components 1 -C /usr/local`. - **Web:** `solidcraft-web-{version}.zip` is a static site to host yourself. - `SHA256SUMS.txt`: `sha256sum -c SHA256SUMS.txt --ignore-missing`. +- Files without a version in the name (`solidcraft-windows-x64.msi`, `solidcraft-linux-x86_64.AppImage`, …) + are the same packages under fixed names, for download links that always fetch the latest release. For Flatpak feed installation and updates, add Flathub for the required runtime before installing SolidCraft; keep both remotes in the same user installation: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d6d65ccf..7577e8da 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -12,6 +12,10 @@ # Windows x64, x86, arm64 .msi and a portable .zip; x64 also the plain .exe packaging/windows # Web a .zip of the static site packaging/web # +# The main installers are also attached without the version in their names +# (solidcraft-windows-x64.msi, solidcraft-linux-x86_64.AppImage, ...) so that +# releases/latest/download/ links in the README keep working across releases. +# # A dry run: dispatch with draft=false (the default). Only the release branch may create drafts. name: Release @@ -350,6 +354,24 @@ jobs: pattern: release-* path: artifacts merge-multiple: true + - name: Version-less copies for permanent download links + # The README links to releases/latest/download/, which must not change between + # releases: solidcraft--windows-x64.msi is also uploaded as + # solidcraft-windows-x64.msi, and so on for the main installers. + working-directory: artifacts + run: | + shopt -s nullglob + for f in "solidcraft-$VERSION-"*; do + case "$f" in + *.msi | *-portable.zip | *.dmg | *.AppImage | *.deb | *.rpm | *.flatpak | *.snap) + cp -- "$f" "solidcraft-${f#"solidcraft-$VERSION-"}" ;; + esac + done + for f in solidcraft-windows-x64.msi solidcraft-macos-universal.dmg \ + solidcraft-linux-x86_64.AppImage solidcraft-linux-x86_64.deb solidcraft-linux-x86_64.rpm; do + test -s "$f" || { echo "::error::missing version-less copy $f"; exit 1; } + done + ls -l solidcraft-[!0-9]* - name: Checksums and notes run: | (cd artifacts && sha256sum -- * | tee SHA256SUMS.txt) diff --git a/README.md b/README.md index 46d6be2b..7b338478 100644 --- a/README.md +++ b/README.md @@ -10,12 +10,50 @@ model through the built-in MCP server. *Start with an empty design and draw the original parametric electronics enclosure in the English desktop UI: rounded corners, a shell, a USB port sketched directly on the wall and a four-boss pattern. Change width from 80 → 100 mm and wall thickness from 2 → 3 mm in Parameters and watch it rebuild. Original animated pointer and click cues; 4× playback. [Full video](https://github.com/bherbruck/solidcraft/raw/refs/heads/main/docs/screenshots/enclosure-demo-0.2.1.mp4), generated with the [demo script](examples/demo/record_ui.sh).* -**Documentation:** the [SolidCraft book](https://bherbruck.github.io/solidcraft/) (user guide, -developer guide and command reference; sources in [docs/book](docs/book)), and the -[web app](https://bherbruck.github.io/solidcraft/app/) to try it in the browser. +## Download -Linux Flatpak installation needs the Freedesktop runtime from Flathub as well as the -SolidCraft application feed. See [install and launch commands](https://bherbruck.github.io/solidcraft/guide/getting-started.html#linux-flatpak). +[![Download for Windows][badge-windows]][windows-msi] +[![Download for macOS][badge-macos]][macos-dmg] +[![Download for Linux][badge-linux]][linux-appimage] +[![Try it in your browser][badge-web]][web-app] + +- **Windows:** download and run the [installer][windows-msi]. + Also for [ARM64][windows-arm64-msi] and [32-bit][windows-x86-msi] PCs, or as a + [portable zip][windows-portable] that runs without installing. +- **macOS:** open the [disk image][macos-dmg] and drag SolidCraft into Applications + (Apple silicon and Intel). +- **Linux:** download the [AppImage][linux-appimage], allow it to run as a program and open it. + Or install the [.deb][linux-deb] (Ubuntu, Debian, Mint) or [.rpm][linux-rpm] (Fedora, + openSUSE), or use [Flatpak](https://bherbruck.github.io/solidcraft/guide/getting-started.html#linux-flatpak). + For ARM64: [AppImage][linux-arm64-appimage], [.deb][linux-arm64-deb], [.rpm][linux-arm64-rpm]. +- **Web:** [try it in your browser][web-app], no install. + +The downloads aren't signed yet. On Windows, if SmartScreen warns you, choose **More info**, then +**Run anyway**. On macOS, the first time, right-click SolidCraft in Applications and choose **Open**. + +Older versions, checksums and other formats are on the [releases page](https://github.com/bherbruck/solidcraft/releases). +Install details, upgrading from earlier builds and building from source are in +[Getting started](https://bherbruck.github.io/solidcraft/guide/getting-started.html). + +[badge-windows]: https://img.shields.io/badge/Windows-Download-0078D6?style=for-the-badge&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0yIDJoOS41djkuNUgyek0xMi41IDJIMjJ2OS41aC05LjV6TTIgMTIuNWg5LjVWMjJIMnpNMTIuNSAxMi41SDIyVjIyaC05LjV6Ii8%2BPC9zdmc%2B +[badge-macos]: https://img.shields.io/badge/macOS-Download-333333?style=for-the-badge&logo=apple&logoColor=white +[badge-linux]: https://img.shields.io/badge/Linux-AppImage-E95420?style=for-the-badge&logo=linux&logoColor=white +[badge-web]: https://img.shields.io/badge/Web-Try_in_browser-2EA44F?style=for-the-badge&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJ3aGl0ZSIgc3Ryb2tlLXdpZHRoPSIyIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIxMCIvPjxwYXRoIGQ9Ik0yIDEyaDIwTTEyIDJhMTUgMTUgMCAwIDEgMCAyME0xMiAyYTE1IDE1IDAgMCAwIDAgMjAiLz48L3N2Zz4%3D +[windows-msi]: https://github.com/bherbruck/solidcraft/releases/latest/download/solidcraft-windows-x64.msi +[windows-arm64-msi]: https://github.com/bherbruck/solidcraft/releases/latest/download/solidcraft-windows-arm64.msi +[windows-x86-msi]: https://github.com/bherbruck/solidcraft/releases/latest/download/solidcraft-windows-x86.msi +[windows-portable]: https://github.com/bherbruck/solidcraft/releases/latest/download/solidcraft-windows-x64-portable.zip +[macos-dmg]: https://github.com/bherbruck/solidcraft/releases/latest/download/solidcraft-macos-universal.dmg +[linux-appimage]: https://github.com/bherbruck/solidcraft/releases/latest/download/solidcraft-linux-x86_64.AppImage +[linux-deb]: https://github.com/bherbruck/solidcraft/releases/latest/download/solidcraft-linux-x86_64.deb +[linux-rpm]: https://github.com/bherbruck/solidcraft/releases/latest/download/solidcraft-linux-x86_64.rpm +[linux-arm64-appimage]: https://github.com/bherbruck/solidcraft/releases/latest/download/solidcraft-linux-aarch64.AppImage +[linux-arm64-deb]: https://github.com/bherbruck/solidcraft/releases/latest/download/solidcraft-linux-aarch64.deb +[linux-arm64-rpm]: https://github.com/bherbruck/solidcraft/releases/latest/download/solidcraft-linux-aarch64.rpm +[web-app]: https://bherbruck.github.io/solidcraft/app/ + +**Documentation:** the [SolidCraft book](https://bherbruck.github.io/solidcraft/) (user guide, +developer guide and command reference; sources in [docs/book](docs/book)). **Status: early but usable for simple parts.** 75 of 76 public reference parts match their analytic or FreeCAD-computed volume, area, centre of mass and bounding box @@ -25,18 +63,6 @@ are listed by area in [docs/features.md](docs/features.md); status and plans are Open work and known bugs are in [GitHub issues](https://github.com/bherbruck/solidcraft/issues), and help is welcome: see [CONTRIBUTING.md](CONTRIBUTING.md). -## Name and compatibility - -SolidCraft was renamed from an earlier working name. Since 0.5.0 everything uses the new -name: the `solidcraft` and `solidcraft-cli` programs, `.solidcraft` designs, `SOLIDCRAFT_*` -environment variables, settings folders and the `solidcraft` MCP server. Upgrading keeps -working: designs, settings, recovery files, environment variables and CLI/MCP setups from -earlier builds carry over. Every compatibility shim is listed in -[docs/compatibility.md](docs/compatibility.md). - -Use the SolidCraft documentation and web-app URLs above. GitHub redirects links to the -renamed repository; old-name Pages and Flatpak URLs are not maintained as permanent aliases. - ## What works - **Sketches** on origin planes, offset planes or planar faces: lines, rectangles, circles, diff --git a/docs/book/src/guide/getting-started.md b/docs/book/src/guide/getting-started.md index d94b5586..c114f6c8 100644 --- a/docs/book/src/guide/getting-started.md +++ b/docs/book/src/guide/getting-started.md @@ -6,7 +6,8 @@ working (see the [compatibility notes](https://github.com/bherbruck/solidcraft/b ## Desktop -Download the latest build from the +Download the installer for your system from the +[Download section of the README](https://github.com/bherbruck/solidcraft#download) or the [releases page](https://github.com/bherbruck/solidcraft/releases), or build it yourself with stable Rust (1.95 or newer): @@ -89,3 +90,15 @@ A script is a list of commands: Units are millimetres and degrees unless an expression says otherwise (`"1 in"`, `"30 deg"`), and Z is up. + +## Name and compatibility + +SolidCraft was renamed from an earlier working name. Since 0.5.0 everything uses the new +name: the `solidcraft` and `solidcraft-cli` programs, `.solidcraft` designs, `SOLIDCRAFT_*` +environment variables, settings folders and the `solidcraft` MCP server. Upgrading keeps +working: designs, settings, recovery files, environment variables and CLI/MCP setups from +earlier builds carry over. Every compatibility shim is listed in the +[compatibility notes](https://github.com/bherbruck/solidcraft/blob/main/docs/compatibility.md). + +Use the SolidCraft documentation and web-app URLs. GitHub redirects links to the renamed +repository; old-name Pages and Flatpak URLs are not maintained as permanent aliases. diff --git a/docs/releasing.md b/docs/releasing.md index b96fe631..9d2760fc 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -15,6 +15,13 @@ Every release asset, binary, installer product name and package uses the SolidCr 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`) 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/`, which follows +the release marked latest; nightlies never are. Keep these names stable: renaming one breaks the +README links. + 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;