SoftwareApp
f9305d1070
Play asks separately about FOREGROUND_SERVICE_DATA_SYNC: which use case, what
the service does, what the user loses if the task is deferred or interrupted,
and a video of the user triggering the work. The answers are now in section 5
of the release checklist, and the video is recorded.
The use case is Local processing -> Importing, exporting. Play's own chart
describes it as moving files from an SD card locally, which is what Paste and
Copy to... / Move to... do. The description (482/500 characters) names every
OperationKind - COPY, MOVE, DELETE, COMPRESS, EXTRACT - and states that the app
has no INTERNET permission, so network processing, backup/restore and media
transcoding are explicitly not ticked.
The video (18.0 s, captions burned in) shows a 1.8 GB synthetic folder copied to
another local folder: the selection and Copy, Paste here, the "Copying files"
notification with its progress bar, and the completed folder. It is cut from a
35.2 s raw take to remove the two waits; the target listing stays empty until
the copy completes, so those frames are progress rather than failure. The shade
was cleared of the phone's weather and Play cards first, leaving only Android's
generic USB cards, and every filename is synthetic.
Two traps are written down: do not press Up after Copy, because the selection
is already in AADemo and an extra Up makes Paste target AADemo ("Items already
exist here"); and open the shade only after cmd notification list shows the
app's notification, or the video shows no evidence of the service.
Verified: ./tools/verify.sh green, the code map current, links resolve, both
videos decode as H.264 1080x2400 with no audio, and the SRT has five cues.
137 lines
8.8 KiB
Markdown
137 lines
8.8 KiB
Markdown
# Working in this repository
|
|
|
|
**Plain Files** is a file manager for Android: Kotlin and Jetpack Compose, one Gradle module
|
|
(`app`), `minSdk` 26, `targetSdk` 36, and **no `INTERNET` permission** — "nothing leaves the
|
|
device" is a shipping requirement of this app, not a slogan. It is sold once (no ads, no
|
|
subscription, no billing code), and the prose in `docs/` is treated as part of the product.
|
|
|
|
Two habits shape everything here. **The app is driven on a real device** for anything a user can
|
|
see, and what that proved is written down. **A test name is a sentence** about behaviour, so the
|
|
suite doubles as the specification.
|
|
|
|
## Read these two first, and only then the source
|
|
|
|
| file | why |
|
|
|---|---|
|
|
| `docs/CODE_MAP.md` | Generated index of the source tree: what each file holds, and every test name in the suite. Start here for "which file is this in?" |
|
|
| `docs/ROADMAP.md` | Which milestone is done, the key decisions, and the deliberate deferrals |
|
|
|
|
Do **not** read `CHANGELOG.md` front to back — it is long, and it is meant to be grepped by
|
|
feature name once you know what you are changing.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
./tools/verify.sh # the gate: map check, detekt, tests, lint
|
|
./tools/verify.sh --release # ...and an R8 release build (what CI runs nightly)
|
|
GRADLE_FLAGS=--offline ./tools/verify.sh # when the network is unavailable
|
|
|
|
./gradlew :app:assembleDebug # then: adb install -r app/build/outputs/apk/debug/app-debug.apk
|
|
./tools/measure-startup.sh 5 # cold start, median of five, on the installed device
|
|
./gradlew :benchmark:connectedDebugAndroidTest # the four macrobenchmark tests (needs a device)
|
|
# add -PbenchmarkBuild: it targets the benchmark build
|
|
./gradlew :app:detektBaseline # re-freezes the findings that exist now — think before running it
|
|
python3 tools/make-code-map.py # regenerate docs/CODE_MAP.md after touching source
|
|
```
|
|
|
|
CI (`.github/workflows/verify.yml`) runs the same script on every push and pull request, plus a nightly
|
|
`--release` build, because R8 is the one check nothing else performs and it has hidden a real defect
|
|
here before. `git config core.hooksPath .githooks` runs it before every push as well.
|
|
|
|
The detekt gap it leaves — the findings in `config/detekt/baseline.xml` — is a **ratchet**: new
|
|
findings fail the build, existing ones are parked until the file they live in is touched for another
|
|
reason. `tools/` holds the gate and the generators; `config/detekt/` holds the rules and that baseline.
|
|
|
|
## Where things live, and the one rule about direction
|
|
|
|
```
|
|
core/ pure Kotlin, no Android imports: paths, names, kinds, sorting, planning
|
|
data/ storage backends (all-files access, SAF), volumes, shares, SQLite search/trash/favourites
|
|
domain/ operations over a source: copy/move/delete/rename, archives, search, duplicates
|
|
service/ the foreground service that keeps a long operation alive
|
|
ui/ Compose: browser/, viewer/, usage/, trash/, duplicates/, theme/
|
|
text/ domain enum to string resource
|
|
```
|
|
|
|
The dependency direction is `ui → domain → data → core`, and `core/` importing `android.*` or
|
|
`androidx.*` is a test failure, not a matter of taste: it is what keeps the trickiest logic
|
|
testable without Robolectric. `docs/CODE_MAP.md` has the per-file detail.
|
|
|
|
## Non-negotiables
|
|
|
|
Each of these is enforced somewhere, so breaking one fails a test, lint, or a reviewer's first
|
|
comment. `app/src/test/java/…/ProjectInvariantsTest.kt` holds the source-level ones.
|
|
|
|
- **No new permission, and never `INTERNET`.** The manifest's permission set is asserted exactly;
|
|
adding one means deciding it, explaining it in the manifest comment and the README, and updating
|
|
that list deliberately.
|
|
- **Every user-visible string comes from `strings.xml`.** The debug build enables a pseudo-locale
|
|
(`values-en-XA`), so untranslated text is visible on screen as unaccented text.
|
|
- **A name is one path segment.** `core/FileNames.isUsableName` is the only implementation; never
|
|
inspect `/` yourself. `StoragePath.child("a/b")` resolves *into a subfolder*, so an unguarded
|
|
call renames or creates something the dialog never offered.
|
|
- **Nothing is overwritten silently.** Operations refuse rather than destroy; deletes go through
|
|
the trash (24-hour window) and offer undo; a batch that cannot succeed is refused as a whole
|
|
rather than performed until it hits the problem.
|
|
- **Comments explain why, not what.** The house style is a KDoc paragraph per file and type that
|
|
says what it is for and what was rejected — decisions and limits, not restatements of the code.
|
|
- **A test name is a sentence about behaviour** (`a batch rename is a single undo step`), because
|
|
the names are read as the spec. Logic gets behaviour tests, rules about the shape of the project
|
|
get source-level tests, and **what a user sees gets a Compose rendering test** — those run on the
|
|
JVM through Robolectric, so they are part of the same gate rather than needing a device.
|
|
- **The docs are part of the change.** `CHANGELOG.md` (Added/Changed/Fixed, in the house voice),
|
|
the `ROADMAP.md` milestone table, the README if a claim changed, and `docs/EDGE_CASE_TESTING.md`
|
|
for anything only a device could confirm.
|
|
|
|
## Traps that have cost real time here
|
|
|
|
- **MIUI blocks `adb install` twice over.** Developer options needs *Install via USB*, and each
|
|
install then waits for a confirmation dialog that times out on its own. A bare
|
|
`INSTALL_FAILED_USER_RESTRICTED` means the dialog was answered late, not that the APK is bad.
|
|
- **Never run `assembleDebug` and `adb install` in one parallel batch.** They race, the install
|
|
takes the previous APK, and the feature you just wrote appears to be missing.
|
|
- **R8 has hidden real bugs.** A class reached only by reflection, or named only from a resource,
|
|
is stripped from the release build while debug works perfectly — this happened with `coil-video`,
|
|
where video frames decoded in debug and quietly fell back to icons for real users. When debug and
|
|
release disagree, assume the shrinker removed something.
|
|
- **`adb input text` does not deliver a `/`.** Send `input keyevent 76` instead. The slash is worth
|
|
testing at all because the field *accepts* it and the dialog is what refuses it.
|
|
- **Long-press multi-select via `input swipe x y x y 900` works, but not every time** — it has also
|
|
landed as a plain tap. A flaky gesture is a reason to look at the screen, not to distrust the code.
|
|
- **The debug build is a separate package** (`…filemanager.debug`), so it installs beside a release
|
|
build and the two can be compared directly.
|
|
|
|
- **detekt 1.23 cannot run on JDK 25.** It parses the version string of the JVM it runs on and
|
|
throws `25.0.4.1` as the entire error message, which is why `:app:detekt` drives the CLI on a 21
|
|
launcher. A bare version number as a build failure is this, not the code — and a **JDK 21 has to be
|
|
installed** for the toolchain to find: Gradle does not download one here.
|
|
- **A detekt baseline has to exist before it can be read.** It starts as an empty document on
|
|
purpose; `--create-baseline` cannot conjure the path it was told to consult.
|
|
|
|
## Documentation map — read on demand
|
|
|
|
| file | what it is for |
|
|
|---|---|
|
|
| `README.md` | The tour: features, layout, build, and the honest **known limitations** |
|
|
| `CHANGELOG.md` | The reasoning behind each change. Grep it; do not read it end to end |
|
|
| `docs/ROADMAP.md` | Milestones with their evidence, the key decisions, the deferrals |
|
|
| `docs/EDGE_CASE_TESTING.md` | What was verified, on which device or AVD, and what was not |
|
|
| `docs/PERFORMANCE.md` | The numbers that exist, and the ones that deliberately do not yet |
|
|
| `docs/PLAY_RELEASE_CHECKLIST.md` | Release only — work it in order |
|
|
| `docs/RELEASE_NOTES.md` | The Play **What's new** copy, at 500 characters, and the longer announcement |
|
|
| `docs/PERMISSION_VIDEO.md` | The declaration's 23-second video: what it shows, and how to re-shoot it |
|
|
| `docs/FGS_VIDEO.md` | The foreground-service video: the local copy, what was cut, and how to re-shoot it |
|
|
| `docs/COMPETITIVE_ANALYSIS.md`, `docs/MONETISATION.md`, `docs/STORE_LISTING.md` | Product context, pricing, and length-checked listing copy |
|
|
| `PRIVACY.md` | The policy text the store listing points at |
|
|
|
|
## Definition of done
|
|
|
|
1. `./tools/verify.sh` green — the map current, detekt, the unit tests and lint in one command.
|
|
2. `python3 tools/make-code-map.py` run, so that `--check` passes.
|
|
3. A `CHANGELOG.md` entry in the house voice: what changed, why, what was rejected, and what was
|
|
verified rather than assumed.
|
|
4. Anything a user can see driven on a device or emulator, with the result written into
|
|
`docs/EDGE_CASE_TESTING.md` — including what was deliberately left untested, and why.
|
|
5. A commit whose subject is a sentence about the change and whose body explains the reasoning.
|
|
The diff already says what changed; the message is there for why it is this way.
|