mirror of
https://github.com/storytold/materialcraft.git
synced 2026-11-19 14:01:02 +01:00
storytold/materialcraft#2 keeps FreeBSD by building it on a larger runner instead; this skip conflicts with it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
178 lines
10 KiB
Markdown
178 lines
10 KiB
Markdown
# Releasing MaterialCraft
|
|
|
|
The recipe is craftrules' [release playbook](release-playbook.md); this page covers what is
|
|
specific to MaterialCraft. The pipeline is [`.github/workflows/release.yml`](../.github/workflows/release.yml).
|
|
|
|
## Release manager checklist
|
|
|
|
The steps below are the release manager's; agents never create the `release` branch, tags or
|
|
GitHub Releases. The shared runbook with copy-paste `gh` commands is craftrules
|
|
`release/cut-a-release.md`.
|
|
|
|
### 1. One-time repository setup (org admin)
|
|
|
|
Status on 2026-10-23: `storytold/materialcraft` has the `release` environment (deployable from
|
|
`release` only) and the `release` ruleset (steps 1 and 2 below). Still to do before the first run:
|
|
the secrets (step 3) and the runner group (step 4); the `release` branch is created by the first
|
|
release push. An org admin runs craftrules `release/signing-setup.md` steps 1-2 for this repo:
|
|
|
|
1. Create the **`release` environment**, with deployment branches limited to `release`.
|
|
2. Add the **ruleset on `refs/heads/release`** (restrict creations, updates and deletions, block
|
|
force pushes; bypass: the `release-managers` team and the Organization admin role).
|
|
3. Set these **environment secrets** on `release` (`gh secret set <NAME> --env release -R
|
|
storytold/materialcraft`). Never as org- or repo-level Actions secrets: only the `release`
|
|
environment keeps them away from other branches.
|
|
|
|
| Secret | Read by |
|
|
|---|---|
|
|
| `APPLE_CERTIFICATE`, `APPLE_CERTIFICATE_PASSWORD`, `KEYCHAIN_PASSWORD` | macOS: Developer ID certificate into a temporary keychain |
|
|
| `APPLE_ID`, `APPLE_PASSWORD`, `APPLE_TEAM_ID` | macOS: notarization (`notarytool`) and its verification |
|
|
| `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_SIGNING_ENDPOINT`, `AZURE_SIGNING_ACCOUNT`, `AZURE_CERT_PROFILE` | Windows: Azure Trusted Signing (the org's method) |
|
|
| `WINDOWS_CERTIFICATE`, `WINDOWS_CERTIFICATE_PASSWORD` | Windows: a `.pfx` instead of Azure; takes precedence when set. Leave unset |
|
|
|
|
Those twelve (`APPLE_*` and `KEYCHAIN_PASSWORD`, `AZURE_*`) are all a signed release needs;
|
|
`GITHUB_TOKEN` is provided by Actions.
|
|
4. Add the repo to the org's **Default runner group** (Settings → Actions → Runner groups). The
|
|
macOS job (`macos-15-xlarge`) and the FreeBSD job (`github-ubuntu-16core`) run on larger runners,
|
|
which only serve repos in that group; outside it they wait for a runner forever, with no error.
|
|
|
|
### 2. Set the version
|
|
|
|
On `main`:
|
|
|
|
```sh
|
|
cargo xtask version # prints the current version
|
|
cargo xtask version set 0.2.0 # or 0.2.0-rc.1 for a pre-release
|
|
```
|
|
|
|
`set` rewrites `[workspace.package] version` in the root `Cargo.toml` (the single source of truth)
|
|
and refreshes `Cargo.lock`. Commit, push, and wait for CI on `main` to pass.
|
|
|
|
### 3. Cut the release
|
|
|
|
Fast-forward `release` to `main` and push it (only the `release-managers` team and org admins can):
|
|
|
|
```sh
|
|
git fetch origin
|
|
git push origin origin/main:refs/heads/release
|
|
```
|
|
|
|
That push runs `release.yml`, and also `freebsd.yml` and `windows-arm64.yml` (build, test, install
|
|
checks). A version with a hyphen becomes a pre-release. To test without bumping, dispatch
|
|
`release.yml` on `release` with `version` set (e.g. `0.2.0-rc.1`); a dispatch on any other branch
|
|
is a dry run (Linux, Flatpak, FreeBSD and web build; the signing jobs are refused by the
|
|
environment, so no draft is made).
|
|
|
|
### 4. Wait for green and verify
|
|
|
|
```sh
|
|
RID=$(gh run list -R storytold/materialcraft -w release.yml -L1 --json databaseId --jq '.[0].databaseId')
|
|
gh run watch $RID -R storytold/materialcraft
|
|
gh run view $RID -R storytold/materialcraft --log | grep -E "status: Accepted|staple and validate action worked|::warning"
|
|
```
|
|
|
|
- Every job is green, and no `::warning::` names a missing secret (that platform shipped unsigned:
|
|
fix the secret and re-run, don't publish).
|
|
- macOS: two `The staple and validate action worked!` lines (app and DMG) and `status: Accepted`.
|
|
- The draft `MaterialCraft v<version>` exists, targets the commit you pushed, and carries every
|
|
file in the table below plus `SHA256SUMS.txt`.
|
|
- Download, check and launch at least one artifact per platform:
|
|
- Windows: `signtool verify /pa /v materialcraft-<v>-windows-x64.msi` succeeds and names the
|
|
org's publisher; install, open a `.mcraft` by double-click, `materialcraft-cli --version` from the
|
|
install dir, uninstall.
|
|
- macOS: `spctl -a -vvv -t install materialcraft-<v>-macos-universal.dmg` says *Notarized
|
|
Developer ID*; the app opens with no Gatekeeper prompt.
|
|
- Linux: `sha256sum -c SHA256SUMS.txt --ignore-missing`, then run the AppImage and install the
|
|
`.deb` or `.rpm`; `materialcraft --version`, `materialcraft-cli --version`.
|
|
- Web: unzip `materialcraft-web-<v>.zip`, serve it (`python3 -m http.server`), open it in a
|
|
WebGPU browser.
|
|
|
|
### 5. Publish
|
|
|
|
Review the generated notes, then publish the draft (`gh release edit v<version> -R
|
|
storytold/materialcraft --draft=false --latest`, or `--prerelease` for an rc). A draft is updated in
|
|
place by a re-run; a published release is never overwritten, so bump the version before building
|
|
again.
|
|
|
|
## What gets built
|
|
|
|
All file names are `materialcraft-<version>-<platform>-<arch>.<ext>`, written to `dist/release/`.
|
|
|
|
| Platform | Artifacts | Script |
|
|
|---|---|---|
|
|
| macOS universal (`macos-15-xlarge`) | `-macos-universal.dmg` (`MaterialCraft.app`), `materialcraft-cli-<version>-macos-universal.zip` | `packaging/macos/package.sh`, `verify.sh` |
|
|
| Windows x64, x86, arm64 | `-windows-<arch>.msi`, `-windows-<arch>-portable.zip` | `packaging/windows/package.ps1` |
|
|
| Linux x86_64, aarch64 (Ubuntu 22.04, glibc 2.35) | `.AppImage` + `.AppImage.zsync`, `.deb`, `.rpm`, `.tar.gz` | `packaging/linux/package.sh` |
|
|
| Flatpak x86_64, aarch64 | `-linux-<arch>.flatpak`, repackaged from the Linux tarball | `packaging/linux/flatpak-bundle.sh` |
|
|
| FreeBSD x86_64 (14.3 VM on `github-ubuntu-16core`) | `-freebsd-x86_64.tar.gz` | `packaging/freebsd/package.sh` |
|
|
| Web | `materialcraft-web-<version>.zip` (trunk, `wasm-release` profile; hosting notes in `packaging/web/README.md`) | `packaging/web/package.sh` |
|
|
|
|
Every desktop package ships both binaries, `materialcraft` and `materialcraft-cli` (on macOS the CLI
|
|
is its own zip next to the DMG). Release builds pass the craft-fonts reference (`CRAFT_FONTS_REF` in `release.yml`); MaterialCraft
|
|
does not embed CJK fonts yet (see docs/localization-parity.md). The packaging
|
|
scripts smoke-test `materialcraft-cli --version`, and the Linux job also runs the AppImage with
|
|
`--version`, so both binaries must print their version and exit without opening a window.
|
|
|
|
## MaterialCraft-specific values
|
|
|
|
| What | Value |
|
|
|---|---|
|
|
| Bundle / app id | `ai.storyteller.materialcraft` |
|
|
| Package format | `.mcraft`, MIME `application/x-materialcraft`, UTI `ai.storyteller.materialcraft.package` (owned). Declared in `materialcraft.wxs`, `Info.plist.in`, the `.desktop` file, `mime.xml` and the AppStream metainfo: keep all five in step |
|
|
| WiX UpgradeCode | `89DE105E-B6C8-4261-ADBE-25BCFA3A0C91`, never change it |
|
|
| Flathub manifest | `packaging/linux/flatpak/ai.storyteller.MaterialCraft.yml` (release bundle: `…MaterialCraft.bundle.yml`) |
|
|
| macOS minimum | 11.0 (`LSMinimumSystemVersion`, `MACOSX_DEPLOYMENT_TARGET`) |
|
|
|
|
## Version and build info in the binaries
|
|
|
|
`apps/materialcraft/build.rs` (also `include!`d by `apps/materialcraft-cli/build.rs`) sets, for
|
|
`env!`:
|
|
|
|
- `MATERIALCRAFT_BUILD_SHA`: the full commit. CI sets it to `github.sha`; `packaging/env.sh` sets
|
|
it from git; otherwise build.rs asks git itself; empty when unknown.
|
|
- `MATERIALCRAFT_BUILD_DATE`: `YYYY-MM-DD` (UTC). CI sets it once per run; otherwise today's date,
|
|
or `SOURCE_DATE_EPOCH`'s for reproducible builds.
|
|
|
|
On Windows targets it also embeds `assets/app-icon/materialcraft.ico` and VERSIONINFO
|
|
(ProductName MaterialCraft); `package.ps1` sets `MATERIALCRAFT_REQUIRE_WINRES=1` so a release can't
|
|
ship an exe without them. The version itself is `CARGO_PKG_VERSION`.
|
|
|
|
Other environment variables the scripts read: `MATERIALCRAFT_VERSION` (override the version),
|
|
`DIST`, `CARGO_TARGET_DIR`, `MATERIALCRAFT_MAINTAINER` (deb/rpm maintainer),
|
|
`MATERIALCRAFT_WASM_MAX_BYTES` (web size gate, default 24 MiB), and at run time
|
|
`MATERIALCRAFT_NO_DESKTOP_INTEGRATION=1` (the AppImage's AppRun skips installing its `.desktop`
|
|
entry and icons).
|
|
|
|
## Signing
|
|
|
|
Secrets live only in the `release` environment and are all optional: a missing one gives an
|
|
unsigned artifact and a `::warning::`, never a failed build.
|
|
|
|
- macOS: `APPLE_CERTIFICATE`, `APPLE_CERTIFICATE_PASSWORD`, `KEYCHAIN_PASSWORD` (import into a
|
|
temporary keychain, `packaging/macos/import-cert.sh`), then `APPLE_ID`, `APPLE_PASSWORD`,
|
|
`APPLE_TEAM_ID` for `notarytool` and stapling. Without them the app is ad-hoc signed.
|
|
- Windows: `packaging/windows/sign.ps1` uses a PFX (`WINDOWS_CERTIFICATE`,
|
|
`WINDOWS_CERTIFICATE_PASSWORD`) if set, otherwise Azure Trusted Signing (all six `AZURE_*`).
|
|
It signs both exes before WiX and the MSI after.
|
|
|
|
## Icons
|
|
|
|
`assets/app-icon/materialcraft.svg` is the engraved rhino (the owner's original drawing, vectorised
|
|
to three colours, craftrules `standards/icon-design.md`); `materialcraft-small.svg` is a lighter
|
|
trace for the hicolor scalable icon. `packaging/icons.sh` renders everything else with resvg and
|
|
`cargo xtask ico|icns`: the hicolor PNGs (16-512 px) and scalable SVG, `materialcraft-1024.png`,
|
|
`materialcraft.ico` and `materialcraft.icns`. The outputs are committed; rerun it after changing the
|
|
artwork and keep `ATTRIBUTION.md` in step. See `assets/app-icon/README.md`.
|
|
|
|
## Local checks
|
|
|
|
- `cargo xtask ci`: fmt, clippy, tests, `cargo xtask layers`, `cargo xtask wasm`.
|
|
- `bash packaging/linux/apprun-test.sh` and `bash packaging/freebsd/package.sh --dry-run` run
|
|
anywhere with bash.
|
|
- `packaging/macos/package.sh --arch aarch64` on a Mac builds an ad-hoc signed DMG.
|
|
- `pwsh packaging/windows/package.ps1 -Arch x64` on Windows (needs WiX 5.0.2) builds an unsigned
|
|
MSI and portable zip. Use PowerShell 7 as CI does: Windows PowerShell 5.1 with redirected output
|
|
turns cargo's stderr into an error, so there build with cargo first and pass `-SkipBuild`.
|
|
- `.github/workflows/packaging-lint.yml` runs actionlint, shellcheck, the PowerShell parser and
|
|
the desktop/AppStream/Flatpak validators on every change to `packaging/` or the workflows.
|