e9899d2e6d
Some checks failed
Android CI Build / check (push) Has been cancelled
Android CI Build / package-apks (push) Has been cancelled
Docs Deploy / build (push) Has been cancelled
Module Market Check / Validate modules/ (push) Has been cancelled
Module Market Publish / Generate submissions.json (push) Has been cancelled
Docs Deploy / deploy (push) Has been cancelled
- Package rename com.webtoapp -> br.com.drukstech.codeapp - Product rename WebToApp/web-to-app -> DruksCode/drukscode - Design system Wta* -> Dkc* - applicationId br.com.drukstech.codeapp (.play for gplay flavor) - rootProject.name DruksCode - Fresh git history (upstream kept as remote for sync)
50 lines
2.4 KiB
Markdown
50 lines
2.4 KiB
Markdown
# Config Field Drift
|
|
|
|
The most common silent failure in DruksCode: a feature works in preview but is quietly skipped in the exported APK because a config field name drifted between the export factory and the shell config class.
|
|
|
|
## Why it happens
|
|
|
|
The shell reads its config with **Gson**, and Gson **silently drops** unknown or missing fields — no exception, no log. So if the JSON key written by the export factory does not exactly match the `@SerializedName` on the shell config field, the feature just… doesn't run, with no error.
|
|
|
|
The three things that must stay aligned:
|
|
|
|
1. The payload keys in `ApkConfigJsonFactory.kt` (the `"key" to value` pairs).
|
|
2. The `@SerializedName("key")` annotations in `ShellModeManager.kt`'s shell config classes.
|
|
3. The `ApkConfig` fields they map from.
|
|
|
|
## The gate
|
|
|
|
A CI gate checks this automatically:
|
|
|
|
```bash
|
|
./gradlew :app:checkConfigFieldDrift --no-configuration-cache
|
|
# or directly:
|
|
python3 scripts/check_config_field_drift.py
|
|
```
|
|
|
|
It parses the payload keys out of `ApkConfigJsonFactory.kt` and the `@SerializedName` annotations out of `ShellModeManager.kt`, then reports any mismatch (subject to an allowlist in `scripts/config_field_drift_allowlist.json`).
|
|
|
|
**Run it whenever you change config fields.** It is part of the Android CI `check` job.
|
|
|
|
## Diagnosis checklist
|
|
|
|
When a feature "works in preview, broken after export," check in this order:
|
|
|
|
1. Did the shell config JSON actually contain the field at runtime?
|
|
2. Does the field name in `ApkConfig` JSON match the `@SerializedName` in shell config? Run `checkConfigFieldDrift`.
|
|
3. Is the runtime use site shell-synced (not host-only)?
|
|
4. For adblock specifically: confirm `adBlockEnabled` mapping, host filter rebuild from cached subscriptions, and export rule compile without wiping host state.
|
|
5. Rebuild the template after sync changes (stale template is a frequent miss).
|
|
|
|
## Adding a setting that affects the generated APK
|
|
|
|
Trace and update **all** of:
|
|
|
|
1. Model (`WebApp` / nested config) and editor UI binding.
|
|
2. Export mapping (`ApkBuilder` / `ApkConfig` / `ApkConfigJsonFactory`).
|
|
3. Shell config types (`ShellModeManager` / shell config data classes) if the runtime reads them.
|
|
4. Runtime use site in shell-synced code.
|
|
5. Unit tests for export wiring when flags change.
|
|
|
|
Missing any step usually yields: editor shows the switch, export ignores it, or export embeds config the runtime never reads.
|