Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
74 lines (52 loc) · 2.43 KB

CONTRIBUTING.md

File metadata and controls

74 lines (52 loc) · 2.43 KB
Raw

Contributing

Goal

Keep Reposes visually and functionally stable while making the internals easier to reason about, test, and evolve.

Prefer incremental hardening over broad replacement.

Ground Rules

  • Preserve product parity unless a change is explicitly scoped as product work.
  • Keep package boundaries real. Do not bypass them by moving logic back into the shell or root app.
  • Prefer small APIs between packages over shared implementation details.
  • Keep AppKit escape hatches near the shell and windowing edge.
  • Keep indexing and graph layers UI-free.
  • Keep canvas semantics-dumb. It should consume scene data, not repository logic.

Architecture Rules

  • ReposesCore must stay free of SwiftUI, AppKit, RepoSessUI, Flow, and SwiftSyntax.
  • ReposesIndexing owns repository traversal, ignore handling, indexing, and cache persistence.
  • ReposesGraph owns semantic slicing and projection, not scene or rendering details.
  • ReposesScene is the boundary where semantic projection becomes canvas input.
  • ReposesCanvasEngine owns viewport, rendering, hit testing, and interaction plumbing.
  • ReposesShell owns window composition, workspace coordination, settings, exports, and inspector flow.
  • Sources/App should remain a thin executable entry point.

Local Workflow

Build and test from the repo root:

swift build --disable-sandbox
swift test --disable-sandbox

Run package-local suites when changing a package boundary:

swift test --package-path Packages/ReposesIndexing
swift test --package-path Packages/ReposesGraph
swift test --package-path Packages/ReposesScene
swift test --package-path Packages/ReposesCanvasEngine
swift test --package-path Packages/ReposesShell

Useful helpers:

make run
make test
make verify

Tests

  • Add tests in the package that owns the behavior.
  • Keep root Tests/ReposesTests for cross-package integration coverage.
  • When a test needs a higher-level dependency, move that test upward instead of introducing a dependency cycle.
  • Do not rely on the root target as a back door for package-internal behavior.

Pull Request Standard

Each change should answer these questions cleanly:

  • What boundary got clearer?
  • What behavior stayed intentionally the same?
  • What test proves that?

Conduct And Security

Be direct, respectful, and focused on the work. See CODE_OF_CONDUCT.md.

Report security issues privately. See SECURITY.md.