# Contributing Bug fixes, documentation improvements, performance work, focused features, and thoughtful ideas are welcome. This is the canonical guide for building OmniWM and submitting a change, also available [on the website](https://omniwm.app/developers/contributing/). For larger changes, open an issue or discussion first so we can agree on direction. Documentation-only contributions do not require building the app. For website changes, follow the [website development guide](website/README.md). ## Quick Start ### 1. Install Xcode Building OmniWM requires an **Apple Silicon Mac running macOS 27**, **Xcode 27** for the macOS SDK and signing tools, and the **Swift toolchain pinned in `.swift-version`**. The released OmniWM app still supports macOS 26.0 or later. Install Xcode from [Apple Developer Downloads](https://developer.apple.com/download/all/), open it, and finish its first-launch setup. In **Xcode → Settings → Locations → Command Line Tools**, select Xcode 27. The standalone Command Line Tools package is not a substitute for this Xcode installation. Install [swiftly](https://www.swift.org/install/macos/) to manage the pinned Swift toolchain. ### 2. Fork, Clone, and Create a Branch Click **Fork** on [the OmniWM repository](https://github.com/OmniNull/OmniWM), then clone your fork. Replace `YOUR-USERNAME` with your GitHub username: ```bash git clone https://github.com/YOUR-USERNAME/OmniWM.git cd OmniWM git remote add upstream https://github.com/OmniNull/OmniWM.git git fetch upstream git switch -c my-change upstream/main ``` Use a descriptive branch name in place of `my-change`. Each contribution should start from `main` and focus on one problem. From the repository directory, install and confirm the pinned toolchain: ```bash swiftly install swift --version ``` The result must report the Swift 6.5 development snapshot named in `.swift-version`. ### 3. Set Up Dependencies ```bash make setup ``` Setup needs [Lix](https://lix.systems/install/) (or another Nix with flakes). It builds the repository's `flake.nix`: the pinned, prebuilt GhosttyKit is linked at `Frameworks/GhosttyKit.xcframework` and checked against its checksum, and the pinned SwiftFormat, SwiftLint, Python, Fish and Nushell are linked at `.cache/flake-tools`. **You do not need to compile GhosttyKit**, and no Homebrew installation is required. `nix develop` opens a shell with the same tools on `PATH`. With [direnv](https://direnv.net), `direnv allow` loads that shell whenever you enter the checkout. Tool versions and download checksums are recorded in [Scripts/dev-tools.env](Scripts/dev-tools.env), which the flake reads; other packages are pinned by `flake.lock`. Ghostty's internal archive pin remains in [Scripts/build-metadata.env](Scripts/build-metadata.env). Setup preserves an existing framework that does not match the pin and explains the mismatch instead of overwriting it. Setup does not launch OmniWM or change privacy permissions, login items, or CLI links. ### 4. Optionally Create a Signing Certificate For repeated development, [create the local signing certificate below](#optional-signing-certificate). A stable signing identity helps macOS retain the Dev app's permissions across rebuilds. It needs no paid Apple Developer membership. You can skip this and run Dev immediately. Without the certificate, the build uses ad-hoc signing and warns that you may need to grant permissions again after rebuilding. ### 5. Build and Run Dev ```bash make run ``` This builds your checked-out code, packages and signs **OmniWM Dev.app**, installs it at `~/Applications/OmniWM Dev.app`, and opens it. It builds before quitting the running OmniWM copy; if that copy cannot quit, installation stops with an error. Your normal OmniWM app remains installed. Only one copy runs at a time. On first launch, grant **Accessibility** and **Input Monitoring** to **OmniWM Dev** in the permissions window. **Screen Recording** is optional for capture-derived visuals such as Overview thumbnails. Dev has its own permissions, separate from your normal app. Follow any restart prompt after granting permissions, then return to the permissions window and click **Start OmniWM** or **Continue Without Screen Recording**. Edit code in your preferred editor, then run `make run` again to rebuild. You can also launch the installed Dev app from Finder. ### 6. Verify and Open a Pull Request For app code changes, run: ```bash make verify swift test ``` `make verify` checks formatting, lint, and the build. **It does not run tests.** See [verification](#verification) for runtime changes and website checks. Commit your change, push your branch to your fork, and open a pull request targeting **`OmniNull/OmniWM:main`**. A draft PR is welcome when you want early feedback. Explain the problem, the resulting behavior, and what you verified; say what you could not check and why. ## Everyday Commands | Command | Result | | --- | --- | | `make setup` | Check prerequisites and obtain the pinned dependencies. | | `make doctor` | Diagnose tools, dependencies, signing, and app paths without changing them. | | `make hooks` | Enable the pre-commit hook: SwiftFormat and SwiftLint on staged Swift files, and a warning when a pinned download in `Scripts/dev-tools.env` is not public yet. | | `make build` | Build the app without installing or launching it. | | `make run` | Build, sign, install, and switch to Dev; alias for `make dev-install`. | | `make use-dev` | Switch to the installed Dev app without rebuilding. | | `make use-release` | Switch back to the normal app at `/Applications/OmniWM.app`. | If your normal app is elsewhere, set its path when switching: ```bash OMNIWM_RELEASE_APP="$HOME/Applications/OmniWM.app" make use-release ``` The development commands do not install the normal release. If you need it, follow the [installation guide](https://omniwm.app/guides/install/). ## Separate Settings and State The installed Dev app has the fixed identity `com.barut.OmniWM.dev`, which selects its own storage directories even when launched from Finder: | Data | Normal app | Dev app | | --- | --- | --- | | Settings | `~/.config/omniwm/settings.toml` | `~/.config/omniwm-dev/settings.toml` | | Saved state | `~/.local/state/omniwm/` | `~/.local/state/omniwm-dev/` | | OmniWM diagnostics | `~/.local/state/omniwm/diagnostics/` | `~/.local/state/omniwm-dev/diagnostics/` | On first installation, the helper copies your normal `settings.toml` into an independent Dev file. Existing Dev settings are preserved, and later edits are never synchronized. If no normal settings file exists, Dev uses its defaults. Saved state and clipboard history start fresh; they are not copied. Absolute `XDG_CONFIG_HOME` and `XDG_STATE_HOME` values replace the corresponding base directories, with `omniwm` or `omniwm-dev` appended. Relative values are ignored. These variables must be available to the app process: a variable set only in a Terminal session is not automatically available to a Finder launch. Keep **Start at Login** disabled in Dev. The helper does not change login registration. Dev can still display normal release-update notifications; installing a stable update does not rebuild your development code. Use `make run` to rebuild Dev. ### Testing the CLI Both copies use the same IPC socket, so an existing `omniwmctl` command talks to whichever copy is running. Enable IPC in that copy's settings when testing CLI commands. To test the CLI built from your changes, invoke it directly: ```bash "$HOME/Applications/OmniWM Dev.app/Contents/MacOS/omniwmctl" --help ``` Setup and switching do not change CLI links. Dev's **Install CLI** setting can create a link to its bundled CLI when no conflicting link exists; use the embedded path above to leave your normal CLI setup alone. ## Optional Signing Certificate Create one certificate and reuse it for future builds: 1. Open **Keychain Access** using Spotlight and select the **login** keychain. 2. Choose **Keychain Access → Certificate Assistant → Create a Certificate**. 3. Set **Name** to `OmniWM Dev`, **Identity Type** to **Self Signed Root**, and **Certificate Type** to **Code Signing**. 4. Click **Create**, accept the self-signed certificate prompt, and click **Done**. Keep the certificate and its private key in your login keychain. 5. Double-click the certificate, expand **Trust**, and set **Code Signing** to **Always Trust**. Close the window and confirm the change if prompted. 6. Run `make doctor`, then rebuild with `make run`. See Apple's [certificate creation guide](https://support.apple.com/guide/keychain-access/create-self-signed-certificates-kyca8916/mac) and [code-signing instructions](https://developer.apple.com/library/archive/documentation/Security/Conceptual/CodeSigningGuide/Procedures/Procedures.html) for background. If macOS asks whether `codesign` may access this certificate's private key while building, allow that access. To use an existing local code-signing identity with another name: ```bash OMNIWM_SIGNING_IDENTITY="Your Certificate Name" make run ``` ## Verification Run `make format` to apply formatting and the required license headers. Run `make verify` afterward to check formatting, lint, localization catalogs, and an arm64 debug build. The commands use the versions installed by `make setup`. Localization checks and synchronization generate compiler metadata with the selected Xcode installation's default Swift toolchain in `.build/localization`. This separate incremental build supports localization extraction even when `swift` on your PATH selects a standalone toolchain that does not emit the metadata. Every Swift source and test file starts with the two-line GPL-2.0 header enforced by SwiftFormat. Preserve that header. `Package.swift` keeps its `swift-tools-version` directive on line one. Keep contributions in Swift, and avoid additional source comments; use clear names and structure. Use focused regression tests for changed behavior. Runtime changes require the full serial `swift test` suite, and changes affecting concurrency also require `swift test --parallel`. Live tests that depend on the machine compile only when `OMNIWM_LIVE_CHECKS` is set, so the default suite never skips them. For motion, focus, layout, and other visible behavior, also describe the manual checks you performed. Shell render speed benchmarks are opt-in because their production CPU-budget verdict depends on the machine and its load. Run them with the pinned toolchain: ```sh LIBRARY_PATH="$(./Scripts/ghostty-preflight.sh print-library-dir)${LIBRARY_PATH:+:$LIBRARY_PATH}" \ OMNIWM_LIVE_CHECKS=1 "$HOME/.swiftly/bin/swift" test --arch arm64 --filter testRenderSpeed ``` The default suite keeps the corresponding functional assertions without a render CPU limit and still checks runaway-script containment. The app's production CPU budget is unchanged. CI takes Fish and Nushell from the flake to run the native CLI completion tests. For the same coverage locally, run `swift test` inside `nix develop`; tests fail with a message if a shell is missing. For changes to setup, packaging, development installation, or related tooling, also run `make test-dev-tools`. This runs the Python development-tooling tests and is included in CI's **Tooling** job. CI also checks that the generated IPC wire encoders match their models. After changing IPC models or the generator, run `python3 Scripts/generate_ipc_wire.py --check`. If it reports stale files, run `python3 Scripts/generate_ipc_wire.py`, review the generated diff, and rerun the check. ### Translating the App Translations live in the [string catalogs](Sources/OmniWM/Resources). `Localizable.xcstrings` contains interface text, `Commands.xcstrings` contains command names, categories, and scopes, `InfoPlist.xcstrings` contains the macOS permission descriptions, and `Shell.xcstrings` contains built-in OmniShell widget text. Add or edit your language's `localizations` entries in those files. Keep the English keys and source values intact, and translate the meaning in context. English is the fallback for strings without a translation. Preserve each format argument's type when translating. You may reorder arguments with positional forms such as `%2$@` and `%1$lld`; a `%lld` count cannot become `%@`. Plural branches may omit a count when the wording does not need it. `make verify` checks format arguments, including plural forms, before a translation is accepted. To preview length and direction issues, use Xcode's localization pseudolanguages or change the app language in macOS settings. If you change localized Swift source text, run `make localization-sync` to build and update the catalogs from compiler-extracted strings, then review the catalog diff. `make verify` fails when source and catalogs differ. For translation-only changes, edit the catalogs directly and run `make verify` and `make test-dev-tools`. This SwiftPM repository has no Xcode project for XLIFF export and import; contribute the catalog files directly. See Apple's [string catalog guide](https://developer.apple.com/documentation/xcode/localizing-and-varying-text-with-a-string-catalog) for the catalog format and plural variations. Before adding the first translation for a new language, translate every desktop string in all four catalogs and have a fluent speaker review the result in the packaged app. Add its cardinal plural categories to `PLURAL_CATEGORIES` in `Scripts/localization.py`, then run `python3 Scripts/localization.py completeness --locales fr de` with the locale codes you are adding; this optional audit requires a nonblank string marked `translated` for every nonempty key and each required plural branch. A partial catalog activates that language for macOS users as soon as it ships. After a language is established, newly added strings may temporarily fall back to English while translations catch up. Website changes use the checks in [website/README.md](website/README.md): `npm run reference:check`, `npm run check`, and `npm run build` from `website/`. Small documentation-only changes do not need app builds or Swift tests. GitHub's **OmniWM CI** workflow reports **Tooling** (flake check, formatting, lint, generated IPC files and `make test-dev-tools`), **Verify** (`make arc-audit`, which fails on any retain, release or allocation in the exercised `OmniWMShellCore` workload, then localization and build) and **Tests** (the Swift suite) separately. It doesn't run when a change only touches `docs/`, `website/` or top level Markdown files; website changes get the **Website** workflow instead. On a pull request that only changes Python directly under `Scripts/` or `Tests/DevToolingTests/` (with or without docs), **Tests** is skipped, since **Tooling** already tests those. **Verify** builds the app and test bundle once and uploads it, and **Tests** runs that build as four parallel shards, **Tests (shard 1)** to **Tests (shard 4)**, with `swift test --skip-build`; it passes once Verify and every shard have. Verify starts from the newest `.build/localization` cache that **Cache dependencies** saved on `main`, and `Scripts/restore-mtimes.py` dates every source by the last commit on `main` that changed it and marks the files changed since the cached build's commit as new, so only those files rebuild. Pull requests only read that cache. Only the shard holding the completion and launcher shell suites (`SHELL_SUITES` in the planner) installs fish and Nushell from the flake, so a new suite that needs real shells belongs in that set. `Scripts/ci_test_plan.py` packs suites into shards by their CI seconds in `Scripts/ci-suite-seconds.json`, and the last shard skips every suite the others filter, so a new suite always runs; when the shards drift apart, run `gh run view --log | python3 Scripts/ci_test_plan.py seconds`, which merges that run's suite seconds into the file and keeps suites the run did not reach. A pull request that only changes Swift files under `Tests/OmniWMTests/` runs just the suites those files reach as **Tests (selected N)**, split into more than one shard only when they outweigh one. It runs every group instead when a reached file has no type declaration, declares a non-private top-level function or variable, extends a type that no test file declares, or opens a top-level `#if OMNIWM_LIVE_CHECKS` block, or when the selection reaches more than half the suites. Pushes to `main` always run every group, and every run renders a reduced grid for the slowest glass sweeps unless a full-grid variable is set (see the [architecture notes](website/src/content/docs/developers/architecture.md)). Tests are initially advisory while the hosted environment is established; a failing test still needs an explanation. On a first contribution, a maintainer may need to [approve the workflow run](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/approve-runs-from-forks) before checks start. A pending approval does not mean you did something wrong. ## Troubleshooting Start with `make doctor` and the first error reported by the failing command. - **Wrong Swift version:** from the repository directory, run `swiftly install` and check `swift --version` against `.swift-version`. Ensure swiftly's `bin` directory is on `PATH`. Use `make doctor` to check the Swift toolchain and selected Xcode installation separately. - **Missing dependencies:** run `make setup`. If an existing GhosttyKit fails its checksum, move your custom framework aside before running setup again; the helper will not replace it for you. - **Permissions requested again:** check the signing identity with `make doctor`, rebuild with the same valid certificate, and grant Dev's permissions again when prompted. Stable and Dev permissions are separate. - **Switching stops because OmniWM is still running:** quit that copy from its menu, then retry. The helper does not force-kill it or install over a running copy. - **Normal app not found:** install the release or supply `OMNIWM_RELEASE_APP` as shown above. ## Pull Request Expectations - Keep changes focused. Explain the current problem and why your approach solves it; refactors need a concrete reason. - Include verification results, including any checks you could not run. Add screenshots, recordings, or CLI examples when useful. - Update documentation when behavior, configuration, workflows, or interfaces change. - Create your change branch from `main` and target `main`. There is no permanent `develop` branch. - Contributor PRs are normally integrated with merge commits so their commit history and authorship remain intact. You do not need to squash or perfect your history before asking for review. Reviewed development lands on `main`; published releases come from version tags. Merging a PR does not itself update users' installed apps. Work that merges to `main` outside a PR, such as a release branch, needs a name ending in `-release` so the same CI runs on every push to it. ### Releases Releases use the **OmniWM release** workflow, dispatched from `main` in two runs: `prepare` with the version number, then `publish` with the prepare run ID and final release notes. Preparation requires BarutSRB's approval of the `release-signing` environment. Publication requires a separate BarutSRB approval of `release-publish`, after reviewing the exact artifact ID, release commit, asset checksums, and final notes in the validation job summary. The publish job downloads that same artifact by ID. Each prepare run first resolves the newest commit on Ghostty's upstream `main` and builds that exact revision in a separate job with no Apple credentials and a read-only repository token. It uses the released Zig version declared by that Ghostty revision, verifies the official compiler download, and runs `zig build -Doptimize=ReleaseFast -Demit-macos-app=false -Dxcframework-target=native` on Apple Silicon. There is no scheduled update. The source revision, compiler, build arguments, and framework checksums are saved as provenance. Preparation installs that framework on its disposable runner, runs `make verify` and both serial and parallel Swift tests against it, and includes its new source and binary pins in the release commit. An upstream build or compatibility failure stops preparation. Publication reuses the tested framework without checking upstream again. It restores the prepared ZIP before dependency setup, then verifies the public download before pushing the new pins to `main`. Ordinary `make setup` continues downloading the prebuilt framework for its checkout; contributors do not need Zig. Both environments must allow only the `main` branch, list **BarutSRB** as their sole required reviewer, and disable administrator bypass. Leave **Prevent self-review** off so BarutSRB can also approve a personally dispatched run. The workflow checks this configuration before preparation and again before publication; missing or weakened protection stops the run. Repository administrators remain able to change environment settings, so administrator access must remain trusted. Store these secrets in **Settings → Environments → release-signing** for stable releases and **canary-signing** for canary builds, with no repository-level duplicates: - `APPLE_DEVELOPER_ID_CERT_P12_BASE64` and `APPLE_DEVELOPER_ID_CERT_PASSWORD`: the Developer ID certificate and its export password, produced with `base64 -i cert.p12 | pbcopy`. - `APPLE_NOTARY_KEY_ID`, `APPLE_NOTARY_ISSUER_ID`, and `APPLE_NOTARY_KEY_P8`: the App Store Connect API key ID, issuer ID, and raw `.p8` contents (`pbcopy < AuthKey_XXXX.p8`). A normal trailing newline is accepted. The `release-publish` environment contains no Apple secrets. Two optional repository variables override defaults: `OMNIWM_RELEASE_SIGNING_IDENTITY` (default `Developer ID Application: Oliver Nikolic (VF8LDJRGFM)`) and `OMNIWM_RELEASE_NOTARIZE_PROFILE` (default `OmniWM-Notarize`). The prepare summary prints the `gh workflow run` command for publication because the web form cannot take multi-line notes. Download and launch the prepared app on a desktop before approving publication. Pass `skip_app_launch` only when the runner cannot launch the GUI; signature, notarization, and quarantine checks still run. Prepared artifacts expire after 30 days. If `main` moves before publication, prepare again. Retry an interrupted publish with the same prepare run and identical notes. Publication creates the tag and release before pushing `main`; a competing push or remote failure can still require manual recovery. Local releases via `Scripts/omniwm_release.py` use your own keychain and notarization profile. For canaries, configure **canary-signing** with no required reviewers and a selected-branches deployment policy allowing only `main`. The daily **OmniWM canary** workflow skips a build when the checked-out commit is already contained in a stable or canary tag, or when only documentation changed since the newest ancestor tag. For this check, documentation means root-level `.md` files and everything under `docs/` or `website/`; Markdown elsewhere still counts as an app change. Documentation-only commits are also omitted from canary release notes. The manual `force` option bypasses both skip checks. When a build is needed, the workflow requires the latest **OmniWM CI** push run on `main` to pass, including both **Verify** and **Tests**. It starts from the actual checkout rather than the scheduled event's commit, before dependency setup or importing Apple credentials. Documentation-only pushes don't start CI, so it uses the newest commit that has a run, looking from the checked-out commit down through documentation-only commits to the first app commit. A failed or unfinished run there, or no run at all, stops the canary; wait for CI to pass and rerun the workflow. The manual `force` option cannot bypass CI. ### Maintainer CI Rollout The **Main branch protection** ruleset blocks branch deletion and force-pushes. Keep those protections and do not grant GitHub Actions an **Always** bypass. The release workflow uses a normal fast-forward push and rejects additional blocking rules before publication, even when its token could bypass them. Required checks or pull-request-only updates need a release flow that publishes an already-reviewed version commit; do not bypass those rules to keep the current flow working. **OmniWM CI** (`ci.yml`) runs automatically on pull requests and pushes to `main` or branches ending in `-release`, except documentation-only changes. **Website** (`website.yml`) checks website changes on pull requests and pushes to `main`. Neither workflow requires a custom review approval. GitHub may still require approval for first-time fork runs. For an existing PR, use **Actions → OmniWM CI → Run workflow** and enter its PR number to test its merge with the base branch. A manual run runs the full test groups and provides logs; it does not replace the PR's required check. Updating the PR branch triggers its normal PR checks. ## Trace Files Include a trace file when useful, especially for bug reports. Open **Settings → Troubleshooting**, click **Start Recording**, reproduce the bug, then click **Stop & Save Recording** and attach the saved `.log` file. Before attaching a diagnostic, review it: the file can contain OmniWM settings, application and window titles, and title-based App Rule matchers. With IPC enabled, captures can also be scripted using the CLI: `capture start trace`, `capture stop`, and `capture status`. If you are unsure about something, open an issue or ask in your pull request. Questions and early feedback are welcome.