125 lines
5.1 KiB
Markdown
125 lines
5.1 KiB
Markdown
# Repository instructions
|
|
|
|
## Gitea issue workflow
|
|
|
|
Use the `tea` command-line tool as the preferred way to list, inspect, create,
|
|
and update Gitea issues. Run it from the repository root so it can use the
|
|
configured remote, for example `tea issues` or `tea issues 1`.
|
|
|
|
Run issue-detail commands directly, for example `tea issues 7`. In a sandboxed
|
|
runner, grant network access before invoking `tea`. Without DNS/network access,
|
|
the current `tea` detail path may panic inside Gitea SDK version handling
|
|
instead of returning the underlying connection error.
|
|
|
|
## Required pre-commit gates
|
|
|
|
Run every gate below from the repository root before committing. Every command
|
|
must succeed; do not commit code that is unformatted, fails Clippy, or compiles
|
|
with warnings.
|
|
|
|
```sh
|
|
cargo fmt --all -- --check
|
|
RUSTFLAGS="-D warnings" cargo check --workspace --all-targets
|
|
cargo clippy --workspace --all-targets -- -D warnings
|
|
cargo test --workspace
|
|
```
|
|
|
|
Do not weaken or skip these gates to make a commit pass. Fix the underlying
|
|
warning, lint, formatting issue, or test failure.
|
|
|
|
## Rust and Swift ownership boundary
|
|
|
|
Rust owns all application behavior. Put networking, authentication, input
|
|
validation, persistence, preference changes, filtering, sorting, aggregation,
|
|
parsing, content classification, display-data formatting, and navigation target
|
|
derivation in `crates/app`. Cover non-trivial behavior there with Rust tests and
|
|
expose view-ready records and operations through UniFFI.
|
|
|
|
Swift is the native iOS presentation layer. Limit `ios/Sources` to UIKit and
|
|
SwiftUI lifecycle, view-controller navigation, native controls, layout, drawing,
|
|
fonts, colors, symbols, accessibility, task cancellation tied to view lifetime,
|
|
and Apple presentation integrations such as Quick Look. Swift may map
|
|
Rust-provided states to visual treatments and maintain transient control state;
|
|
it must not infer domain state from display strings, duplicate Rust
|
|
transformations, classify content, or implement persistence and API behavior.
|
|
|
|
When changing iOS functionality:
|
|
|
|
- Trace the complete flow before editing and implement behavior in Rust first.
|
|
- Prefer view-ready Rust records over exposing raw Gitea models or rebuilding
|
|
titles, summaries, selections, progress, and categories in Swift.
|
|
- Treat a pure Swift helper that does not require an Apple UI framework as a
|
|
boundary warning; move it to Rust unless it only calculates view geometry.
|
|
- Regenerate and commit the UniFFI Swift and C bindings whenever the exported
|
|
Rust interface changes.
|
|
- During review, inspect both sides of the bridge and reject new business logic
|
|
added to Swift merely because its caller is a view controller.
|
|
|
|
## UI verification conventions
|
|
|
|
`TESTING.md` is the source of truth for iOS visual verification and the release
|
|
regression suite.
|
|
|
|
- Update `TESTING.md` in the same commit whenever UI appearance, behavior,
|
|
navigation, or interaction changes so its scenarios remain current.
|
|
- For each ordinary commit, run every `TESTING.md` scenario relevant to the
|
|
changed UI in addition to the required pre-commit gates. Report which visual
|
|
scenarios were exercised.
|
|
- When asked to perform a release test, run the complete `TESTING.md` checklist.
|
|
Every scenario must succeed before reporting release sign-off; record failures
|
|
and resolve release blockers instead of skipping them.
|
|
|
|
## iOS simulator build and deployment
|
|
|
|
This Apple Silicon project builds the simulator app for `arm64`. Do not disable
|
|
code signing: the Rust build script consumes Xcode's generated simulator
|
|
entitlement paths. Do not request an `x86_64` simulator build unless the
|
|
`x86_64-apple-ios` Rust target has explicitly been installed.
|
|
|
|
Use this sequence from the repository root:
|
|
|
|
```sh
|
|
cd ios
|
|
xcodegen generate
|
|
|
|
xcodebuild \
|
|
-project Gotcha.xcodeproj \
|
|
-scheme Gotcha \
|
|
-configuration Debug \
|
|
-sdk iphonesimulator \
|
|
-destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
|
|
ARCHS=arm64 \
|
|
ONLY_ACTIVE_ARCH=YES \
|
|
build
|
|
|
|
gotcha_build_dir="$(
|
|
xcodebuild \
|
|
-project Gotcha.xcodeproj \
|
|
-scheme Gotcha \
|
|
-configuration Debug \
|
|
-sdk iphonesimulator \
|
|
-destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
|
|
-showBuildSettings -json \
|
|
ARCHS=arm64 \
|
|
ONLY_ACTIVE_ARCH=YES |
|
|
plutil -extract 0.buildSettings.TARGET_BUILD_DIR raw -o - -
|
|
)"
|
|
xcrun simctl install booted "$gotcha_build_dir/Gotcha.app"
|
|
xcrun simctl launch booted de.rfc1437.gotcha
|
|
```
|
|
|
|
Before deploying, check for a booted simulator with
|
|
`xcrun simctl list devices available`. If none is booted, boot an available
|
|
iPhone (currently `xcrun simctl boot "iPhone 17 Pro"`) and open Simulator.
|
|
CoreSimulator access may require running `xcodebuild` and `simctl` outside the
|
|
workspace sandbox.
|
|
|
|
## Generated build data
|
|
|
|
Use Xcode's default DerivedData location; do not pass `-derivedDataPath`.
|
|
Cargo's ignored `target/` directory is a disposable build cache. Cargo does not
|
|
bound or garbage-collect stale target artifacts, so check it with
|
|
`du -sh target` and run `cargo clean` when disk space is worth a full rebuild.
|
|
Do not add a custom cache-pruning tool or disable incremental compilation just
|
|
to reduce routine cache usage.
|