Releases & versioning

FolioOrb uses plain semantic versioning. The version lives in one place — app/version.py — and flows into the app, the installers, and the release assets.

How a release is built

Pushing a v* tag (or merging to main) triggers a single GitHub Actions workflow. It runs the tests, builds both installers on their native runners, smoke-tests each frozen bundle, and only then publishes. If either build or smoke test fails, nothing is published and the previous release stays exactly as it was.

Two channels

• Stable — cut by pushing a version tag like v5.6.0. This is what the website, README, and download buttons point to by default. A tag whose number doesn’t match app/version.py fails the build on purpose, so assets can never be mislabeled.
• latest-main — a single rolling prerelease, refreshed on every merge to main. Always marked prerelease, so it never becomes the “latest” download by accident. Offered under Development builds for anyone who wants to test the newest changes.

Assets in every release

Asset	Description
FolioOrb-macOS-arm64-v5.6.0.dmg	macOS Apple Silicon installer
FolioOrb-Windows-x64-v5.6.0-Setup.exe	Windows per-user installer
SHA256SUMS.txt	Checksums for every asset — see verifying downloads

Development builds use the same names with v5.6.0 replaced by main-<short-sha>.

Code-signing roadmap

Builds are currently unsigned (macOS uses only PyInstaller’s ad-hoc signature). We don’t claim otherwise anywhere — the install guides show the exact warnings you’ll see. The path forward, in order:

Phase	Status	Effect
1 · Unsigned + checksums	Now	Works everywhere; system warnings on first launch
2 · Apple Developer ID signing	Planned	Removes the macOS “cannot verify developer” block
3 · macOS notarization	Planned	No Gatekeeper warning on macOS
4 · Windows code signing	Planned	SmartScreen warnings fade as reputation builds

Note

Until signing lands, verifying the SHA256SUMS.txt and downloading only from the official GitHub Releases is the strongest guarantee that a build is genuine.