Change recipes
The everyday changes, and the steps that make them land. Follow a recipe end to end; stopping halfway is how a feature works on one screen and nowhere else.
1. Add a user-visible string
- Add the key to
app/src/main/res/values/strings.xmlandapp/src/main/res/values-zh-rCN/strings.xml, with matching positional format args. - Run
python3 scripts/check_string_parity.py. The gate fails on a missing key, a mismatched key set, or a different number of format args. - Reference it with
stringResource(R.string.your_key).
2. Add parsing, filtering or detection logic
- Put it in
core/<area>/as pure Kotlin — no Android framework types. - Add a unit test under
app/src/test/java/…/core/<area>/. - Keep the ViewModel and the engine thin: they call the pure function and publish the result.
LogFilter.fromLine is the model for "build a filter out of a log line": pure, tested, and it returns the model rather than saving anything.
3. Change the logcat stream
- One process, owned by
LogcatEngine. Never spawn a secondlogcat. - Keep the
-Tresume stamp, so a reconnect does not dump the ring again. - Keep the API 33+ foreground rule: an app-uid logcat may not start while the app is in the background.
- If you add a buffer, add it to
LogcatSource.buildCommandand toLogcatCommandTest.
4. Change a foreground service
- Use
specialUse, neverdataSync— Android 15 capsdataSyncat six hours per 24 hours, which a long-lived service cannot stay under. - Start it with
startForegroundOrFalse. A refused start must stop the service, never take the process down. - Record the refusal (
watchBlockedAt) so the next attempt is not immediate, and say so in the UI instead of claiming the service is alive.
5. Change the list UI
- New presentational pieces go into
StreamChrome.kt;StreamScreen.ktkeeps state and gestures. - Geometry that maps positions to indices goes into a pure object with tests —
ScrollRailMathis the model. - Anything the user sees as a number should come from one place, so the screen and the rail cannot disagree.
6. Change the SDK
- The SDK stays permission-free, network-free, and free of libsu.
- It may only read its own host app's logs.
- Verify with the
:sampleapp on a device:Sleuth.init→ capture → crash → share the zip.
7. Ship it
See Releasing for the version bump, the release notes and the tag. The delivery loop itself is in AGENTS.md and CONTRIBUTING.md.