Contributing

Contributing

Forks, issues, and pull requests are welcome. Contained is source-available under the PolyForm Noncommercial License 1.0.0 — contributions are accepted under those same non-commercial terms, and the "Contained" name and branding are reserved (see NOTICE).

Layout

Sources/ContainedCore/   pure logic — models, CLI wrapper, decoding, compose (no SwiftUI)
Sources/Contained/       the SwiftUI app
  DesignSystem/          glass helpers, tokens, shared components
  Features/<Domain>/     one folder per sidebar domain
  Navigation/ Stores/ Support/ History/
Tests/ContainedCoreTests/  golden-argv + decode + decision tests
Tests/ContainedAppTests/   RunSpec argv + compose mapping
scripts/                 bundle.sh, release.sh, appcast.sh
docs/                    appcast.xml (Sparkle feed, served by Pages) — human docs live in this wiki

Conventions

• Every CLI action goes through a ContainerCommands builder + a ContainerClient wrapper, with a golden-argv test. The UI never assembles argv inline — this keeps "Reveal CLI" honest.
• Pure decision logic is factored into ContainedCore (RestartDecision, HealthDecision, compose ordering) and unit-tested without spawning processes.
• No contained.* personalization labels. Card styles and healthchecks live in local stores. Only contained.restart and contained.stack are written (they must round-trip through the container).
• Never put secrets or personal data in test fixtures. Fixtures are captured CLI output — scrub tokens, domains, and paths before committing. (.gitignore blocks signing material; push protection is on.)
• Match the surrounding style — comment density, naming, Liquid Glass idioms. AppKit bridges are flagged in comments.

Before a PR

swift build && swift test                     # must be green
./scripts/bundle.sh && open Contained.app     # smoke-test the screens you touched

Good first contributions

• Work through a row of the 1.0 Polish Checklist in the README for one screen (states, a11y, copy, layout).
• Add a golden-argv or decode test for an under-covered command.
• Improve an empty / loading / error state.

See Architecture for how the pieces fit together.