Use JDK 17 or newer with Android SDK 36 installed. The app targets Java and Kotlin bytecode level 11, but Gradle and CI run on JDK 17.
chmod +x gradlew
./gradlew :app:assembleDebugFor a complete local check, run:
./gradlew :app:testDebugUnitTest \
:app:compileDebugAndroidTestKotlin \
:app:ktlintCheck \
:app:detekt \
:app:lintDebug \
:app:assembleDebugUse ./gradlew --warning-mode all <task> when Gradle reports deprecations. The current protobuf toolchain may emit Gradle 10 compatibility warnings; identify the plugin or dependency source before changing build scripts.
The repository includes a non-production Google Services configuration for debug builds. CI creates its own debug configuration through .github/actions/create-google-services.
For a local release build, provide a production app/google-services.json and signing material. Do not commit production Firebase configuration or keystores.
If processDebugGoogleServices or processReleaseGoogleServices fails:
- Confirm the JSON file is at
app/google-services.jsonfor release builds orapp/src/debug/google-services.jsonfor debug builds. - Confirm the JSON contains an Android client whose package name is
com.kingpaging.qwelcome. - Run
./gradlew :app:processDebugGoogleServicesor./gradlew :app:processReleaseGoogleServicesto isolate the failure.
After a significant change to proto/src/main/proto/user_preferences.proto, clear generated outputs before compiling:
./gradlew clean
./gradlew :proto:build :app:assembleDebugKeep field numbers stable. Add removed field numbers to reserved; reusing them can misinterpret persisted user data. If a migration test fails, run :app:testDebugUnitTest and the focused PreferencesToProtoMigrationTest before modifying production migration logic.
Check that a device or emulator is visible before running instrumentation tests:
adb devices
./gradlew :app:connectedDebugAndroidTestCI runs a focused emulator smoke suite on pull requests and pushes, while scheduled or manually dispatched runs execute the full suite. Test reports are uploaded as workflow artifacts after every CI test job.
Connected tests install androidx.test.services:test-services temporarily through the androidTestUtil configuration. AGP's Unified Test Platform grants this package MANAGE_EXTERNAL_STORAGE during setup and removes the utility APK during cleanup. Keep its version aligned with the androidx.test.services:storage version resolved by AndroidX Test Runner. If the dependency is removed or mismatched, physical-device runs can print No UID for androidx.test.services in user 0 before otherwise successful tests.
If an individual Compose test is unstable on a physical device, run its class in a fresh instrumentation process before treating it as a code regression. The Gradle task supports test filtering:
./gradlew :app:connectedDebugAndroidTest \
-Pandroid.testInstrumentationRunnerArguments.class=com.kingpaging.qwelcome.ui.templates.TemplateEditorScreenTestAn INSTALL_FAILED_UPDATE_INCOMPATIBLE error means the installed app was signed with a different certificate. Use the same signing key for an update. For a development-only reinstall, uninstall the existing package first; this deletes its local data:
adb uninstall com.kingpaging.qwelcome
adb install app/build/outputs/apk/debug/app-debug.apkFor local release builds, configure either the repository-root qwelcome-release.keystore or KEYSTORE_FILE, plus these environment variables:
KEYSTORE_PASSWORDKEY_ALIAS(defaults toqwelcome)KEY_PASSWORD
The release workflow additionally requires GOOGLE_SERVICES_JSON_BASE64 and KEYSTORE_BASE64 repository secrets. It fails before signing if the pushed vX.Y.Z tag does not match VERSION_NAME or if CHANGELOG.md lacks that released version.
Use scripts/bump-version.sh or scripts/bump-version.ps1 to update version.properties, move the Unreleased changelog entries, create the release commit, and create an annotated tag. Follow the release guide for the required branch and retagging order.
If the release workflow stops before signing, inspect the metadata error first:
- A tag must use the
vX.Y.Zform. - The tag version must equal
VERSION_NAMEinversion.properties. CHANGELOG.mdmust have a non-empty## [X.Y.Z]section.
Correct the release branch, merge it, recreate the annotated tag on the final default-branch commit, and push the corrected tag. Do not bypass metadata checks by editing the workflow.