mirror of
https://github.com/stablyai/orca.git
synced 2026-11-16 02:47:34 +00:00
docs: cut dev-environment internals and drop the stale release doc
Trim docs/development.md to the setup steps people actually hit, drop docs/releasing.md in favor of the self-documenting Cut Release workflow, and move the RC Homebrew cask into the README.
This commit is contained in:
@@ -16,7 +16,7 @@ pnpm dev
|
||||
|
||||
`pnpm dev` in a linked Git worktree uses its own profile and ports, so instances in different worktrees run side by side.
|
||||
|
||||
See [`docs/development.md`](../docs/development.md) for per-OS packages, Corepack and Windows notes, dev profiles and seeding, the pnpm global virtual store, cross-architecture and Linux (Docker) builds, and dev server options.
|
||||
See [`docs/development.md`](../docs/development.md) for per-OS packages, Corepack and Windows notes, dev profiles and seeding, cross-architecture and Linux (Docker) builds, and troubleshooting.
|
||||
|
||||
## Branch Naming
|
||||
|
||||
@@ -60,13 +60,13 @@ pnpm test:changed src/main/runtime --maxWorkers=2 # staged, unstaged, and untr
|
||||
pnpm test --changed=origin/main --maxWorkers=2 # also commits since the merge base
|
||||
```
|
||||
|
||||
Affected tests follow Vitest's static import graph, so run suites explicitly for dynamic imports, fixtures, or subprocess inputs. Local affected tests do not replace CI. If a file passes alone but fails after others, add `// @orca-isolated-worker` to it. More detail is in [`docs/development.md`](../docs/development.md#tests-and-dev-server-options).
|
||||
Affected tests follow Vitest's static import graph, so run suites explicitly for dynamic imports, fixtures, or subprocess inputs. Local affected tests do not replace CI. If a file passes alone but fails after others, add `// @orca-isolated-worker` to it.
|
||||
|
||||
## Pull Requests
|
||||
|
||||
Fill in every section of [`.github/pull_request_template.md`](./pull_request_template.md): an ELI5, what changed and why, a linked issue (required for outside contributors), a before and after (screenshots or videos) for any UI or behavior change (only if there is truly no visual or interaction change, write exactly `N/A` and briefly say why), how you tested it, the risk, and under Review a short summary from your AI coding agent covering cross-platform, SSH/remote, agent and integration compatibility, performance, UI quality, and security. Keep each PR small and focused on one topic.
|
||||
|
||||
Version bumps, tags, and releases are maintainer-managed. Do not include release version changes unless a maintainer asks. Maintainers: see [`docs/releasing.md`](../docs/releasing.md).
|
||||
Version bumps, tags, and releases are maintainer-managed. Do not include release version changes unless a maintainer asks. Maintainers cut releases with the [Cut Release](https://github.com/stablyai/orca/actions/workflows/release-cut.yml) workflow.
|
||||
|
||||
## Getting Help
|
||||
|
||||
|
||||
@@ -100,7 +100,6 @@ docs/**
|
||||
!docs/bug-reproductions/**
|
||||
!docs/STYLEGUIDE.md
|
||||
!docs/development.md
|
||||
!docs/releasing.md
|
||||
!docs/styleguide/
|
||||
!docs/styleguide/**
|
||||
!docs/agents-md-refs/
|
||||
|
||||
@@ -272,6 +272,8 @@ _Or via a package manager:_
|
||||
brew install --cask stablyai/orca/orca
|
||||
# Upgrade an existing install
|
||||
brew upgrade --cask stablyai/orca/orca
|
||||
# Release candidates (conflicts with the stable cask; uninstall it first)
|
||||
brew install --cask stablyai/orca/orca@rc
|
||||
|
||||
# Arch Linux (AUR) — or stably-orca-git to build from source
|
||||
yay -S stably-orca-bin
|
||||
|
||||
+19
-145
@@ -1,67 +1,28 @@
|
||||
# Orca Development Environment
|
||||
|
||||
Reference details for working on Orca locally. Start with [`CONTRIBUTING.md`](../.github/CONTRIBUTING.md).
|
||||
Setup details beyond [`CONTRIBUTING.md`](../.github/CONTRIBUTING.md).
|
||||
|
||||
## Toolchain and Native Prerequisites
|
||||
## Prerequisites
|
||||
|
||||
Install Node 24, pnpm, and the Bun version in [`config/.bun-version`](../config/.bun-version).
|
||||
`pnpm test` runs Vitest on Bun, with Node workers for runtime contracts such as SQLite,
|
||||
native PTYs, socket liveness, and V8 memory behavior. `pnpm test:node` runs the same suites
|
||||
entirely on Node. Builds and dependency installation still use Node and pnpm.
|
||||
Install Node 24, the pnpm version in `packageManager` in [`package.json`](../package.json), and the Bun version in [`config/.bun-version`](../config/.bun-version).
|
||||
|
||||
The server, its workers and its packaged dependencies target Node 24. The compatibility
|
||||
launcher and CLI still target Node 18; the launcher hands off to bundled Node 24 before
|
||||
loading server code. WSL guest programs and host discovery retain their Node 18 minimum.
|
||||
Keep Node 24 APIs and server imports out of these host compatibility paths. Running an
|
||||
unpackaged server directly requires Node 24 or newer.
|
||||
`corepack enable` needs Corepack 0.34.5 or newer (`npm install -g corepack@latest`). On Windows it fails with `EPERM` outside an elevated shell when Node is in `C:\Program Files\nodejs`; run `npm install -g pnpm@<that version>` instead.
|
||||
|
||||
Use the pnpm version in `packageManager` in [`package.json`](../package.json): `corepack enable`
|
||||
needs Corepack 0.34.5 or newer to start the pinned pnpm (`npm install -g corepack@latest`). On
|
||||
Windows it writes shims next to `node.exe` and fails with `EPERM` outside an elevated shell when
|
||||
Node is in `C:\Program Files\nodejs`; run `npm install -g pnpm@<that version>` instead.
|
||||
|
||||
`pnpm install` compiles native modules such as `node-pty` with `node-gyp` and loads them in
|
||||
Electron, so a fresh machine also needs:
|
||||
`pnpm install` compiles native modules such as `node-pty`, so a fresh machine also needs:
|
||||
|
||||
- **macOS**: Xcode Command Line Tools (`xcode-select --install`).
|
||||
- **Windows**: Python 3 and Visual Studio Build Tools with the "Desktop development with C++"
|
||||
workload.
|
||||
- **Linux**: a C++ toolchain, Python 3, and the libraries Electron loads even on a headless
|
||||
machine, plus `xvfb`, which the `*.electron.test.ts` files in `pnpm test` use when `DISPLAY` is
|
||||
unset. On Ubuntu 24.04+ and Debian 13+:
|
||||
- **Windows**: Python 3 and Visual Studio Build Tools with the "Desktop development with C++" workload.
|
||||
- **Linux**: a C++ toolchain, Python 3, Electron's libraries, and `xvfb` (used by `*.electron.test.ts` when `DISPLAY` is unset). On Ubuntu 24.04+ and Debian 13+ (older releases name the last package `libasound2`):
|
||||
|
||||
```bash
|
||||
sudo apt-get update && sudo apt-get install -y build-essential python3 xvfb libgtk-3-0 libnss3 libgbm1 libasound2t64
|
||||
```
|
||||
|
||||
Older releases name the last package `libasound2`.
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
`mobile/` is a separate pnpm project with its own lockfile, so the root `pnpm install` leaves its
|
||||
dependencies uninstalled. `pnpm build` (`build:mobile-web` fails without them) and the lint
|
||||
passes that cover `mobile/` need them. Install them before building or linting, and again
|
||||
when `mobile/pnpm-lock.yaml` changes:
|
||||
|
||||
```bash
|
||||
pnpm -C mobile install --frozen-lockfile
|
||||
```
|
||||
Re-run `pnpm -C mobile install --frozen-lockfile` whenever `mobile/pnpm-lock.yaml` changes.
|
||||
|
||||
## Dev Profiles and Parallel Instances
|
||||
|
||||
`pnpm dev` in a linked Git worktree uses its own userData profile, renderer port, and remote
|
||||
debugging (CDP) port, so dev instances in different worktrees run side by side. The main checkout
|
||||
keeps the shared `orca-dev` profile. Ports are derived from the worktree path and move to the next
|
||||
free port when taken: renderer ports start at 15200 and CDP ports at 9333.
|
||||
|
||||
On startup the runner prints one stdout line and writes the same JSON to `out/dev-instance.json`:
|
||||
|
||||
```text
|
||||
ORCA_DEV_INSTANCE {"userData":".../orca-dev-wt/1d3830d4d3","profile":"worktree","rendererPort":15339,"rendererUrl":"http://localhost:15339","cdpPort":9513,"cdpUrl":"http://127.0.0.1:9513","repoRoot":"...","runnerPid":4242}
|
||||
```
|
||||
`pnpm dev` in a linked Git worktree uses its own profile, renderer port (from 15200), and CDP port (from 9333), so worktrees run side by side. The main checkout uses the shared `orca-dev` profile. The chosen profile and ports are printed on an `ORCA_DEV_INSTANCE` line and written to `out/dev-instance.json`.
|
||||
|
||||
| Option | Effect |
|
||||
| ----------------------------------------------------------------------- | ---------------------------------------------------------- |
|
||||
@@ -71,109 +32,22 @@ ORCA_DEV_INSTANCE {"userData":".../orca-dev-wt/1d3830d4d3","profile":"worktree",
|
||||
| `REMOTE_DEBUGGING_PORT=<port>`, `ORCA_DEV_RENDERER_PORT=<port>` | Pin a port |
|
||||
| `pnpm dev --seed-profile[=<dir>]` or `ORCA_DEV_SEED_PROFILE=<dir or 1>` | Seed an empty profile on first launch |
|
||||
|
||||
Per-worktree profiles live in `orca-dev-wt/<hash>` next to `orca-dev` (`~/Library/Application
|
||||
Support` on macOS, `%APPDATA%` on Windows, `$XDG_CONFIG_HOME` or `~/.config` on Linux). The
|
||||
automatic storage cleanup removes them once their worktree is gone and nothing still runs from
|
||||
them. `config/scripts/development/launch/orca-dev.mjs` and the `orca-dev` terminal wrapper target the profile this
|
||||
checkout's `pnpm dev` used.
|
||||
|
||||
Seeding copies a slim set of state from another profile: projects, workspaces, settings, SSH
|
||||
targets, and the Orca account session. Terminal sessions, PTY leases, automations, caches, logs,
|
||||
and lock files are not copied, and the source profile is only read. The default source is
|
||||
`orca-dev`, or the installed app's profile when `orca-dev` is empty. Seed from `orca-dev` when you
|
||||
need the signed-in account session: dev builds cannot decrypt secrets the installed app encrypted.
|
||||
Seeding copies projects, workspaces, settings, SSH targets, and the Orca account session from another profile (default `orca-dev`, else the installed app's). Seed from `orca-dev` if you need to stay signed in: dev builds cannot decrypt secrets the installed app encrypted.
|
||||
|
||||
```bash
|
||||
pnpm dev:seed-profile [--from=<profile dir>] [--to=<profile dir>] [--reset]
|
||||
pnpm dev:fresh [--keep] [--seed-from[=<profile dir>]] # temporary profile, removed on exit
|
||||
```
|
||||
|
||||
## Tests and Dev Server Options
|
||||
## Installs and Builds
|
||||
|
||||
Use a test file or directory when you know the relevant suites. For dependency-based
|
||||
feedback, Vitest can select tests affected by your edits:
|
||||
- Local installs use pnpm's global virtual store (`~/pnpm/store`) shared by all worktrees. Do not keep a `node_modules` in your home directory: it hides missing-dependency bugs. Set `ORCA_PNPM_GLOBAL_VIRTUAL_STORE=0` in your shell to opt out.
|
||||
- Before a cross-architecture build (including `pnpm build:mac`, which builds x64 and arm64), run `pnpm install:release`.
|
||||
- On Linux, `pnpm build`, `pnpm build:native`, and packaging need a running Docker daemon for the clipboard helper. For native Wayland development, run `pnpm build:native` before `pnpm dev`. See the [clipboard build guide](../native/wayland-clipboard/README.md#building-and-testing).
|
||||
|
||||
```bash
|
||||
pnpm test:changed src/main/runtime --maxWorkers=2
|
||||
pnpm test --changed=origin/main --maxWorkers=2
|
||||
pnpm test src/shared/automations/scheduling/automation-cron-input-validation.test.ts --maxWorkers=2
|
||||
```
|
||||
## Troubleshooting
|
||||
|
||||
`test:changed` considers staged, unstaged, and untracked files. `--changed=origin/main`
|
||||
also includes committed changes since the branch's merge base. Update that ref when
|
||||
you need a newer baseline. Both accept the same path filters and options as `pnpm test`.
|
||||
When Git reports no changed files at all, the launcher exits before starting Vitest.
|
||||
|
||||
Affected tests use Vitest's static import graph. Run suites explicitly for computed
|
||||
dynamic imports, fixture files, subprocess inputs, or other dependencies outside that
|
||||
graph. Local affected tests do not replace CI.
|
||||
|
||||
Use `pnpm test`, not raw `vitest`: only it keeps the transform cache that makes repeat runs fast.
|
||||
|
||||
Most unit files share a worker and its module cache with the files before them. After each file
|
||||
the worker undoes mocks, fake timers, stubs, env, cwd, and leftover timers, listeners, and globals.
|
||||
Files using `vi.doMock`, `vi.resetModules`, a DOM environment, or direct `globalThis` writes keep
|
||||
their own worker. If a file passes alone but fails after others, add `// @orca-isolated-worker`
|
||||
to it; `ORCA_VITEST_ISOLATE_EVERY_FILE=1` isolates every file to confirm a leak.
|
||||
|
||||
To reduce main-process rebuild CPU and memory when you do not need its source maps,
|
||||
set `ORCA_DEV_MAIN_SOURCEMAPS=0` before `pnpm dev`. In Bash/zsh:
|
||||
|
||||
```bash
|
||||
ORCA_DEV_MAIN_SOURCEMAPS=0 pnpm dev
|
||||
```
|
||||
|
||||
In PowerShell, use `$env:ORCA_DEV_MAIN_SOURCEMAPS='0'` before `pnpm dev`.
|
||||
Remove the variable when debugging the main process with source maps. Renderer and
|
||||
preload settings are unaffected; production builds always keep their hidden main maps.
|
||||
|
||||
`pnpm dev` serves the renderer with Vite's bundled dev mode: a few bundled chunks instead of
|
||||
thousands of module requests, so the first render and full reloads are faster. While a rebuild is
|
||||
pending, a newly opened pop-out, space, or web window may briefly get placeholder HTML. If the
|
||||
renderer misbehaves, set `ORCA_DEV_BUNDLED=0` (PowerShell: `$env:ORCA_DEV_BUNDLED='0'`) and report it.
|
||||
|
||||
Local installs use pnpm's global virtual store: each package version is one slot
|
||||
under `~/pnpm/store` that every worktree links to, instead of a full `node_modules` per worktree.
|
||||
An existing worktree converts on its next `pnpm install`, and an older branch without the setting
|
||||
converts back the same way. CI always uses the normal layout. On Windows, pnpm links with
|
||||
junctions when you lack the symlink privilege, so no administrator rights or Developer Mode are
|
||||
needed. Things to know:
|
||||
|
||||
- Keep `~/node_modules` (and any other `node_modules` above the store) out of your home
|
||||
directory. Node resolves upward from the store slot, so a stray one there supplies
|
||||
dependencies the package never declared and hides missing-dependency bugs; `pnpm install` warns
|
||||
when it finds one.
|
||||
- Native addons are never rebuilt in place in a shared slot: each CPU gets its own build
|
||||
beside it (see [`native-build-entry.cjs`](../config/scripts/native-build/node-addons/native-build-entry.cjs)), so
|
||||
cross-arch packaging is safe for other worktrees.
|
||||
- `ORCA_PNPM_GLOBAL_VIRTUAL_STORE=0` opts out. Keep it set
|
||||
in your shell: `pnpm run` re-checks the install and relinks a worktree whose layout no longer
|
||||
matches.
|
||||
|
||||
Ordinary installs include native optional dependencies for the current OS and CPU only.
|
||||
Before a cross-architecture build (including `pnpm build:mac`, which produces both x64 and
|
||||
arm64 artifacts by default), run `pnpm install:release` to add the other CPU's variants.
|
||||
|
||||
Linux `pnpm build`, `pnpm build:native`, and Linux packaging require a running Docker
|
||||
daemon to build the clipboard helper against Ubuntu 20.04 rather than the host's
|
||||
newer libraries. A verified cached helper can be reused without Docker. For native
|
||||
Wayland development, run `pnpm build:native` before `pnpm dev` to make text copying
|
||||
available. See the [clipboard build guide](../native/wayland-clipboard/README.md#building-and-testing).
|
||||
macOS and Windows builds do not use this helper or require Docker for it.
|
||||
|
||||
## Lint and Typecheck
|
||||
|
||||
`pnpm lint` runs independent checks in a bounded pool. Use
|
||||
`pnpm lint --maxWorkers=2 --timings` to limit concurrent checks and print their durations.
|
||||
|
||||
For repeated local typechecks, use `pnpm tc` (or `pnpm tc:node`, `pnpm tc:web`,
|
||||
and `pnpm tc:cli`). On Apple Silicon macOS and x64/arm64 Linux, these use the pinned
|
||||
`tsrs` compiler with incremental caches. Keep `.cache/typecheck/` between checks;
|
||||
delete it to force a fresh check. Caches are separate for each project, compiler
|
||||
version, and worktree. At most two projects run together, subject to the memory budget.
|
||||
Windows, Intel macOS, and other unsupported platforms use pinned Bun automatically.
|
||||
Pass `--compiler=bun` to explicitly use Bun, or `--compiler=native` to use TypeScript.
|
||||
CI uses `pnpm typecheck:ci`, which explicitly selects Bun and its CI concurrency.
|
||||
Shared tests are checked by the
|
||||
Node project; shared production code is checked in all three environments.
|
||||
Run `pnpm tc:node` after editing shared tests, or `pnpm tc` to check everything.
|
||||
- Slow main-process rebuilds: set `ORCA_DEV_MAIN_SOURCEMAPS=0` before `pnpm dev` when you don't need main-process source maps.
|
||||
- Renderer misbehaving in dev: set `ORCA_DEV_BUNDLED=0` to turn off bundled dev mode, and report it.
|
||||
- Test passes alone but fails after others: add `// @orca-isolated-worker` to the file; `ORCA_VITEST_ISOLATE_EVERY_FILE=1` isolates every file to confirm a leak.
|
||||
- Slow typechecks: where supported, `pnpm tc` keeps incremental caches in `.cache/typecheck/`; delete it to force a fresh check.
|
||||
|
||||
@@ -1,63 +0,0 @@
|
||||
# Releasing Orca
|
||||
|
||||
## Release Process
|
||||
|
||||
Version bumps, tags, and releases are maintainer-managed. Do not include release version changes in a normal contribution unless a maintainer asks for them.
|
||||
|
||||
### Cutting a release (maintainers)
|
||||
|
||||
All releases are cut from the **Cut Release** GitHub Actions workflow. There is no local `pnpm release:*` script — running releases locally is too easy to get wrong (dirty tree, wrong branch, stale main).
|
||||
|
||||
**To cut a release:**
|
||||
|
||||
1. Open [Actions → Cut Release](https://github.com/stablyai/orca/actions/workflows/release-cut.yml).
|
||||
2. Click **Run workflow** and pick:
|
||||
- **kind**: one of `rc`, `patch`, `minor`, `major`.
|
||||
- **ref**: the branch, tag, or SHA to build from. Defaults to `main`.
|
||||
3. Run it.
|
||||
|
||||
The workflow resolves the next version from GitHub Releases, bumps `package.json`, tags, pushes, and runs the multi-platform build + publish inline.
|
||||
|
||||
**How the next version is chosen:**
|
||||
|
||||
All stable kinds (`patch`, `minor`, `major`) are computed off the latest _stable_ release, ignoring any RCs in between.
|
||||
|
||||
- `kind=rc` + last tag was stable (e.g. `v1.3.14`) → `v1.3.15-rc.0`.
|
||||
- `kind=rc` + active RC series (e.g. `v1.3.15-rc.2`) → `v1.3.15-rc.3`.
|
||||
- `kind=patch` + latest stable `v1.3.14` → `v1.3.15` (regardless of any intermediate RCs).
|
||||
- `kind=minor` + latest stable `v1.3.14` → `v1.4.0`.
|
||||
- `kind=major` + latest stable `v1.3.14` → `v2.0.0`.
|
||||
|
||||
**Safety guarantees:**
|
||||
|
||||
- Stable releases are refused if the new version isn't strictly greater than the latest published stable. This is the only rule `electron-updater` actually needs — it compares semver within the `latest` channel, so a regressing stable is the one thing that breaks auto-update for fresh installs.
|
||||
- Complete RC draft releases created by the release workflow are published before cutting a new tag only when the draft tag was built from the current release ref. Stale drafts are skipped so fixes cut a fresh RC instead of exposing old artifacts.
|
||||
- If the latest RC tag exists but is still draft-only or missing its GitHub Release, the workflow resumes that tag only when it was built from the current release ref. Otherwise the next RC number is cut.
|
||||
- RC numbering also considers release commits on `main`, so deleting a stale tag does not let a later cut reuse the same RC number.
|
||||
- Off-main releases (when `ref` is not the tip of `main`) only push the tag. `main` is never mutated from a non-main ref, so you can safely release an older commit without polluting history.
|
||||
- When `ref` is the tip of `main`, the workflow tries to fast-forward the version-bump commit onto `main`. If main requires pull requests, it leaves main unchanged and pushes only the release tag. Other push errors still stop the cut.
|
||||
|
||||
**Common scenarios:**
|
||||
|
||||
- **Normal release:** `kind=patch`, `ref=main`.
|
||||
- **"A bad commit just landed on main, release the commit before it":** `kind=patch`, `ref=<good-sha>`. `main` is left alone; the tag points at the good SHA. Fix forward on `main` afterward.
|
||||
- **One-off RC for a feature branch:** `kind=rc`, `ref=<branch-or-sha>`. Produces an RC tag that does not touch `main`.
|
||||
- **Minor or major bump:** `kind=minor` or `kind=major`.
|
||||
|
||||
## Release Channels
|
||||
|
||||
The public Homebrew cask tracks stable desktop releases:
|
||||
|
||||
```bash
|
||||
brew install --cask stablyai/orca/orca
|
||||
```
|
||||
|
||||
Release candidates use a separate cask token:
|
||||
|
||||
```bash
|
||||
brew install --cask stablyai/orca/orca@rc
|
||||
```
|
||||
|
||||
The two casks conflict because both install `Orca.app`. Switch channels with a
|
||||
normal `brew uninstall --cask` followed by the install for the other channel.
|
||||
Do not use `--zap` unless you intentionally want to remove local Orca state.
|
||||
Reference in New Issue
Block a user