# Contributing to Silo Apple > [!IMPORTANT] > The most helpful way to contribute to Silo right now is a clear, accurate > issue. Feature ideas go in > [Discussions → Ideas](https://github.com/Silo-Server/silo-apple/discussions/categories/ideas), > not issues. Pull requests are welcome from contributors who've had one merged > in a Silo repository, or when a maintainer asks for one; a feature pull request > also needs an issue a maintainer has labeled `accepted`. Other pull requests > are closed automatically without review. ## Why we're asking for issues Pull requests now arrive faster than we can review them carefully. Reviewing a change properly means reading every line, checking it against work already in flight, re-running validation, and owning the result after it merges. Writing the change ourselves from a precise issue takes less time, and it keeps every change on one workflow with the same tests and the same review. This is about review capacity, not the quality of anyone's work, and it applies whether or not you used AI. We'll revisit it as Silo approaches 1.0. Thank you for taking the time to write things up well. ## Write a useful issue Open an [issue](https://github.com/Silo-Server/silo-apple/issues) for problems in the iOS, tvOS, and macOS apps. Server and API problems belong in [`silo-server`](https://github.com/Silo-Server/silo-server/issues/new/choose). Search first; if an issue already covers the problem, add what's new there. Using Claude Code or Codex? The [Silo troubleshooting skill](https://github.com/Silo-Server/silo-troubleshooting-skill) helps you collect these details and drafts the issue, then has independent reviewers check it against your evidence before you post it. - One problem per issue. - Describe what you observed before any theory about the cause. - Give exact steps to reproduce, expected and actual behavior, the app version and build, your device and OS version, and the Silo server version. - Paste raw logs rather than a summary. Redact credentials, tokens, personal data, and private media details, mark each redaction, and leave the rest untouched. - If you found the cause or have a fix in mind, add it under a Technical notes heading, apart from what you observed. Point to the files involved; a short code excerpt is fine. We may implement it differently. - Disclose AI use, as described in the [Silo contribution guide](https://github.com/Silo-Server/.github/blob/main/CONTRIBUTING.md#ai-assisted-contributions). Report security vulnerabilities privately with **Report a vulnerability** on the repository's Security tab, not in a public issue. ## Suggest a feature Post feature ideas for the iOS, tvOS, and macOS apps in [Discussions → Ideas](https://github.com/Silo-Server/silo-apple/discussions/categories/ideas), not as issues. Ideas that need new server behavior go in [silo-server's Ideas](https://github.com/Silo-Server/silo-server/discussions/categories/ideas). Search first and upvote an existing idea rather than repeating it. Describe the problem the feature solves and who it affects, and read [Project non-goals](https://github.com/Silo-Server/silo-server/blob/main/docs/non-goals.md) first. Maintainers open an issue for an idea when they plan to build it or want help building it. ## Pull requests Pull requests are welcome from contributors who've had a pull request merged in a Silo repository, and from anyone a maintainer has asked for one, usually in an issue comment. A feature pull request (a `feat` title) from someone without triage or write access must also link, in its description, an issue in this repository that a maintainer has labeled `accepted`. The rest of this guide applies to those pull requests. A workflow closes other pull requests without review when they open. That isn't a judgment of the work. If the problem still matters, open an issue for it, or post a feature idea in Ideas, and link the closed pull request; we may use the code as a reference. Once a feature's issue is labeled `accepted`, link it in a new pull request, or ask a maintainer to reopen the closed one. If a maintainer asked you for a pull request and you haven't had one merged yet, the workflow still closes it when it opens; the maintainer reopens it, and the check leaves it alone from then on. The [Silo contribution guide](https://github.com/Silo-Server/.github/blob/main/CONTRIBUTING.md) covers project-wide coordination, focused changes, evidence, AI disclosure, and pull request expectations. Those requirements apply here; this guide adds the Apple-specific workflow. ## Before you start A feature needs an issue labeled `accepted` before you implement it; start with an idea in Ideas. Open an [issue](https://github.com/Silo-Server/silo-apple/issues) before implementing a navigation or behavior change, large refactor, or work that changes the shared server contract. Documentation, narrow fixes, and well-scoped parity corrections can go straight to a pull request. This repository owns the iOS, tvOS, and macOS clients. Server/API work belongs in [`silo-server`](https://github.com/Silo-Server/silo-server), and shared client behavior should be checked against [`silo-android`](https://github.com/Silo-Server/silo-android). ## Development setup Read [README.md](README.md) for prerequisites, signing setup, and build commands, then read [AGENTS.md](AGENTS.md) for module ownership and platform guidance. Regenerate `iosApp/Silo.xcodeproj` from `iosApp/project.yml`; never hand-edit the generated project. ## Validate your change Build every affected platform and run the focused XCTest targets. A typical iOS build and simulator test gate is: ```sh cd iosApp xcodegen generate xcodebuild build \ -project Silo.xcodeproj \ -scheme Silo \ -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \ CODE_SIGNING_ALLOWED=NO xcodebuild test \ -project Silo.xcodeproj \ -scheme Silo \ -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \ CODE_SIGNING_ALLOWED=YES CODE_SIGN_IDENTITY=- ``` Simulator tests use ad-hoc signing so Keychain-dependent tests have an application identity; they do not require a distribution certificate. The `SiloTests` bundle belongs to the `Silo` scheme; there are currently no separate tvOS or macOS test bundles. Use `SiloTV` with a tvOS simulator for tvOS builds and `SiloMac` with `platform=macOS` for macOS builds. Exercise visible changes in each affected app. ## Show visible changes A pull request that changes what a user sees must show the change in its Evidence section, so reviewers can see it without building the branch. In this repository that means iOS, tvOS, and macOS. A change is visible when it alters any of these: - layout, styling, copy, navigation, focus, empty and error states; - which items a screen shows, or in what order: search results, home sections, recommendations, library browsing, collections, sorting, or filtering; - what an item shows: titles, artwork, descriptions, ratings, badges, episode grouping, or availability; - playback behavior a user notices, such as default audio or subtitle tracks, markers, controls, or resume position. Provide evidence that fits the change: - **Changes to a screen:** before-and-after screenshots of the same screen with the same data, one pair per affected surface. Add a short recording when motion, timing, focus movement, or a multi-step flow matters. - **Every affected device:** iPhone, iPhone Duo, iPad, Mac, and Apple TV each lay out screens differently, so capture each one the change can reach. Shared code outside the `iOS`, `macOS`, and `tvOS` folders usually reaches all of them. Capture the iPhone Duo both folded and open: the open display is iPad-sized but reports as a phone, so it gets layouts no other device shows. Simulator captures are fine. To skip a device, say why the change cannot reach it. - Name the device, the build or commit, and for the iPhone Duo whether it was folded or open, for each capture. Capture against a test library or public-domain media where you can, and keep passwords, tokens, and API keys out of every capture. Then put the evidence in one of two places: - **On GitHub:** attach the screenshots or recordings under the pull request's Evidence heading. Everything on GitHub is public, so crop or blur hostnames, URLs, account names, and personal library contents. - **On [evidence.siloserver.org](https://evidence.siloserver.org/) (optional):** only you and Silo maintainers can open what you publish there, after signing in with GitHub, so captures need no cropping or blurring. Captions that start with `Before:` and `After:` become a side-by-side comparison, and recordings get a player. Upload from the Details link of the pull request's `Evidence` check, or with the command line (Node.js 22 or later): `npx @silo-server/evidence login` once on each computer, then `npx @silo-server/evidence publish --pr `. The [package README](https://www.npmjs.com/package/@silo-server/evidence) describes the folder. Then write `Evidence: https://evidence.siloserver.org/r/silo-apple/pr-/` under the Evidence heading. Until a pull request of yours has merged here, a maintainer approves you once before your first upload. The pull request's `Evidence` check passes once evidence is published or attached. It asks for evidence when the change touches the app source under `iosApp/iosApp/`, or when a maintainer adds the `evidence-required` label; a maintainer adds `evidence-not-needed` when nothing visible changed. Changes users cannot see write `Evidence: none, no user-visible change`. If you could not capture evidence, say why; the reviewer decides whether the pull request can merge without it. ## Open the pull request Use a Conventional Commit title, fill in the pull request template, explain which platforms are affected, paste the actual validation results, and call out any server or Android coordination. Read the [AI-assisted contribution policy](https://github.com/Silo-Server/silo-server/blob/main/docs/ai-contributions.md) and include its disclosure block. ## Licensing of contributions This project is licensed under `AGPL-3.0-or-later` with two additional permissions: the App Store / DRM permission in [APPSTORE-EXCEPTION.md](APPSTORE-EXCEPTION.md) and the platform library permission in [PLATFORM-EXCEPTION.md](PLATFORM-EXCEPTION.md). By submitting a contribution, you agree that it is licensed under those same terms — the AGPL *including* both additional permissions — and that the project may distribute builds containing your contribution through application stores such as the Apple App Store and TestFlight as the App Store permission describes. If you cannot agree to an additional permission, say so in your pull request before it is merged. You retain copyright in your contribution; no assignment is requested. ## Practical notes - Repository layout, build commands, and coding conventions are in [AGENTS.md](AGENTS.md) and the docs under `docs/`. - Third-party components and their licenses are inventoried in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md); update it when a dependency changes. ## Instructions for coding agents Coding agents must read [AGENTS.md](AGENTS.md) before changing the repository (`CLAUDE.md` points to the same guidance). The organization-wide contribution guide and AI-assisted contribution policy apply to agent and human authors equally.