An auto tiler for macOS
parcel CONTRIBUTING.md
15 kB · 278 lines
Markdown
at main

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: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, 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.