Repository Public License
1<!-- ORIX Clean / File: docs/release/distribution.md / Author: Simon-Pierre Boucher / Contact: contact@spboucher.ai -->2# Distribution34How the distributable artifacts are built by `Scripts/package.sh` and checked by `Scripts/finalize.sh`, what5they contain, and how users receive updates.67This document describes a procedure. It does not state that any version has been packaged or published.89## Channel1011ORIX Clean is distributed directly, outside the Mac App Store, as a Developer ID signed and notarized12application. The Mac App Store is not a possible channel for this design: the application is not sandboxed,13because it measures folders the user points it at across the whole disk.1415| Artifact | Name | Purpose |16|---|---|---|17| Disk image | `dist/ORIXClean-<version>.dmg` | Primary download: drag-to-Applications window |18| ZIP archive | `dist/ORIXClean-<version>.zip` | Alternative download, same stapled application |19| Checksums | `dist/SHA256SUMS.txt` | SHA-256 of the two files above |20| Metadata | `dist/release.json` | Version, build, minimum macOS, architectures, artifact sizes and hashes, notary submission ids |2122Requirements stated to users: macOS 15.0 or later; Apple silicon or Intel (universal binary). The application23has been run on macOS 27.0 on Apple silicon only; see `docs/development/performance.md`.2425## Release sequence2627```mermaid28flowchart TD29 A[Scripts/sign.sh] --> B[dist/ORIX Clean.app signed]30 B --> C[Scripts/notarize.sh]31 C --> D[app notarized and stapled]32 D --> E[Scripts/package.sh]33 E --> F[DMG signed, ZIP created]34 F --> G[Scripts/notarize.sh on the DMG with name dmg]35 G --> H[DMG notarized and stapled]36 H --> I[Scripts/finalize.sh]37 I --> J[Gatekeeper checks, SHA256SUMS.txt, release.json]38 J --> K[manual upload of the artifacts]39```4041```sh42Scripts/sign.sh43Scripts/notarize.sh44Scripts/package.sh45Scripts/notarize.sh dist/ORIXClean-<version>.dmg dmg46Scripts/finalize.sh47```4849Each script stops on the first error (`set -euo pipefail`). Signing and notarization are described in50`signing.md` and `notarization.md`.5152## Packaging (`Scripts/package.sh`)53541. Requires `dist/ORIX Clean.app` and requires it to be stapled (`xcrun stapler validate`); otherwise it stops55 and points to `Scripts/notarize.sh`.562. Reads the version and build number from the bundle's `Info.plist`.573. Reads the signing identity from the application's own signature (the `Authority=Developer ID Application: …`58 line), so the disk image is signed by the same identity without naming it in the script.594. Deletes any previous DMG and ZIP of that version.605. Draws the background with `swift Scripts/dmg-background.swift` into `build/dmg-background.png`: 660 by 42061 points at 2x, dark gradient, "ORIX Clean", the tagline, an arrow and "Drag ORIX Clean to the Applications62 folder".636. Copies the application to a temporary staging folder with `ditto` and builds the image with `create-dmg`:6465 | Property | Value |66 |---|---|67 | Volume name | `ORIX Clean <version>` |68 | Window | 660 by 420 at position 200, 140 |69 | Icon size | 128 |70 | Application icon | at 170, 205, extension hidden |71 | Applications shortcut | at 490, 205 |7273 If `create-dmg` fails, the script falls back to a plain compressed image made with `hdiutil create`74 (`UDZO`) containing the application and an `Applications` symlink, without the artwork, and says so on75 standard error.767. Signs the image: `codesign --force --timestamp --sign "<identity>" <dmg>`.778. Creates the ZIP from the stapled application with `ditto -c -k --keepParent`.789. Prints the artifact names and reminds that the DMG must be notarized next.7980The image is signed but not yet notarized when this script ends.8182## Final verification (`Scripts/finalize.sh`)8384Run after the disk image has been notarized and stapled.8586| Step | Command used | Stops the script when |87|---|---|---|88| Gatekeeper on the application | `spctl --assess --type execute --verbose=2` | the assessment is rejected |89| Gatekeeper on the image | `spctl --assess --type open --context context:primary-signature --verbose=2` | rejected |90| Tickets | `xcrun stapler validate` on the application and on the image | a ticket is missing |91| ZIP content | extract with `ditto -x -k` to a temporary folder, then `spctl` and `stapler validate` on the extracted application | rejected or missing |92| Checksums | `shasum -a 256` of the DMG and the ZIP into `dist/SHA256SUMS.txt` | |93| Metadata | writes `dist/release.json` | |9495`release.json` contains the name, bundle identifier, version, build, minimum macOS version, the architectures96reported by `lipo`, a signing description, the two notary submission ids read from `build/notary/app.json` and97`build/notary/dmg.json`, and for each artifact its file name, size in bytes and SHA-256.9899Two caveats when reading that file:100101- The notarization `status` fields are copied from the notary answers saved in `build/notary/app.json` and102 `dmg.json` (`unknown` when a file is missing). The independent proof remains `xcrun notarytool info <id>`.103- The submission ids are empty strings if `build/notary/*.json` is missing, for example after cleaning104 `build/`.105106## Verifying a download107108For anyone who received the artifacts:109110```sh111shasum -a 256 -c SHA256SUMS.txt112spctl --assess --type open --context context:primary-signature --verbose=2 ORIXClean-<version>.dmg113xcrun stapler validate ORIXClean-<version>.dmg114codesign -dvv "/Volumes/ORIX Clean <version>/ORIX Clean.app"115```116117The checksum proves the file is the one that was built; the other three prove who signed it and that Apple118notarized it.119120## Installation and removal121122- Install: open the disk image and drag **ORIX Clean** to **Applications**.123- First launch: the standard Gatekeeper dialog for a downloaded application. Then the onboarding sheet;124 Full Disk Access is optional and can be granted later.125- Nothing is installed outside the bundle: no helper, launch agent, login item, kernel or system extension.126- Remove: move the application to the Trash. Data left behind: the history database folder127 `~/Library/Application Support/ORIX Clean/`, the preferences file of `ai.spboucher.orix.clean`, and whatever128 macOS itself keeps for any application (saved state, caches). See `docs/PRIVACY.md`.129130## Updates131132There is no automatic updater. Sparkle was evaluated and deferred: an updater needs network access, and the1331.0 application contains no network code at all (`Scripts/check.sh` enforces this). Updates are manual134downloads: the user replaces the application in Applications with the new version. Settings > About says so:135"ORIX Clean does not check for updates on its own because it never connects to the network."136137Consequences to keep in mind for each release:138139- Users learn about a new version only from wherever releases are announced; the application cannot tell them.140- The history database has no schema version; a release that changes the schema must handle older files (see141 `docs/architecture/persistence.md`).142- Bump `MARKETING_VERSION` and `CURRENT_PROJECT_VERSION` in `project.yml` before `Scripts/sign.sh`; artifact143 names derive from the bundle version.144145## Not scripted146147- Uploading or publishing the artifacts, release notes and announcement. `docs/release/RELEASE_NOTES.md` is148 maintained by hand.149- An appcast or any update feed.150- Tagging the repository.151- A guard against running `Scripts/package.sh` twice. Running it again after the DMG has been notarized152 deletes and rebuilds the DMG, discarding its notarization; the step after notarizing the DMG is153 `Scripts/finalize.sh`.154