Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
87 lines (66 loc) · 3.25 KB

CONTRIBUTING.md

File metadata and controls

87 lines (66 loc) · 3.25 KB
Raw

Contributing to PicChronoImporter

Thank you for helping improve PicChronoImporter. Changes should stay small, testable, and aligned with the documented import-safety rules.

Before starting

Read these files before changing behavior:

  • AGENTS.md
  • docs/SPEC.md
  • docs/IMPLEMENTATION_PLAN.md
  • docs/code_review.md

The specification wins when an implementation detail and a product rule differ. Please discuss changes to product rules or v1 non-goals before implementing them.

Architecture boundaries

  • PhotoImportCore contains platform-independent domain models, protocols, services, and use cases. It must not directly depend on SwiftUI, AppKit, ImageIO, UniformTypeIdentifiers, FileManager, or SQLite details.
  • PhotoImportPlatformMac contains macOS file-system, metadata, thumbnail, cache, and persistence adapters.
  • MacApp/PicChronoImporter contains SwiftUI views, ViewModels, navigation, dependency composition, resources, and UI-test fixtures.
  • Keep business rules out of SwiftUI views and inject platform dependencies explicitly.

Import and duplicate-detection changes require particular care. Preserve the two-stage duplicate check, default conflicts to skip, and re-check the destination immediately before every mutation.

Tests

Use Xcode 26.6 or a compatible newer Xcode on macOS 26.0 or later.

cd Packages/PhotoImportCore
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer \
  /usr/bin/xcrun swift test

cd ../PhotoImportPlatformMac
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer \
  /usr/bin/xcrun swift test

cd ../..
/Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild test \
  -project PicChronoImporter.xcodeproj \
  -scheme PicChronoImporter \
  -destination 'platform=macOS' \
  -only-testing:PicChronoImporterTests

Add or update deterministic tests for behavior changes. Prefer Swift Testing for Core and XCUITest for fixture-backed UI flows. Run the UI suite by replacing the final target with PicChronoImporterUITests when a change affects the app workflow, fixtures, accessibility, or presentation.

Fixtures and private media

JSON fixtures live in MacApp/PicChronoImporter/Resources/Fixtures/ and must be deterministic. Use synthetic paths such as /Users/example/...; never commit a real home-directory path, volume UUID, camera file, content hash, or private metadata.

Representative real-media validation is opt-in. Keep its media and populated manifest under the Git-ignored LocalTestMedia/ directory and follow docs/REAL_MEDIA_VALIDATION.md. Automated tests must not require a real SD card, photo library, network connection, or manual file selection.

Pull requests

Before opening a pull request:

  1. Confirm the change matches docs/SPEC.md and does not add a v1 non-goal.
  2. Run the smallest relevant test suites, then the broader deterministic suites when practical.
  3. Check git diff --check and review every changed fixture or generated asset.
  4. Run a secret scan when the change touches configuration, fixtures, documentation, or release automation.
  5. Explain user-visible behavior, safety implications, tests run, and any known limitation in the pull request description.

By contributing, you agree that your contribution is licensed under the MIT License in this repository.