From a60335c841295c3b9f34502b144fd27d4efe804d Mon Sep 17 00:00:00 2001 From: devnull03 <56480041+devnull03@users.noreply.github.com> Date: Sun, 7 Jun 2026 17:03:14 +0530 Subject: [PATCH] Release v0.1.0-alpha.1: bump version and add setup runbook Bump workspace version to 0.1.0-alpha.1 (inherited by all crates) so the tag-driven release.yml version guard passes. Add docs/SETUP.md documenting init steps and the CI/CD pipelines. Co-Authored-By: Claude Opus 4.8 --- Cargo.lock | 8 +-- Cargo.toml | 2 +- docs/SETUP.md | 154 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 159 insertions(+), 5 deletions(-) create mode 100644 docs/SETUP.md diff --git a/Cargo.lock b/Cargo.lock index c301e33..cdf4dcd 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -127,7 +127,7 @@ checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c" [[package]] name = "app" -version = "0.1.0" +version = "0.1.0-alpha.1" dependencies = [ "anyhow", "base64", @@ -5587,7 +5587,7 @@ dependencies = [ [[package]] name = "settings" -version = "0.1.0" +version = "0.1.0-alpha.1" dependencies = [ "anyhow", "dirs 6.0.0", @@ -7235,7 +7235,7 @@ checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f" [[package]] name = "window-wrapper" -version = "0.1.0" +version = "0.1.0-alpha.1" dependencies = [ "gpui", "gpui-component", @@ -7845,7 +7845,7 @@ dependencies = [ [[package]] name = "workbench-integration" -version = "0.1.0" +version = "0.1.0-alpha.1" dependencies = [ "anyhow", "indexmap", diff --git a/Cargo.toml b/Cargo.toml index d2d3f4c..340c23a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -9,7 +9,7 @@ members = [ default-members = ["crates/app"] [workspace.package] -version = "0.1.0" +version = "0.1.0-alpha.1" edition = "2024" [workspace.dependencies] diff --git a/docs/SETUP.md b/docs/SETUP.md new file mode 100644 index 0000000..2030a73 --- /dev/null +++ b/docs/SETUP.md @@ -0,0 +1,154 @@ +# Setup & Release Runbook + +How to stand this project up from scratch and how its CI/CD works. This is the +"do these things first" companion to `README.md` — especially before cutting a +release, since a release depends on several pieces being configured ahead of time. + +--- + +## 1. What's in the repo + +| Branch | Contents | Purpose | +|---|---|---| +| `main` | The Rust **GPUI** desktop app (`crates/*`) + release pipeline | Default branch; source of truth for the app and for tag-driven releases. | +| `dev` | Same app, integration branch | Where day-to-day work lands and CI runs before promoting to `main`. | +| `site` | An **Astro** static site (no Rust) | The public releases page deployed to GitHub Pages. Independent of the app. | + +Workspace crates (versions are inherited from `[workspace.package].version`): +`crates/app` (binary `app`), `crates/settings`, `crates/workbench-integration`, +`crates/window-wrapper`. + +--- + +## 2. Local prerequisites + +**App (on `main`/`dev`):** +- Rust **stable** toolchain — `rust-toolchain.toml` pins the channel and pulls in + `rustfmt` + `clippy`. Run `rustup update stable` periodically to match CI. +- The app only targets **Windows + macOS** (gpui needs heavy system libs on Linux), + so build/test there. +- **Runtime dependency:** the app drives the external + [Islandora Workbench](https://github.com/mjordan/islandora_workbench) Python tool. + End users need `python` + `uv` and that tool installed separately — it is **not** + bundled in the release artifacts. + +**Site (on `site`):** +- Node 20+ and npm. `npm install`, then `npm run dev` + (`http://localhost:4321/islandora_workbench_gui/`). + +--- + +## 3. One-time GitHub setup (do this before the first release) + +These are the "things to set up beforehand" — without them the pipelines fail or +produce nothing visible. + +1. **GitHub Pages → GitHub Actions source.** + Settings → Pages → Build and deployment → Source = **GitHub Actions** + (API `build_type: "workflow"`). Required for `deploy-site.yml` to publish. + *Already enabled for this repo.* + +2. **Actions permissions.** Settings → Actions → General → Workflow permissions: + allow workflows to write (the release job needs `contents: write`; the site + dispatcher needs `actions: write`). These are also declared per-workflow. + +3. **Branch protection (recommended).** Protect `main`: require the `CI` checks + (Windows + macOS) to pass before merge. Note the release **tag** push is not a + PR, so it bypasses protection by design. + +4. **Code signing (optional, currently OFF).** Releases are **unsigned**: + - Windows: SmartScreen "unknown publisher" warning. + - macOS: Gatekeeper quarantine (`xattr -dr com.apple.quarantine ...`). + To sign later you'd add secrets (Apple Developer ID cert + notarization creds, + a Windows code-signing cert) and signing steps in `release.yml`. None exist yet, + so no secrets are required to build today. + +5. **Custom domain (optional).** Settings → Pages writes a `CNAME`; then set + `site:` in `astro.config.mjs` to the domain and drop/empty `base`. + +--- + +## 4. CI/CD pipelines + +Four workflows, two on `main`, one on `site`, and CI on `dev`/PRs. + +### `ci.yml` — quality gate (on `main`) +- **Triggers:** push to `dev`; PRs targeting `dev` or `main`. +- **Does:** on Windows + macOS, runs `cargo fmt --check`, `cargo clippy … -D warnings`, + `cargo test`, `cargo build`. Cancels superseded runs to save minutes. +- **Why it matters:** a PR into `main` (including a release-prep PR) must be green. + +### `release.yml` — build & publish artifacts (on `main`) +- **Trigger:** pushing a tag matching `v*`. Merging to `main` alone does nothing. +- **Guard:** the `version` job asserts the tag (minus `v`) **exactly equals** + `Cargo.toml`'s `[workspace.package].version`. Mismatch ⇒ the build fails fast. +- **Builds:** + - macOS: universal (x86_64 + aarch64) binary → `.app` → `.dmg` + (`scripts/bundle-mac.sh`). + - Windows: `.exe` → portable `*-x86_64.zip` + NSIS `*-setup.exe` + (`scripts/installer.nsi`). +- **Publishes:** a **DRAFT** release with the artifacts + `SHA256SUMS.txt`. It does + **not** set the pre-release flag — you choose that when you publish (§5). + +### `deploy-site.yml` — build & deploy the site (on `site`) +- **Triggers:** push to `site`; `workflow_dispatch`. +- **Does:** `withastro/action` builds the Astro site, which **fetches the release + list at build time** using the job's `GITHUB_TOKEN` (1000 req/hr, no token in the + shipped HTML), then `actions/deploy-pages` publishes it. + +### `redeploy-site-on-release.yml` — refresh the site on release (on `main`) +- **Trigger:** `release: published` (and `workflow_dispatch`). +- **Why it lives on `main`:** `release` events only fire for workflows on the + **default branch**. The site's build is on `site`, so this small workflow bridges + the gap: it runs `gh workflow run deploy-site.yml --ref site`. +- **Net effect:** publishing a release ⇒ the site rebuilds and shows it. + +``` +tag vX.Y.Z ─▶ release.yml (build dmg/zip/exe) ─▶ DRAFT release + │ (you publish, optionally pre-release) + ▼ + release: published + │ + redeploy-site-on-release.yml (on main) + │ gh workflow run --ref site + ▼ + deploy-site.yml (on site) ─▶ Pages updates +``` + +--- + +## 5. Cutting a release (runbook) + +1. **Land the code** on `main` (via PR; CI green). +2. **Bump the version** in `Cargo.toml` `[workspace.package].version` (inherited by + all crates), and sync the lockfile (`cargo metadata` or any cargo build updates + the member versions in `Cargo.lock`). Commit to `main`. +3. **Tag and push** — the tag must match the version exactly: + ```sh + git tag v0.1.0 + git push origin v0.1.0 + ``` +4. **Wait for `release.yml`** to finish; it leaves a **draft** release with the + `.dmg`, `.zip`, `-setup.exe`, and `SHA256SUMS.txt`. +5. **Publish the draft** (Releases → edit the draft → *Publish release*). This is + when the release becomes visible to the API and to the site. +6. Publishing fires `redeploy-site-on-release.yml` → the site rebuilds with the new + release. + +### Pre-releases (alpha / rc / beta) +- Use a **semver pre-release version**, e.g. `0.1.0-alpha.1`, in `Cargo.toml`, and + tag `v0.1.0-alpha.1` (the version guard requires the match — `0.1.0-alpha.1` + is a valid Cargo version). +- When publishing the draft, **check "Set as a pre-release"** (API `prerelease: true`). + The site renders it with a **"Pre-release"** badge and never awards it the + **"Latest"** badge — "Latest" only goes to the newest *stable* (non-pre-release) + release. +- Drafts are hidden from the public API, so an in-progress release never leaks to + the site until you publish it. + +### Rolling back a bad tag +```sh +git push origin :refs/tags/v0.1.0 # delete remote tag +git tag -d v0.1.0 # delete local tag +``` +Then delete the draft/release in the GitHub UI if one was created.