Files

67 lines
3.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Project Instructions: EtchDroid
This repository hosts **EtchDroid**, an Android application for writing OS images to USB drives.
## Project Structure
- `app/` – Android app module
- `src/main/` – Kotlin sources and Compose UI
- `src/foss/` – F-Droid flavor overrides
- `src/gplay/` – Google Play flavor overrides (telemetry, in-app review)
- `src/test/` – Unit tests
- `appium-tests/` – End-to-end tests written in Python with Appium.
- `misc/` – Helper scripts and `mock-google-services.json` used for GPlay builds
- `fastlane/` – Play Store text and images
- Top-level `build.gradle.kts` and `settings.gradle.kts` define the Gradle build.
## Development Workflow & Conventions
### 1. Linear History (No Merge Commits)
We use a **rebase-only workflow**. Your branch must be rebased onto the latest `main` branch.
- **Do:** Use `git rebase main`.
- **Don't:** Use `git merge main`.
### 2. Atomic & Concise Commits
- **One Thing Per Commit:** Each commit should perform one logical task.
- **Separate Cleanup from Logic:** Do not lump stylistic/formatting/cleanup changes into functional commits.
- **Commit Messages:** Be descriptive. Use [Conventional Commits](https://www.conventionalcommits.org/) format (e.g., `feat(ui): add progress bar`).
### 3. Build and Unit Test
- The first build and test run may take up to **10 minutes**.
- Run the build as a background process (`is_background: true`) and log to a file for long runs.
- Do not use `--scan` when invoking Gradle.
#### FOSS variant
1. Ensure `ETCHDROID_ENABLE_SENTRY` is **unset** or empty.
2. Build: `./gradlew assembleFossDebug`
3. Test: `./gradlew testFossDebugUnitTest`
#### GPlay variant
1. Set `ETCHDROID_ENABLE_SENTRY=true`.
2. Prepare: `cp misc/mock-google-services.json app/google-services.json`
3. Build: `./gradlew assembleGplayDebug`
4. Test: `./gradlew testGplayDebugUnitTest`
### 4. End-to-End (Appium) Tests
Agents should run Appium tests unless instructed otherwise.
- Requirements: Android SDK, `uv`, `7z`, `qemu-img`, `node`/`npm` installed.
- **Install Appium**:
```bash
cd appium-tests
npm ci
```
- Location: `appium-tests/`
#### Running Bliss OS VM locally:
1. Prepare the VM files: `./appium-tests/scripts/prepare-vm.sh` (downloads ISO, extracts files, creates USB image in `.appium-vm/`).
2. Run the VM (in a separate terminal): `./appium-tests/scripts/run-vm.sh` (shows GTK UI, serial console on stdio, ADB on 5556).
3. Wait for the VM to boot: `./appium-tests/scripts/wait-vm-startup.sh`
4. Build and install the app: `./gradlew installFossDebug`
5. Run the tests: `uv run pytest -sv` (inside `appium-tests/`)
- Run only generic tests (excluding QEMU): `uv run pytest -m "not qemu" -sv`
- *Note: QEMU tests require a specific setup (see `appium-tests/README.md`). If the environment supports KVM/QEMU, they should be run.*
- **Proxy gotcha:** if `HTTP_PROXY`/`HTTPS_PROXY` are set in the environment, selenium/urllib3 route the localhost Appium connection through the proxy and fail with `SSL: CERTIFICATE_VERIFY_FAILED`. Exclude localhost when running: `NO_PROXY=127.0.0.1,localhost,127.0.0.10 no_proxy=127.0.0.1,localhost,127.0.0.10 uv run pytest -sv`.
### 5. Linting
Run `./gradlew lint` before submitting changes.