# Contributing Thanks for wanting to help. Here's what you need to know. ## Getting set up You'll need macOS 15 or later, Xcode 26.3 (see `.xcode-version`), and [mise](https://mise.jdx.dev/) 2026.6.10 or later. Select that Xcode with `xcode-select` or `DEVELOPER_DIR`, then: ```sh mise trust && mise run setup mise run test mise run lint mise run test:scripts # name guard and every shell fixture, as in CI mise run app # build/Parcel.app mise run e2e # drives the real app through FixtureApp ``` Setup installs the versions in `mise.toml`, builds the native developer tool, and installs worktree-local lefthook hooks, then runs `mise run doctor`. It refuses to replace foreign hooks. Pre-commit formats and restages changed Swift files and checks names, shell scripts, and workflows. Commit messages require DCO sign-off. Pre-push builds every test target, verifies the lane partition, and runs full lint (aiming for about 90 seconds warm), without executing all CI lanes. Run the [local CI parity tasks](#sending-a-change) before merging. See [guard maintenance](Scripts/Names.md). Normal mise tasks run offline: update checks and automatic tool installs are disabled in the repo config. Setup explicitly enables downloads for installation; once installed, hooks do not need a network connection. Hooks resolve mise even outside its environment and fail if the pinned checker cannot run. Repository helpers use `Scripts/parcel-dev.sh COMMAND`, backed by a cached release executable in `.build`; the first call builds it. Workflow checks need no parser dependency. Generated casks are checked with the pinned Ruby's `ruby -c`. Swift and swift-format always come from Xcode, not mise. `make` remains a thin compatibility wrapper around the same tasks. Build tasks and doctor stamp the selected toolchain and package inputs per cache; a changed stamp discards compiled objects but retains dependencies. CI caches only checkouts, repositories, and artifacts; compiled products are shared only within one workflow run. After a cast crash such as `ContiguousArrayStorage` to `Error`, run `mise run clean-modules` first. Direct `swift build` bypasses the stamp; prefer `mise run build` (or `Scripts/swift-build.sh --build-tests` for test binaries). Run `Scripts/make-dev-cert.sh` once. It creates a local "Parcel Development" signing identity so macOS remembers the Accessibility grant across rebuilds. Then add `build/Parcel.app` under System Settings → Privacy & Security → Accessibility. [AGENTS.md](AGENTS.md) has the architecture and the rules we hold ourselves to. Give it a read before a big change. ## Everyday tasks `mise run` is the entry point; `make` is a compatibility wrapper. | Task | What it does | | --- | --- | | `mise run build` / `mise run app` | Build binaries / assemble the signed development bundle | | `mise run run` | Build and open the app | | `mise run test` / `mise run e2e` | Unit tests / opt-in live-window tests | | `mise run lint` / `mise run format` | Check / apply formatting and repository guards | | `mise run test:scripts` | Tooling and packaging regressions | | `mise run audit` | Redacted full-history secret scan, shipped locales, and dependency licenses | | `mise run bench:smoke` | Debug benchmark smoke, identical to CI; no performance certification | | `mise run check-app` | Check and smoke-launch a relocated bundle | | `mise run dmg` / `mise run release-dry-run` | Package a release / exercise disposable signing | | `mise run remote-test your-mac` | Test on another Mac | | `mise run clean-modules` / `mise run clean` | Discard compiled modules / remove build outputs | `make app` and `mise run app` build a debug bundle by default; `make app CONFIG=release` and `mise run app release` select release. Both hide the tour replay menu item by default. To expose it for development, quit Parcel and run: ```sh defaults write dev.vinnymac.parcel developer.showGuidedTour -bool YES ``` Relaunch Parcel and choose **Guided Tour…** in its menu. Remove the override with `defaults delete dev.vinnymac.parcel developer.showGuidedTour`. Reality and fixture checks use their isolated IPC route instead. Release packaging needs the metadata in [distribution notes](Packaging/README.md); dry-run artifacts aren’t for installation. ## Testing Format only the files you touched, then run the full gates: ```sh mise exec -- swift format --in-place path/to/changed.swift Scripts/swift-build.sh --build-tests PARCEL_TEST_SKIP_BUILD=1 mise run test mise run lint PARCEL_TEST_SKIP_BUILD=1 mise run test:scripts Scripts/check-doc-links.sh ``` `mise run test` positively selects the screen-free suites in [unit manifest](Tests/Lanes/unit.txt). It clears live opt-ins, checks discovered suite IDs before running, and rejects empty runs or missing executed suites. `PARCEL_TEST_SKIP_BUILD=1` reuses a prior `swift build --build-tests`; `PARCEL_TEST_XUNIT_OUTPUT` changes the JUnit destination (default `build/junit.xml`). A `--filter` narrows the manifest; it cannot enable another lane. Hosted AppKit and native input coverage stays in the [native-host manifest](Tests/Lanes/native-host.txt). Run it deliberately: ```sh PARCEL_NATIVE_HOST=1 Scripts/test-native-host.sh ``` The wrapper takes `Scripts/screen-lock.sh`; tests also verify lock ancestry and an unlocked console. Native input needs an existing Accessibility grant for the test process, never a consent prompt. Missing permission is a visible skip, not an early-return pass; skips do not certify that capability. The unit, native-host, and [benchmark manifests](Tests/Lanes/bench.txt) must be kept current when adding suites: unclassified or overlapping suites fail the inventory check. Screen-free FixtureApp decoding and input-validation suites belong to unit, even though they live in `ParcelE2ETests`; only the real-app suites are exempt for the live lane. JUnit uses Swift Testing directly, not an empty XCTest report. Plain `swift test` remains screen-free by default: the shared AppKit ancestor and native input tests require explicit opt-in and the mutex, even when the test process already has Accessibility. Suites retain `.e2e`, `.benchmark`, and `.appKit` tags for test plans. `mise run bench` runs the complete performance suite in release, serially; record a baseline with `make bench-record` on a quiet machine first. `mise run bench:smoke` positively selects the benchmark manifest in debug locally and in CI, including the screen-free display event benchmark; missing or skipped suites fail its JUnit execution check. Set `PARCEL_TEST_SKIP_BUILD=1` to reuse a debug `swift build --build-tests`. `mise run e2e` builds the real bundle and drives it through FixtureApp. Only `build/Parcel.app` needs Accessibility; the test runner needs neither Accessibility nor Screen Recording. A missing grant fails preflight rather than silently skipping. ```sh PARCEL_E2E_PREFLIGHT_ONLY=1 mise run e2e ``` Quit your running Parcel first: the harness refuses to control or quit it, and manages fixture windows rather than your own. Screen recording is a separate opt-in: see [media capture](docs/media/README.md). `mise run reality` checks real apps using a helper embedded only in its debug Parcel bundle. Only `build/Parcel.app` needs Accessibility: its directly spawned helper inherits that existing permission. No separate helper grant is needed. Run `mise run reality -- --preflight-only` to verify inherited access without opening scenario windows or requesting consent. Reality builds require the local **Parcel Development** identity and preserve Parcel's designated requirement. Ordinary debug and release bundles contain neither helper nor launcher. Every live lane shares `Scripts/screen-lock.sh`; do not run reality, fixture, first-light, or tour checks outside that lock. Frame checks need no Screen Recording. Optional visual checks use ScreenCaptureKit only in the helper, with `PARCEL_REALITY_SCREEN_CAPTURE=1` and an existing Screen Recording grant for its responsible Parcel bundle. The lane never requests a new privacy grant. See [reality checks](Tests/Reality/README.md) for scenarios and artifact safety. ### Writing tests that stay fast Choose the lane by what a test does, not its target name. Pure models, codecs, and fake-backend tests belong in unit. AppKit hosting and native input belong in native-host. Real window writes need the locked fixture or reality lane. Tooling and subprocess tests belong in the script lane. Add each new unit, native-host, or benchmark suite to its lane manifest; the inventory gate rejects missing and overlapping classifications. Use Swift Testing with independent fixtures and parameterized arguments for behavioral cases. Give each test its own temporary directory, notification center, preferences suite, and socket as needed. Clean them up on failure too. Avoid process-wide environment changes and standard preferences. Use `.serialized` only for an identified shared resource or measured scheduling problem, and explain the reason beside it. Main-actor isolation alone does not require suite serialization. For asynchronous behavior, wait for an observable state change or an explicit fixture acknowledgement. Inject clocks and schedulers to exercise elapsed time; advance them across the real suspension points and assert exact boundaries. A sleep, a fixed number of yields, or an empty queue does not prove that an event was consumed. Negative assertions need an event-processing barrier before checking that nothing happened. Keep real delays only when elapsed wall time is the behavior under test. Give waits a bounded failure path, and ensure cancellation releases continuations and child tasks rather than leaving the runner hung. ### Iterating and measuring Build once after edits, then select the affected unit tests: ```sh Scripts/swift-build.sh --build-tests PARCEL_TEST_SKIP_BUILD=1 mise run test -- --filter HotPathTracingRegressionTests ``` Selection still checks lane membership and rejects an empty match. Skip-build means the caller already built the current sources; it does not check freshness. Before merging, run the complete unit and script lanes, lint, and the other gates listed below. A filtered pass does not certify the whole lane. Measure build time separately from execution. Keep the host and build configuration the same, compare repeated warm runs, and inspect `build/junit.xml` for test durations. Parallel test durations include time waiting for shared executors, so reproduce a slow suite with a filter before optimizing it. Compare `mise run test:serial` when investigating contention; serialization is a diagnostic, not an automatic fix. The script lane records per-phase and per-fixture durations in `build/script-results.json` and `build/script-summary.md`, with individual logs. Preserve failure artifacts before rerunning: each lane replaces its previous report. Benchmark smoke establishes execution coverage; use the release benchmark lane on a quiet host for performance budgets. ## Translations Yes, translation contributions are welcome. Edit the relevant `.xcstrings` String Catalog under `Sources/`, keeping format placeholders and accessibility labels intact. Include the locale and the screens you checked in your change. Don’t commit generated resource files. Run the same build, test, and lint gates. Settings → General → Language lists the languages in the built app. Changes use Parcel’s own `AppleLanguages` preference and take effect after restarting. The bundled `prcl` reads the app’s language choice at launch for catalog-backed human-readable output. JSON keys and command names remain stable; the CLI never writes a language preference to the terminal or global domain. Debug bundles include accented, expanded catalog text. Quit your Parcel first, then launch with `open -n --env PARCEL_PSEUDO_LOCALIZATION=1 build/Parcel.app`. This launch option does not save a language preference; release bundles ignore it and contain no pseudo-localization resources. `Scripts/check-localization.sh` audits catalog keys and common UI text sinks; script tests read back every module’s compiled catalogs, including plurals and format arguments. ## Sending a change - Keep pull requests small and focused, with tests. If it moves a window, it needs an e2e scenario too. - Every motion change needs a Reduce Motion path, and every new shortcut goes through config. - Pre-push runs `mise run check:push`: build every test target, verify lane completeness, then lint. Full unit execution, secret/license audits, and benchmark smoke remain explicit merge gates: ```sh mise run check mise run test:scripts mise run audit mise run bench:smoke ``` `audit` scans all locally available Git history, like CI's full checkout; a shallow clone cannot certify missing history. Reports go to `build/gitleaks.sarif` and `build/ci-audits`. Packaging changes also need `mise run release-dry-run`; live-window changes need the locked e2e/reality checks described above. ## Releasing Complete the [owner setup checklist](docs/releasing-setup.md), then start with `Scripts/launch.sh --dry-run` and run interactively on the signing Mac. Reuse `--version` to resume, including an existing draft. Uploads and pushes ask first; `--replace-secret NAME` confirms a local credential replacement. Protection checks are read-only: missing policies or repository-level signing/mirror secrets stop launch, rather than changing settings or deleting credentials. Product settings and the permanent public update key live in `Scripts/product.env`. Commit `PRODUCT_UPDATE_PUBLIC_KEY` before the first release; never rotate it implicitly. The GitHub `mirror` and `release` environments accept only `PRODUCT_DEFAULT_BRANCH`. The mirror token belongs only to `mirror`; signing, notarization, and private update keys belong only to the owner-reviewed `release` environment. Tag CI builds unsigned artifacts without secrets. Launch validates branch/tag protections, environment policies, secrets, and default-branch ancestry before pushing the tag and dispatching signing from the configured default branch. The owner-approved signing job uses trusted scripts from that branch on a GitHub-hosted runner, then signs, notarizes, staples, and publishes. Live e2e stays disabled. Persistent secrets never enter process arguments; macOS keychain tooling briefly exposes only a random disposable keychain password on that isolated runner. The launch script verifies DMG checksums and update signatures before merging the appcast into the separate site repo. Review/build/deploy that site yourself before running the printed tunnel commands. ## Sign your commits We use the [Developer Certificate of Origin](https://developercertificate.org). Add a `Signed-off-by` line to each commit, which `git commit -s` does for you. It says you wrote the change or have the right to submit it under Apache 2.0. ## Third-party code MIT, BSD, Apache 2.0 and Zlib code is welcome. Keep the original copyright header and add an entry to `NOTICE`. We can't take GPL or source-available code, so please don't paste from those projects, even small snippets.