From a0d63a36635f6848e9b740c23d60f260e03d65d7 Mon Sep 17 00:00:00 2001 From: "alexei.dolgolyov" Date: Tue, 21 Apr 2026 20:01:26 +0300 Subject: [PATCH] docs(release): drop stale WLED-rename task, document android signing secrets - Remove the top-of-file "IMPORTANT: Remove WLED naming throughout the app" checklist. The effort was absorbed by the multi-backend refactor (BLE / USB-serial / ESP-NOW / MQTT / OpenRGB providers all shipped), and the remaining user-facing copy has been swept in separate commits. - Add an "Android Signing Secrets (Gitea)" section covering the four secrets the release APK CI expects, the one-off `keytool` command to generate `release.jks`, the consequences of losing the keystore, and a checklist of the remaining setup steps before tagging v0.4.1. --- TODO-release.md | 56 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 45 insertions(+), 11 deletions(-) diff --git a/TODO-release.md b/TODO-release.md index de13eaf..99b2944 100644 --- a/TODO-release.md +++ b/TODO-release.md @@ -1,16 +1,5 @@ # TODO -## IMPORTANT: Remove WLED naming throughout the app - -- [ ] Rename all references to "WLED" in user-facing strings, class names, module names, config keys, file paths, and documentation -- [ ] The app is **LedGrab** — not tied to WLED specifically. WLED is just one of many supported output protocols -- [ ] Audit: i18n keys, page titles, tray labels, installer text, pyproject.toml description, README, CLAUDE.md, context files, API docs -- [ ] Rename `ledgrab` package → decide on new package name (e.g. `ledgrab`) -- [ ] Update import paths, entry points, config references, build scripts, Docker, CI/CD -- [ ] **Migration required** if renaming storage paths or config keys (see data migration policy in CLAUDE.md) - ---- - ## Donation / Open-Source Banner - [x] Add a persistent but dismissible banner or notification in the dashboard UI informing users that the project is open-source and under active development, and that donations are highly appreciated @@ -18,3 +7,48 @@ - [x] Remember dismissal in localStorage so it doesn't reappear every session - [x] Add i18n keys for the banner text (`en.json`, `ru.json`, `zh.json`) - [ ] Configure `DONATE_URL` and `REPO_URL` constants in `donation.ts` once platform is chosen + +## Android Signing Secrets (Gitea) + +The CI workflow `build-android.yml` produces a signed release APK **only** when all four secrets below are configured in Gitea → Settings → Secrets. When any one is missing, the "Guard release tag against missing keystore" step hard-fails a `v*` tag build — previously we silently shipped a debug-signed APK labeled as release. + +| Secret | Contents | +| --- | --- | +| `ANDROID_KEYSTORE_BASE64` | Output of `base64 -w0 release.jks` — the whole keystore as one line | +| `ANDROID_KEYSTORE_PASSWORD` | Keystore password (the `-storepass` passed to `keytool`) | +| `ANDROID_KEY_ALIAS` | Key alias (e.g. `ledgrab-release`) | +| `ANDROID_KEY_PASSWORD` | Key password (can be the same as keystore password) | + +### Generate the keystore (one-time, ~2 min) + +```bash +keytool -genkeypair -v \ + -storetype JKS \ + -keystore release.jks \ + -alias ledgrab-release \ + -keyalg RSA -keysize 4096 \ + -validity 9125 \ + -dname "CN=LedGrab, O=Dolgolyov, C=BY" + +base64 -w0 release.jks > release.jks.b64 # Linux / Git Bash +# Windows alternative: +# certutil -encode release.jks release.jks.b64 +# (strip the -----BEGIN/END CERTIFICATE----- header/footer lines) +``` + +### Critical — back up `release.jks` outside the repo + +- 1Password attachment, encrypted USB stick, or printed hex + password written down somewhere physical. +- Losing the keystore = every existing sideloaded install is permanently unable to upgrade. The only workaround is uninstall-then-reinstall, which wipes user data. +- The `release.jks` file itself must **never** be committed to git. Only the base64 string lives in Gitea secrets. + +### Why it matters even without Play Store + +Android's package manager refuses to install an upgrade whose signature differs from the currently-installed APK's signature — enforced by the OS, not Play. So once users install a build signed by key X, every future build they can upgrade to must also be signed by key X. + +### Current state + +- [ ] Generate `release.jks` with `keytool` (above) and back it up +- [ ] Upload the four secrets to Gitea +- [ ] Tag a throwaway `v0.4.1-test` to verify signed release APK is produced (then delete the tag + release) +- [ ] Note: any existing `v0.4.0` debug-signed install cannot upgrade to a release-signed v0.4.1 — users must uninstall first