From 3e86ca14e6d0ebf7d86f5c86391dfab97d7a1197 Mon Sep 17 00:00:00 2001
From: zarzet <42882290+zarzet@users.noreply.github.com>
Date: Sun, 18 Oct 2026 21:51:59 +0700
Subject: [PATCH] docs(contributing): match the repository (l10n, gradle,
 ffmpeg, test layers)

Generated l10n sources are gitignored, there is no Gradle wrapper, some tests need ffmpeg, and the test layers and boundary directories were undocumented.
---
 CONTRIBUTING.md | 35 ++++++++++++++++++++++++++++++-----
 1 file changed, 30 insertions(+), 5 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b5a8a94b..b7970aa7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -134,6 +134,8 @@ rust_backend/ Production backend, native bindings, and unit tests
 android/      Android platform bridge and foreground worker
 ios/          iOS platform bridge and application project
 test/         Flutter unit and widget tests
+integration_test/ Device and emulator tests (including performance drivers)
+third_party/  Vendored and patched packages (audio_service, Discord bridge)
 assets/       Images, fonts, and bundled resources
 docs/         Local documentation and migration archives (gitignored)
 scripts/      Reproducible project build helpers
@@ -147,8 +149,10 @@ should consume that declaration without knowing which extension uses it.
 
 ## Generated Files
 
-- After changing ARB files, run `fvm flutter gen-l10n` and commit the resulting
-  localization sources.
+- After changing ARB files, run `fvm flutter gen-l10n` (or `fvm flutter pub get`)
+  to refresh the localization sources. They are generated and not committed:
+  `.gitignore` carries `/lib/l10n/app_localizations*.dart` ("Generated by
+  Flutter from lib/l10n/arb during pub get/build."). Commit only the ARB files.
 - Run `fvm dart run build_runner build --delete-conflicting-outputs` only when a
   model or generator input changes, then commit the relevant generated source.
 - Do not commit `build/`, `.dart_tool/`, AAR/XCFramework output, IDE state, or
@@ -164,6 +168,17 @@ Cross-language lyric usability cases live in
 tests read the same cases; add a case there when changing
 that policy.
 
+Test layers:
+
+| Layer | Location | Command |
+| --- | --- | --- |
+| Dart unit and widget | `test/` | `fvm flutter test` |
+| Device and emulator | `integration_test/` | `fvm flutter test integration_test/<file>` |
+| Performance | `integration_test/*_performance_test.dart` | `fvm flutter drive --driver=integration_test/performance_driver.dart --target=integration_test/<file> --keep-app-running` |
+| Kotlin JVM | `android/app/src/test/` | `gradle -p android :app:testDebugUnitTest` |
+| Rust | `rust_backend/` | `bash scripts/check_rust_backend.sh` |
+| Python script tests | `scripts/test_*.py` | `python3 -m unittest discover -s scripts -p 'test_<name>.py'` |
+
 Flutter and Dart:
 
 ```bash
@@ -172,17 +187,27 @@ fvm flutter analyze
 fvm flutter test
 ```
 
+Some Dart tests render audio and need `ffmpeg` and `ffprobe` on `PATH`. Set
+`SPOTIFLAC_TEST_FFMPEG` to an `ffmpeg` binary to override the lookup.
+
+Performance drive runs need a dedicated emulator, `--profile` on Android and
+`--debug` on iOS simulators. See the header of
+`integration_test/performance_driver.dart`.
+
 Rust formatting, Clippy, and unit tests:
 
 ```bash
 bash scripts/check_rust_backend.sh
 ```
 
-Android native code (Gradle builds the Rust artifacts automatically):
+Android native code (Gradle builds the Rust artifacts automatically). The
+repository has no Gradle wrapper; install the Gradle version CI uses
+(`.github/workflows/ci.yml`) and generate the Flutter configuration first:
 
 ```bash
-cd android
-./gradlew :app:compileDebugKotlin :app:testDebugUnitTest
+fvm flutter pub get
+fvm flutter build apk --config-only
+gradle -p android :app:compileDebugKotlin :app:testDebugUnitTest
 ```
 
 For user-facing changes, add or update tests where practical and include