Releasing

WM Keyboard ships through three channels, and they are not the same build. The differences are real: a Play build carries Google libraries that an F-Droid build must not have. But a handful of boolean flags and one flavor drive all of it, so nothing here needs a branch or a patched source tree.

What the channels actually differ on

	GitHub release	F-Droid	Play Store
Flavor	full and lite, each in intl and en	lite, intl	full, en
Gradle task	the four assemble*Release	assembleLiteRelease, an alias for assembleLiteIntlRelease	bundleFullEnRelease
wmkb.enablePlayStore	false	false	true
wmkb.enableGms	true	false	true
wmkb.enableFdroid	false	true	false
wmkb.splitApks	true	not used	ignored by bundle*
wmkb.enableCrashScreen	not set	not set	false, forced by the Fastfile over local.properties
Automation TYPE_TEXT	offered	offered	left out
Artifact	one APK per ABI, for all four flavor combinations, plus R8 mappings, native symbols and SHA256SUMS.txt	one APK, built by F-Droid, carrying our signature once it matches the release’s -fdroid.apk	one AAB, with its R8 mapping and native symbols inside
ML Kit	bundled in the APK	absent	unbundled, fetched from Play services
Local LLM	bundled	absent	on-demand :feature:llm module
On-device translation (ML Kit)	bundled	absent	on-demand :feature:translate module
LiteRT interpreter (offline Whisper, the sticker editor’s own background remover)	bundled	absent	on-demand :feature:litert module
Handwriting recognition (ML Kit)	bundled	absent	on-demand :feature:handwriting module
In-app updates	GitHub releases, downloads and installs	checks F-Droid, links out	Play In-App Updates

The flags read from a -P Gradle property first, then local.properties, then the environment, then default to false. -P winning is what lets a fastlane lane or CI override a developer machine’s local.properties. A clean checkout has no local.properties at all, which is why an F-Droid builder gets the right answer without being told.

wmkb.enableFdroid is the odd one out: it changes no dependency, only the channel line on bug reports and diagnostics, and it hides the “get it on F-Droid” row in About that would otherwise send an F-Droid user to their own install. The F-Droid recipe sets it explicitly, since false is the default everywhere else.

Keep the flags matched to the channel

The flags pick the updater, and the wrong updater is worse than none.

wmkb.enablePlayStore=true links Play’s in-app update library. That library only works for an install that actually came from Play, and calling completeUpdate() restarts the process, which kills a running keyboard. Never ship a Play-flagged build anywhere but Play.

With neither flag set the build gets the GitHub updater, which downloads an APK and installs it. Two things follow. Play’s Device and Network Abuse policy forbids an app distributed through Play from updating itself by any other route, so that code and its two permissions must never reach a Play build, which is what the source-set and manifest split below enforces. And a GitHub-channel build has to be signed with the release key, or it can never install over the published APK: Android refuses an update signed with a different key, and the app checks for that itself so the refusal at least arrives as a sentence rather than a silent failure.

wmkb.enableFdroid=true gets a checker that asks F-Droid and opens F-Droid, and no installer at all. F-Droid’s own client installs F-Droid builds, and installs up to 0.5.9 carry F-Droid’s key rather than ours.

Where the updater code lives

The channel picks source directories and a manifest overlay, wired through the Variant API in app/build.gradle.kts (channelSourceDirs and channelManifests). There is no product flavour for it: the channel is orthogonal to the others, and a dimension for it would double every variant and task name in the project for the sake of one file. The languages dimension was judged to be worth that price and the channel was not, because languages changes about 41 MB of what a user downloads.

Directory	Compiled when	Holds
app/src/play/java	enablePlayStore	PlayAppUpdater, and SplitInstall for :feature:llm and :feature:translate
app/src/noplay/java	otherwise	the no-op SplitInstall stub
app/src/github/java	neither flag	the release check, the download, and the package installer
app/src/fdroid/java	enableFdroid	the F-Droid index check
app/src/play/AndroidManifest.xml	enablePlayStore	a <queries> entry for the Play Store, so the app can see who installed it
app/src/github/AndroidManifest.xml	neither flag	REQUEST_INSTALL_PACKAGES, UPDATE_PACKAGES_WITHOUT_USER_ACTION, and the install-result receiver

Each of the three declares the same rememberAppUpdater(), against the AppUpdater interface in app/src/main. Everything worth unit testing (the asset-name parser, the release picker, the check interval, the install-status mapping) lives in src/main too, because src/test is compiled in every channel and a test that named a class from src/github/java would break check on a Play build.

To confirm the split holds, read the merged manifest rather than trusting the build file:

rm -rf app/build/intermediates/merged_manifest
./gradlew :app:processFullDebugMainManifest -Pwmkb.enablePlayStore=true
grep -c REQUEST_INSTALL_PACKAGES \
  app/build/intermediates/merged_manifest/fullDebug/processFullDebugMainManifest/AndroidManifest.xml

That has to print 0 for a Play build and 1 for a GitHub one.

Cutting a GitHub release

The Release workflow does the build. It runs on any tag starting with v and refuses to run if the tag disagrees with wmkb.versionName. A tag with no wmkb.versionName at all predates the property (v0.1.0 and v0.2.0 kept the version in app/build.gradle.kts), so the run stands down with a notice instead of comparing the tag against an empty string, and that release is written by hand. Neither of those two tags carries this workflow, so pushing them starts no run at all; the guard is for a tag that does reach it without a version to check. It signs with your release key, then attaches one APK per ABI for each of the four flavor combinations, plus a SHA256SUMS.txt, to the release.

The release also carries the files you need to read a crash report from those APKs. The *-mapping.txt.gz files are the R8 mappings — one per flavor combination (full-intl, full-en, lite-intl, lite-en), plus a fifth, *-play-mapping.txt.gz — and *-full-intl-native-symbols.zip and *-full-en-native-symbols.zip hold the native debug symbols. The two language builds are separate R8 runs, so their mappings are not interchangeable even though the Kotlin that went in was identical. Retrace a stack trace with the mapping from the same flavor and version:

gunzip -k wmkeyboard-0.5.9-vc24-full-intl-mapping.txt.gz
retrace wmkeyboard-0.5.9-vc24-full-intl-mapping.txt stacktrace.txt

The fifth one comes from the bundle job rather than the apks job, and it is there because the Play build is compiled with different channel flags, so R8 renames it differently and none of the other four fit a crash from a Play install. Play Console reads the copy inside the AAB and needs no upload; a reporter on GitHub cannot reach that copy, and neither can the retrace workflow below, so it is published like the rest.

The retrace workflow

Nobody has to do any of the above by hand for a crash pasted into an issue. retrace.yml watches new issues and comments, and when a body holds frames that look obfuscated it reads the version: line out of the app’s own crash record, fetches the matching mapping off that release, runs R8’s retrace over the whole body, and comments the result.

What makes the lookup deterministic rather than a guess is that the record names its build. DebugLog writes version: 0.5.9 (24) fullEn (Play Store), and the flavor there is the whole two-dimension name, which :app hands the log on startup — :core:common compiles against :core:config, whose BuildConfig.FLAVOR carries the capabilities dimension alone and would say just full. A record from an F-Droid install is refused with a note instead: the F-Droid build’s mapping is not published. From 0.5.10 that build is identical to the release’s -fdroid.apk, so its mapping could be.

Why a mapping is checked before it is used

A wrong mapping does not fail. It renames every frame, into names that read perfectly and mean nothing — #271 was a crash in the translate panel, from an F-Droid install, and the first version of this workflow retraced it into WmSlider and SoundPack because it picked whichever mapping renamed more frames, 57 against 56.

So before anything is retraced, each candidate mapping is checked against the trace: for a frame a.b(SourceFile:12), the mapping has to hold class a, a member renamed to b inside it, and a line range around 12. Matching the class alone proves nothing, because every mapping of this app holds thousands of two-letter class names. The method and line together are what a different R8 run cannot fake.

The separation is absolute, and measured rather than assumed — across #252, #253, #237 and #271 the correct mapping accounts for 100% of the frames and every wrong one for 0–20%, with nothing in between. Below 60% nothing is posted but a note saying so, which is what #271 gets now.

Commenting /retrace on an issue re-runs it against the issue body, which is what to do when a trace was pasted before its release was published.

The workflow treats every issue body as hostile text: it reaches the script through the environment and a file, never through a shell argument or a workflow expression inside a run: block, and the retraced output goes back inside a fence long enough that no backtick run in it can escape.

One-time setup

1. Base64 your keystore so it can live in a secret:

   base64 -i release.keystore | pbcopy

2. Add the signing secrets under Settings → Secrets and variables → Actions → New repository secret:

   Secret	Value
   KEYSTORE_BASE64	the base64 blob from step 1
   RELEASE_STORE_PASSWORD	keystore password
   RELEASE_KEY_ALIAS	key alias
   RELEASE_KEY_PASSWORD	key password

3. Add the API-key secrets you want baked into public builds: WMKB_KLIPY_API_KEY, WMKB_GIPHY_API_KEY, WMKB_BRAVE_API_KEY, WMKB_TRANSLATE_API_KEY, WMKB_UNSPLASH_API_KEY, WMKB_PEXELS_API_KEY, WMKB_DROPBOX_APP_KEY, WMKB_ONEDRIVE_CLIENT_ID. Any you leave out just make that tool show its “needs an API key” state, or leave that backup destination off the list, so a release without them still builds and runs.

Every release

1. Bump the version. wmkb.versionCode and wmkb.versionName in gradle.properties. The code must increase; the name is what the tag has to match.

2. Write the store changelog. fastlane/metadata/android/en-US/changelogs/<versionCode>.txt. F-Droid and Play both read this file, so it is usually the only place you write it. Play caps it at 500 characters. When Play needs different notes from F-Droid, put Play’s under fastlane/play/metadata/android/en-US/changelogs/<versionCode>.txt: the internal lane uploads that one instead, and F-Droid keeps the shared file. 0.5.10 does this, because its F-Droid notes open with the one-time reinstall for reproducible builds.

3. Write the release notes. release-notes/<versionName>.md, in the repo root. This is the prose at the top of the GitHub release: what changed, in sections, with issue links. Leave it out and the release falls back to the store changelog, which is a paragraph. That is fine for a bug-fix release and thin for anything else.

4. Tag and push.

   git tag v0.3.1 && git push origin v0.3.1

5. Watch the run. It builds the APKs, builds the Play AAB as a separate artifact, and publishes the release. The AAB is not attached to the public release, because an AAB is not installable. The play job uploads it to the Play internal track through fastlane instead, or skips itself with a warning if the PLAY_SERVICE_ACCOUNT_JSON secret is not set. Promoting to production stays a decision you make by hand.

6. Pull the settings-link refresh. Pushing the tag also starts the Settings links workflow (.github/workflows/settings-links.yml). It reruns scripts/extract_settings_links.sh and scripts/extract-settings-since.mjs, which read the tags to find which release first has each settings screen and row, and commits src/data/settings-since.json back to main. The /open/ page, the link builder and the settings chips show that as “Added in version …”. Until the workflow finishes, what the new tag shipped still reads Not released yet on the site. Pull main before you push again.

Telling the issues

Once the release is published, the issue-comments job calls release-comments.yml, which comments on every issue the release notes link. The comment names the version, mentions whoever opened the issue, lists the commits behind it, and says that F-Droid and Google Play take 2 to 3 days to catch up with the GitHub release. So the issue links you write in release-notes/<versionName>.md are also the list of people who hear about it.

When the change added settings, the comment links each one through https://wmkeyboard.pages.dev/open/, with since= set to the release, and notes that the links open only once that version is installed. Nothing records which settings belong to which issue, so the script works it out:

1. The commits. Every commit between the previous tag and this one whose message names the issue (Closes #285, Refs #285), the commits GitHub tied to it on the issue’s timeline (a reference, the closing commit, a merged pull request that mentions it), and any commit a maintainer’s comment names by hash. A commit outside the release’s range never counts.
2. The settings. A <string name> those commits added under src/main/res/values/ that the previous tag did not have, and that docs/src/data/settings-links.json lists as a screen or a row. A row’s link name is the resource name of its title, so this is an exact match. A new screen stands for the rows on it, so a new tool is one link, not twenty.

It runs from the release workflow rather than on release: published because the release is published with the workflow’s own token, and GitHub starts no workflow for an event that token caused. The release trigger is still there for a release you publish by hand. Every comment carries a hidden marker for its tag, so a second run for the same release posts nothing twice: it skips an issue it already told, or updates the comment if the text has changed.

Rehearse against any release that is already out, from the Actions tab (Release comments, dry run on by default, comments land in the run summary) or locally:

python3 .github/scripts/release_comments.py --tag v0.5.11 --dry-run
python3 .github/scripts/release_comments.py --tag v0.5.11 --dry-run --only 285,302

A draft, a pre-release, or a release with no APKs attached is left alone.

What the release body looks like

.github/scripts/release-notes.sh builds it in the publish job, after the APKs have been downloaded back from the apks job. Three parts:

1. What’s new: release-notes/<versionName>.md verbatim, inside a <details open> so it can be folded away, or the store changelog if that file is absent.
2. Download: a grid of architecture against flavour, starred on arm64-v8a, every cell carrying the file’s real size. The sizes are measured from the artifacts that were actually built, so a cell whose file is missing shows an em dash rather than a link to a 404. Checksums, R8 mappings and native symbols sit in a collapsed block under it.
3. One line giving the commit count since the previous tag, linking the compare view.

The publish job then makes the release as a draft, uploads the files one at a time, and only publishes it once they are all attached, so a watcher never sees a release with half its APKs on it. It uses the gh CLI rather than softprops/action-gh-release, which failed the 0.5.9 publish with Error creating asset temp dir after attaching three of twelve files. The whole step is idempotent, so re-running it after a failure edits and re-uploads over whatever the last attempt managed.

A re-run replays the workflow from the tag

Actions runs the workflow file as it was at the ref that triggered it, so fixing release.yml on main does nothing for a re-run of a tag cut before the fix. Attach the files by hand in that case: gh run download <run-id> --name release-apks, then gh release upload <tag> --clobber <files> and gh release edit <tag> --draft=false --latest.

There is deliberately no generated list of commit subjects. The prose in release-notes/ is the changelog; the compare view is a better place to read every commit than a wall of subjects in the release body.

Preview the whole body without cutting a release, against artifacts you already have in dist/:

.github/scripts/release-notes.sh 0.5.9 20 v0.5.9 dist wasi-master/wmkeyboard

Rewriting a release that is already out

.github/scripts/backfill-release-notes.sh puts a published release’s body through the same generator, and creates the release when a tag has none:

.github/scripts/backfill-release-notes.sh --dry-run v0.4.0
.github/scripts/backfill-release-notes.sh v0.4.0 v0.4.1

It downloads nothing. The asset list from the API carries each file’s byte count, and the script writes sparse stand-ins of exactly that size for the generator to measure, so the grid ends up with the real numbers. Two details it handles on its own: 0.3.0 predates the versioned filenames, so its grid is pointed back at the app-<flavor>-<abi>-release.apk names actually attached; and a release it creates passes --latest=false, because a tag cut after the fact must not take the Latest badge that the in-app updater reads.

Rehearse without publishing

Run the workflow from the Actions tab with dry run left on. Everything builds and uploads as workflow artifacts, and no release is created.

Getting into F-Droid

F-Droid does not take your APK as it is. It builds from source on its own machines, and publishes our signature only after its build turns out identical to ours (see Reproducible builds below). Building from source is why the lite flavor exists. Every proprietary dependency in the tree (ML Kit, LiteRT, Play’s update and feature delivery libraries, play-services-auth) is declared fullImplementation or sits behind a channel flag, so lite has no Google artifact on its compile classpath at all.

The recipe’s gradle: list names one flavour, lite, as it has since before :app had a second dimension. fdroidserver joins that list into a task name, so what it runs is assembleLiteRelease. AGP stopped registering a task by that name when the languages dimension arrived in 0.5.10: with two dimensions it offers assembleLiteIntlRelease and assembleLiteEnRelease, and answers the old name with an ambiguity error.

So app/build.gradle.kts registers assembleLiteRelease itself, as an alias for assembleLiteIntlRelease. The alias is there because the recipe cannot be counted on to change. AutoUpdateMode: Version writes each new Builds: entry by copying the last one, gradle: [lite] included, and nobody reviews what the bot writes.

The alias does one thing besides run the build. fdroidserver looks for the APK in the directory under app/build/outputs/apk/ whose name matches its flavour list, which is lite, and a two-dimension build writes to liteIntl/. Without help that ends in Failed to find any output apks after a build that succeeded. The alias therefore mirrors the APK into apk/lite/release/, where the single-dimension build used to put it. It is a Sync and not a Copy, because fdroidserver also refuses a directory that holds more than one APK.

bundleFullRelease is kept the same way, as an alias for bundleFullEnRelease that mirrors the AAB to bundle/fullRelease/. Nothing in this repo calls it any more: the release workflow and the bundle_play lane both name the real task.

F-Droid gets intl on purpose. It ships one APK to everybody and nothing downstream of the build adds a language, so the APK is the only place an F-Droid user can get the translations from. That is worth about 41 MB on a lite build that is otherwise around 12 MB. The small lite-en APK is on the GitHub release, and from 0.5.10 it installs over an F-Droid install like any update, because both carry the same key.

The build recipe is staged in the repo at fdroid/com.wasimaster.wmkeyboard.yml. F-Droid never reads it from there; it is versioned next to the code so the recipe and the build stay in step. It carries no comments, because fdroiddata’s CI runs fdroid rewritemeta on every changed file and fails if the result differs by a byte. rewritemeta strips comments, so any it found would trip that check. Field-by-field reasoning lives in fdroid/README.md instead.

1. Check the app is buildable as-is. Nothing generated may be missing from source. The dictionaries are fine here: the two bundled .wmdict files are compiled at build time by :tools:dictc from the plain-text lists in app/dictionaries-src/, and .wmng n-gram packs are downloaded at runtime rather than built at all. No binary dictionary is committed. Apart from gradle/wrapper/gradle-wrapper.jar, which F-Droid checks against its own known-good list, the only prebuilt binaries in the tree are the Harper .so files under core/intelligence/src/full/ and the LLM module’s, both of which belong to variants a lite build never assembles. The recipe deletes them before building so the scanner has nothing to complain about.

2. Test the exact build locally before you submit, because a failed build on their side means a round trip:

   ./gradlew clean assembleLiteRelease -Pwmkb.enablePlayStore=false -Pwmkb.enableGms=false

   That is the task name fdroidserver runs. Afterwards app/build/outputs/apk/lite/release/ must hold exactly one APK, since that is where it will look.

   No module may ask for a JDK toolchain

   The recipe deletes the foojay resolver, because the scanner rejects anything that could fetch a JDK over the network. Their builders also have auto-provisioning switched off. Together that makes any jvmToolchain(n) in the tree fatal unless n is a JDK their image already carries. :tools:dictc asked for 17 and failed the build outright with Cannot find a Java installation ... matching {languageVersion=17}. Set a jvmTarget instead: it fixes the bytecode level without demanding a particular JDK be installed.

3. Run the three checks their CI runs. fdroid lint must exit 0, and fdroid rewritemeta and fdroid checkupdates --auto must both leave the file byte-identical, since a pipeline job diffs the file after each. lint needs fdroiddata’s own config/ directory to know the valid category and anti-feature names; fdroid/README.md has the copy-paste block that fetches it and runs all three.

4. Fork fdroiddata on GitLab, make a branch named after the application id, and add the recipe as metadata/com.wasimaster.wmkeyboard.yml. Doing it through the GitLab web UI is the documented route and avoids cloning fdroiddata, which is a large repository and fails to clone outright on some networks. Never commit to your fork’s master.

5. Wait for your fork’s pipeline to go green (CI/CD → Pipelines in the fork), then open a merge request titled New app: WM Keyboard and fill in their template. Expect review comments and a wait measured in weeks rather than days. The two questions that come up most are whether every network service is optional, and whether anything prebuilt ends up in the APK. Every service is optional, and since 0.5.6 each one can also be pointed at a server the user runs, which is why the recipe carries no AntiFeatures block. Nothing prebuilt ends up in the APK either.

6. After it is accepted, releases look after themselves. UpdateCheckMode: Tags walks the newest tags, and UpdateCheckData points it at gradle.properties as checked out at each one, so it reads the version a tag actually carries. AutoUpdateMode: Version then adds the next Builds: entry and pins it to that tag’s full commit hash. F-Droid wants hashes, not tags, because a tag can be moved after a build is accepted. What that costs you is a promise: a release whose build needs something the recipe does not do has to be caught before the tag is pushed, because nobody reviews the entry their bot writes.

Reproducible builds

From 0.5.10 the F-Droid build is signed with the same key as the GitHub APKs. F-Droid still compiles it: the recipe’s Binaries: line points at wmkeyboard-<version>-vc<code>-fdroid.apk on the GitHub release, and after F-Droid’s own build finishes it downloads that file and compares the two. If they are identical apart from the signature, it copies our signature onto its build and publishes that. If they are not, that version fails and does not ship on F-Droid. AllowedAPKSigningKeys pins the certificate, so a reference APK signed with anything else is refused as well.

The fdroid job in the release workflow builds that file. It is the recipe copied exactly: assembleLiteRelease run from app/, the recipe’s three -P flags, no API keys, no ABI split, on its own runner so nothing leaks in from the other builds. It skips the recipe’s prebuild seds, because they only delete lines a lite build never reads. That was checked before the switch by rebuilding 0.5.9 and comparing it with the APK F-Droid had published.

The rules that follow from this:

• Never re-upload the -fdroid.apk of a release that is already out. F-Droid fetches it days after the tag, and a file built from anything other than the tagged commit fails the comparison.
• Anything that makes two builds of one commit differ breaks F-Droid. A timestamp or a random value in BuildConfig, a dependency pulled by a version range, a JDK toolchain other than the one their image carries. When a build fails the comparison, their build log holds the diff.
• Build it from a real clone. AGP writes the commit hash into META-INF/version-control-info.textproto. From a git worktree or a tarball it cannot read the repository and writes NO_VALID_GIT_FOUND instead, and that one file fails the comparison. The fdroid job checks the hash is there.
• No dependency metadata in the signature. AGP signs a Google-encrypted dependency list into an APK’s signing block by default, and fdroiddata’s check apk job rejects the reference APK for it. dependenciesInfo { includeInApk = false } in app/build.gradle.kts turns it off. It sits outside the files F-Droid compares, which is why the comparison itself still passed on 0.5.10’s first upload. That APK was re-signed with apksigner sign --alignment-preserved to drop the block.
• Keep the certificate check in the fdroid job in step with the recipe if the signing key ever changes.

The switch cost one reinstall. Installs from F-Droid up to 0.5.9 were signed with F-Droid’s key, and Android will not update an app to a build signed with a different one. Those users had to export a backup, uninstall, and install 0.5.10 again. Dual signing (F-Droid publishes both signatures for each version, as Liseur does) would have spared them, at the price of a hand-made fdroiddata merge request for every release. It was turned down.

Screenshots and description come from this repo

F-Droid reads fastlane/metadata/android/en-US/ directly out of the source tree: title.txt, short_description.txt, full_description.txt, the changelogs/ folder and images/. Editing them here updates the F-Droid listing on the next build, with no metadata merge request.

Two listings, one repo

The two editions are not the same app, so they do not share a description.

Tree	Read by	Holds
fastlane/metadata/android/en-US/	F-Droid, and the shared source for images and changelogs	the lite edition’s title.txt, short_description.txt and full_description.txt, plus images/ and changelogs/
fastlane/play/metadata/android/en-US/	Play, via supply’s metadata_path	the same three text files, written for the full edition, and nothing else

F-Droid scans a fixed set of paths inside the source repo and there is no way to point it somewhere else, so the default tree has to be the F-Droid one. Play is the side that can be redirected, so Play is the side that moved.

Only the three text files diverge. Images and changelogs stay in the shared tree, uploaded by graphics and internal, which read the default path. One copy of each, nothing to keep in step. The exception is a changelog placed under the Play tree for a version whose Play notes must differ, which internal prefers when it exists.

The lite description must not promise what lite does not ship

The lite flavour has no ML Kit, no Whisper and no Harper, so it has no handwriting, no text or QR scanning, no offline dictation and no on-device AI models. fastlane/metadata/android/en-US/full_description.txt names those as absent and links /privacy/policy-fdroid/; the Play copy describes them as present and links /privacy/policy/. Adding a feature to one description means deciding, deliberately, whether it belongs in the other.

preflight runs ensure_listing_limits!, which checks both trees against Play’s caps (30 / 80 / 4000 characters). It reads as UTF-8 explicitly rather than in the machine’s locale, because the description quotes Bengali and a non-UTF-8 locale otherwise raises rather than counting.

Publishing to Play

1. Create the app in the Play Console with package name com.wasimaster.wmkeyboard.

2. Fill in App content before you upload anything, since these answers gate the release. A keyboard is a sensitive category and reviewers do read them:

   • Privacy policy URL: https://wmkeyboard.pages.dev/privacy/policy/, the Play one. There are two, one per edition, because the two builds are not the same app underneath: the full edition carries ML Kit and the Play libraries and has to disclose what they report, and the lite edition F-Droid builds carries neither. F-Droid’s own policy is at /privacy/policy-fdroid/. Never point the Play listing at that one, because it would under-disclose. The About screen picks the right page from BuildConfig.FLAVOR, so a user always reads the policy for the APK they actually installed.
   • Data safety: this project collects nothing and shares nothing. The optional network tools send what you typed into that tool to the service you chose, which belongs under that tool’s own disclosure rather than as app-wide collection. But the form covers bundled SDKs as well as your own code, and the full edition bundles ML Kit. Google documents that its SDKs send device and app information, a per-installation identifier, and performance and error data to Google for diagnostics and usage analytics whenever an ML Kit feature runs. Declare that under App info and performance → Diagnostics and Device or other IDs: collected, not shared, encrypted in transit, and not deletable on request, since Google offers no opt-out. Answering “no data collected” here is the mismatch that gets a keyboard rejected, because the reviewer can see the SDK in the bundle. Read Network policy while you fill it in.
   • AI-generated content: yes. The AI writing tools, the AI chat screen and the on-device models all produce generated text, and the policy asks for an in-app way to report a bad generation. Every surface that shows generated text has one: the keyboard’s AI panel, and the chat screen’s per-answer Report. So the declaration has something true to point at.
   • Target audience: not children. A keyboard aimed at children pulls in Families policy, which this app is not built for.
   • Ads: none. Financial features: none. News: no.

3. Fill the two declaration forms this manifest forces. Only two of the four sensitive surfaces have a form of their own; the other two are judged on the in-app disclosure and the Data safety answers instead. Knowing which is which saves hunting the Console for a page that does not exist.

   Surface	Console form?	What to say
   Accessibility API, from TouchPassthroughService binding BIND_ACCESSIBILITY_SERVICE	Yes, and because isAccessibilityTool="true" it also wants a video of the feature and the disability audience	It carves the key grid out of TalkBack’s touch exploration so screen-reader users can still use the keyboard’s gestures. It subscribes to no accessibility events, cannot read window content, and is inert unless pass-through is switched on.
   Photo and video permissions, from READ_MEDIA_IMAGES	Yes	It feeds the screenshot observer that offers a just-taken screenshot on the strip. The Photo Picker cannot replace it: a picker returns a file the user chose, and this needs to notice that a new one appeared. FUTO Keyboard ships the same permission for the same reason on Play, so this is a well-trodden justification rather than a novel one.
   Notification access, from MediaNotificationListener	No form. Prominent disclosure plus Data safety is the whole requirement	Two jobs, both user-facing: the media-control tool needs the active media session, and one-time-code capture reads codes to offer them on the strip. Both are off until the user enables them, and SpecialAccessActivity shows the disclosure before the system screen opens.
   PACKAGE_USAGE_STATS, for the clipboard’s “Show source app” setting	No form. Same as above	On a copy it reads which app was in the foreground in the ten seconds before, so the clip can say where it came from. It reads no history and no time-in-app, keeps the answer with the clip on the device, and the setting is off until the user turns it on.

4. Check the sensitive-permission story matches what the app says. The label on the notification listener is what a user reads in Settings before granting it, and it has to name both jobs. The in-app prominent-disclosure screens are what the policy asks for, and they exist for every runtime permission already.

5. Build and upload to internal testing. Tagging a release does this for you (the play job in the workflow), or run it locally:

   bundle exec fastlane android internal

   Go to internal first, always. Play’s own device catalogue tells you within minutes if an on-demand module (:feature:llm, :feature:translate, :feature:litert, :feature:handwriting) or the unbundled ML Kit path is misconfigured, and that is far cheaper to learn there than in production.

6. Promote when it looks right.

   bundle exec fastlane android promote

   Add rollout:0.2 for a staged rollout. Play signs with its own upload key flow, so the APK a user installs is not byte-identical to anything you built. That is expected, and it is why the GitHub release exists for people who want to verify a checksum.

Fastlane

The lanes live in fastlane/Fastfile and run through Bundler so the version is pinned by Gemfile.lock (CI installs the same one). One-time setup on a new machine:

brew install ruby@3.4
export PATH="/opt/homebrew/opt/ruby@3.4/bin:$PATH"   # add to ~/.zshrc
bundle install

Lane	What it does
preflight	checks the changelog for the current versionCode exists, signing is configured, and both listing trees are within Play’s character limits
bundle_play	bundleFullEnRelease with the Play channel flags. Play always gets en: it translates the app strings itself and injects them into the bundle at upload, and the translations in the repo were recovered from Play to begin with, so an intl bundle would only hand them back
apks	sideload APKs, full and lite in both language builds, one per ABI
internal	checks the changelog, builds the AAB (or takes aab:path), uploads to the internal track. Only the build path checks signing, since a prebuilt aab: is assumed already signed
promote	move the internal release to production (to:, from:, rollout: options)
listing	push the Play store-listing text, from fastlane/play/metadata/, nothing else
graphics	push the icon, feature graphic and screenshots to Play, nothing else
check_key	validate the service-account key against the Play API

Every lane passes the channel flags as -P properties, which beat whatever your local.properties has, so a machine set up for Play builds still produces a correct sideload build and the other way round.

internal and the tag-triggered upload only touch the binary and the release notes. The listing text is a separate, deliberate listing run and the imagery a separate graphics run, so a routine release can never half-rewrite the store page.

fastlane/metadata/.../images/ is what both stores read: F-Droid takes it straight out of the source tree, and the graphics lane uploads the same files to Play. play/store-listing/ and play/store-listing-tablet10/ are the composed slides those copies come from.

Screenshot shape is a hard Play rule

A Play screenshot’s long side may not be more than twice its short side. The phone slides are composed on a 1080x2400 device canvas, which is 2.22x. The API refuses that, with an error naming neither the file nor the rule. Run python3 play/pipeline/pad_phone_shots.py after you regenerate the slides. It widens each one to 1200x2400 by replicating its edge columns, so the shape is legal and exactly 2:1, with no art scaled or cropped. The graphics lane re-checks every file before it uploads. The 2560x1440 tablet slides are 16:9 and already fine.

One-time setup: the Play API key

1. Link a Cloud project. Play Console → Setup → API access, link (or create) a Google Cloud project.

2. Create a service account in that Cloud project (IAM & Admin → Service accounts). No project roles are needed. Create a JSON key for it and download it.

3. Invite the service account in Play Console → Users and permissions, using its ...@...iam.gserviceaccount.com address. Grant it release permission for this app (releases to testing tracks; add production if promote should work from the CLI too).

4. Put the key where fastlane looks. Locally that is fastlane/play-service-account.json (git-ignored). For CI, paste the whole JSON as a repository secret named PLAY_SERVICE_ACCOUNT_JSON.

5. Prove it works:

   bundle exec fastlane android check_key

Deploying the docs

The site at wmkeyboard.pages.dev is a Cloudflare Pages project connected to this repository, so a push to main that touches docs/ deploys itself. The settings are:

Setting	Value
Project type	Pages, not Workers
Project name	wmkeyboard (this is what makes the hostname)
Framework preset	Astro
Build command	npm run build
Build output directory	dist
Root directory	docs
Node version	22 (set NODE_VERSION=22 if the default is older)

Pages, not Workers

Cloudflare’s newer “Connect to Git” flow creates a Worker and deploys with npx wrangler deploy. Two things go wrong if you take it. A Worker is served from workers.dev, not pages.dev, and the pages.dev URL is compiled into the app. And wrangler deploy on an unconfigured project runs astro add cloudflare, whose adapter does not support Astro 7 yet: the build fails on beginContentEntryCollection missing from Astro’s exports. docs/wrangler.jsonc declares the project as Pages so that never runs.

CI builds the site with npm run check on every pull request, which turns on the link validator, so a broken internal link fails there rather than shipping.