# Contributing to Forji

Thanks for your interest in contributing! Forji is a native iOS client for
Forgejo, and contributions are welcome. These guidelines keep changes easy to
review and the codebase easy to maintain for the next person.

## Pull requests

- **One concern per pull request.** Keep each PR focused on a single change.
  Split bug fixes out from refactors. A behavior-preserving refactor is easy to
  approve on its own; bundling it with a fix makes the actual fix hard to
  isolate and review.
- **Keep the description accurate.** The PR description must match what the diff
  actually does. If you change the approach while iterating, update the
  description to match the final code, and explain *why* the change fixes the
  problem.
- **Prefer small, stacked PRs** over one large change. For anything large, open
  an issue first so we can agree on the shape before you write the code.
- Respond to review feedback by fixing it or explaining it.

## Reporting bugs

Open an issue with exact reproduction steps so the bug can actually be
reproduced and fixed:

- Device and iOS version.
- What to tap and what to watch for.
- Expected behavior vs. what actually happens.

## Architecture

New code follows MVVM with Apple-native tools:

- `@Observable` view models with `async/await`.
- **No external state-management dependency.** The project deliberately stays on
  Apple's `@Observable` + `async/await` direction rather than adopting a
  third-party architecture.
- Keep the code easy to understand for the next contributor. Favor the simplest
  approach that fits Apple's idioms.
- ForgejoKit holds the platform-agnostic API logic; the Forji app holds the
  SwiftUI views, authentication, and persistence. Keep that separation.

## Code style

The repository ships its own formatter and linter configs
([`.swiftformat`](.swiftformat), [`.swiftlint.yml`](.swiftlint.yml)). Match them
before opening a PR, and match the existing style in the files you touch:

```bash
just format   # SwiftFormat
just lint     # SwiftLint
```

## Tests

- Include unit tests for the behavior you add or change.
- When you fix a UI behavior that has no automated coverage, add a UI regression
  test. If a change is hard to cover, say so in the PR and offer a UI test.
- See the [README](README.md) for `just test`, `just test-ui`, and the
  integration test setup.

## License and the App Store exception

Forji is licensed under the [GNU General Public License v3.0](LICENSE) with an
[App Store Exception](LICENSE#app-store-exception) that permits distribution of
the compiled app through Apple's App Store.

By submitting a pull request you agree your contribution is licensed under
GPLv3 and may be distributed through the App Store under that exception. To
confirm, include this sentence in your PR description or a comment:

> "I grant Stefan Hausotte an irrevocable, worldwide, royalty-free license to
> use, sublicense, and distribute my contribution, including through Apple's App
> Store under the project's App Store exception."

You keep your copyright, the project stays open source under GPLv3, and you will
be credited as a contributor.
