Contributing

Contributing

A Playa Named Gus is being prepared as an open source Apple-first Jellyfin client. Contributions should preserve the project constraints and platform feel.

Before You Start

• Read Architecture.
• Check the live roadmap in Documentation/ROADMAP.md for current milestone scope.
• Check existing issues and discussions before opening duplicates.
• Keep changes narrowly scoped.

Design and Implementation Standards

• Prefer Apple/system APIs over custom code.
• Do not add runtime dependencies without an explicit maintainer decision and an ADR. The only runtime dependencies are jellyfin-sdk-swift and — on iOS/iPadOS only — the Readium toolkit for EPUB reading (ADR 0009).
• Keep Jellyfin-specific API/DTO assumptions behind the media-server provider boundary in Sources/Providers (ADR 0008).
• Use SwiftUI and Observation idioms.
• Keep platform divergence in Sources/Platform or very small guarded modifiers.
• Use AVKit for playback. Direct play is the default for hardware-supported formats; Jellyfin server transcoding is the fallback for format compatibility.
• Use Security framework for secrets.
• Use Codable, FileManager, URLSession, OSLog, and String Catalogs before custom systems.
• Respect Dynamic Type, VoiceOver, tvOS focus, pointer/hover, safe areas, and platform navigation conventions.

Working with project.yml

project.yml is the project source of truth. A Playa Named Gus.xcodeproj is generated output.

Run:

xcodegen generate

after adding, deleting, or renaming files, targets, resources, or build settings.

Pull Request Expectations

A strong PR includes:

• A clear summary of what changed and why.
• Validation commands run locally.
• Any platform/device validation that could not be run.
• Notes for deviations from the native-first mandate.
• Roadmap/wiki/docs updates when behavior or scope changes.

Recommended validation:

Scripts/format.sh
swiftformat Sources Tests --lint
jq empty Resources/Localizable.xcstrings
git diff --check
xcodebuild test -project 'A Playa Named Gus.xcodeproj' -scheme 'Gus iOS Unit Tests' -destination 'platform=iOS Simulator,name=iPhone 17'

The A Playa Named Gus scheme is build-only; use the Gus <platform> Unit Tests schemes for the test action. For broader changes, also build the iOS, iPadOS, tvOS, macOS, visionOS, and watchOS destinations.

Issues and Discussions

Use issues for actionable work:

• Bugs.
• Feature requests with a concrete problem statement.
• Platform-specific regressions.
• Documentation gaps.

Use discussions for:

• Announcements.
• Q&A and troubleshooting.
• Ideas that are not ready to become issues.

Localization

All user-facing text belongs in Resources/Localizable.xcstrings. Use clear translator comments for strings with context-sensitive meaning.

Validate the catalog with:

jq empty Resources/Localizable.xcstrings

Documentation

Keep documentation current as part of the same change that changes behavior.

• Use Documentation/adr/ for significant technical decisions.
• Use Documentation/ROADMAP.md for milestone scope and status.
• Use this wiki for contributor and user-facing project docs.