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 2026.6.10 or later. Select that Xcode with
xcode-select or DEVELOPER_DIR, then:
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 before merging. See
guard maintenance.
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 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:
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; dry-run artifacts aren’t for installation.
Testing #
Format only the files you touched, then run the full gates:
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. 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. Run it deliberately:
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 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.
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.
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 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:
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:mise run check mise run test:scripts mise run audit mise run bench:smokeauditscans all locally available Git history, like CI's full checkout; a shallow clone cannot certify missing history. Reports go tobuild/gitleaks.sarifandbuild/ci-audits. Packaging changes also needmise run release-dry-run; live-window changes need the locked e2e/reality checks described above.
Releasing #
Complete the owner setup checklist, 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. 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.