release-engineering

name: release-engineering description: Release engineering tasks including version bumping, building release APKs, creating git tags, writing changelogs, and preparing F-Droid releases. Use when the user asks to prepare a release, bump version, tag a release, or build for distribution. argument-hint: task description

Release Engineering

You are performing release engineering tasks for Guileless Bopomofo.

Version Scheme

versionName: semver-style MAJOR.MINOR.PATCH (e.g. 3.7.4)
versionCode: monotonically increasing integer (e.g. 199)
Both are defined in app/build.gradle.kts

Bump with:

./gradlew bumpPatchVersion   # increments both versionCode (+1) and patch (+1)

For minor or major bumps, edit app/build.gradle.kts manually — the task only handles patch.

Release Process

The established release workflow follows this pattern:

Ensure all changes are committed on the working branch.
Bump version — run ./gradlew bumpPatchVersion or edit app/build.gradle.kts manually for minor/major bumps.
Write changelogs for F-Droid (see Changelog section below).
Build signed APKs — signing requires a keystore passphrase, so do not run the build automatically. Prompt the user to build the signed APKs manually in Android Studio (Build > Generate Signed APK) or via the command line. Output: app/release/ (debug builds go to app/debug/). Wait for the user to confirm the build is complete before proceeding.
Create release commit — commit message format: Release <versionName> with Signed-off-by trailer.
Tag the release — lightweight tag matching versionName (e.g. 3.7.5). Tags are NOT annotated.
Push the commit and tag when the user confirms.

Git Conventions

Release commit message: Release X.Y.Z
Tag name: X.Y.Z (just the version, no v prefix)
Tags are lightweight (not annotated): git tag <versionName>
Commits are signed off: --signoff

Changelogs (F-Droid)

Changelogs live at:

fastlane/metadata/android/en-US/changelogs/<versionCode>.txt
fastlane/metadata/android/zh-TW/changelogs/<versionCode>.txt

Filename is the versionCode (integer), not the versionName.
Max 500 characters per file.
Written in a friendly, first-person tone from the app's perspective.
Always create both en-US and zh-TW versions.
Use * for bullet points in en-US, ＊ (fullwidth asterisk) in zh-TW.
To determine what changed, review commits since the previous release tag:
```
git log --oneline <previous-tag>..HEAD
```

Build Commands Reference

./gradlew :app:assembleDebug       # Debug build
./gradlew :app:assembleRelease     # Release build (minified + shrunk)
./gradlew :app:test                # Unit tests
./gradlew :app:connectedAndroidTest # Instrumented tests
./gradlew :app:clean               # Clean (includes libchewing build artifacts)

GPG Signing

GPG signing requires interactive passphrase entry — do not run gpg commands automatically. Instead, prompt the user to sign the APKs manually with the commands below.

The APK filename follows the pattern org.ghostsinthelab.apps.guilelessbopomofo_v<versionName>-<buildType>.apk (configured by the archivesName setting in app/build.gradle.kts).

Provide the user with the exact commands to run:

gpg --detach-sign --armor <apk-file>

For example:

gpg --detach-sign --armor org.ghostsinthelab.apps.guilelessbopomofo_v3.7.5-release.apk
gpg --detach-sign --armor org.ghostsinthelab.apps.guilelessbopomofo_v3.7.5-debug.apk

Wait for the user to confirm signing is complete before proceeding to the GitHub Release step.

GitHub Release

After building and GPG-signing the APKs, create a GitHub Release using gh.

Release Notes

Write a human-friendly release note body — do not rely solely on --generate-notes. The note should:

Start with both the en-US and zh-TW F-Droid changelogs (already written earlier in the process), separated by a blank line.
Append the auto-generated changelog (commit list) below as a "Full Changelog" section for completeness.

Structure:

<en-US changelog content>

<zh-TW changelog content>

<!-- auto-generated below -->
**Full Changelog**: https://github.com/hiroshiyui/GuilelessBopomofo/compare/<previous-tag>...<versionName>

Creating the Release

gh release create <versionName> \
  --title "<versionName>" \
  --notes "$(cat <<'EOF'
<release notes body as described above>
EOF
)" \
  <apk-and-asc-files...>

Upload both debug and release APKs along with their .asc signature files (4 assets total):

org.ghostsinthelab.apps.guilelessbopomofo_v<version>-debug.apk
org.ghostsinthelab.apps.guilelessbopomofo_v<version>-debug.apk.asc
org.ghostsinthelab.apps.guilelessbopomofo_v<version>-release.apk
org.ghostsinthelab.apps.guilelessbopomofo_v<version>-release.apk.asc

The release title matches the tag/versionName (e.g. 3.7.5).

Important Reminders

Always confirm with the user before pushing commits/tags or creating GitHub releases.
Run tests before tagging a release if the user hasn't already.
The release APK requires a signing configuration — the user handles this outside of version control.
F-Droid builds from source using the tagged commit, so the tag must point to a buildable state.