schwert_und_magie_on_pebble/docs/publish.md

Publishing guide

Steps to generate signing credentials and publish both apps. See docs/architecture.md for what each app does and CLAUDE.md for build commands.

1. .gitignore

Keystore files and credential properties must never be committed. Already added to .gitignore:

*.jks
*.keystore
keystore.properties

If you generate a keystore with a different name/extension, add that specific path too — don't rely on a broad glob you might forget to check.

2. Android companion app → Google Play

2.1 Generate an upload keystore

keytool -genkeypair -v \
  -keystore SchwertUndMagieOnPebbleCompanionApp/release.keystore \
  -alias sum-release \
  -keyalg RSA -keysize 2048 -validity 10000

keytool will prompt for a keystore password, a key password (can be the same), and your name/org details for the certificate (these become public metadata in the signed APK, not secret). Store the keystore file and both passwords in a password manager — losing this keystore means you can never publish an update to the same Play Store listing again under the same app; Google cannot recover or reset it for you.

2.2 Store credentials in a gitignored properties file

Create SchwertUndMagieOnPebbleCompanionApp/keystore.properties (already gitignored, never commit it):

storeFile=release.keystore
storePassword=<keystore password>
keyAlias=sum-release
keyPassword=<key password>

2.3 Wire the signing config

Add to SchwertUndMagieOnPebbleCompanionApp/app/build.gradle.kts, near the top:

import java.util.Properties

val keystoreProps = Properties().apply {
    rootProject.file("keystore.properties").takeIf { it.exists() }
        ?.reader()?.use { load(it) }
}

Inside the android { } block:

signingConfigs {
    create("release") {
        keystoreProps["storeFile"]?.let { storeFile = file(it as String) }
        storePassword = keystoreProps["storePassword"] as String?
        keyAlias       = keystoreProps["keyAlias"] as String?
        keyPassword    = keystoreProps["keyPassword"] as String?
    }
}

buildTypes {
    release {
        signingConfig = signingConfigs.getByName("release")
        // ...existing isMinifyEnabled / proguardFiles
    }
}

This degrades gracefully (null signing config values) on any machine without keystore.properties — CI or a contributor's checkout — rather than failing the whole Gradle configuration.

2.4 Build the release bundle

cd SchwertUndMagieOnPebbleCompanionApp
./gradlew bundleRelease   # produces app/build/outputs/bundle/release/app-release.aab
./gradlew assembleRelease # produces app/build/outputs/apk/release/app-release.apk, for sideload testing

Play Store requires the AAB (bundleRelease output), not the APK — Play re-packages per-device APKs from it (including ABI splits, so arm64-v8a/ x86_64 native VICE libraries each ship only to matching devices).

2.5 Play Console setup (one-time, per app listing)

1. Enroll in the Google Play Developer program (one-time account fee).
2. Create the app in Play Console, set its package name (de.ladkau.schwertundmagieonpebblecompanionapp) — this is permanent.
3. App content: privacy policy URL, content rating questionnaire, data safety form (declare what data the app collects — this app's only network activity is the loopback HTTP server talking to Core for Pebble, so "no data collected/shared" likely applies, but fill out the form yourself).
4. Store listing: title, short/full description, icon (512×512 PNG), feature graphic (1024×500), phone screenshots (min 2, current device's actual aspect ratio).
5. Enroll in Play App Signing when prompted on first upload — Google re-signs your AAB with its own key for distribution; your upload keystore (§2.1) only needs to be kept for future uploads to this listing, not for the keys end users' devices actually trust.
6. Upload the AAB to an internal testing track first, verify the install works on a real device, then promote to closed/open testing or production.

2.6 Versioning for future releases

Bump both fields in app/build.gradle.kts before every release build:

versionCode = 2      // must strictly increase on every Play Store upload
versionName = "1.1"  // user-visible, free-form

3. Android companion app → F-Droid

F-Droid is a community-run FOSS app catalogue that builds apps from source on its own infrastructure and signs them with its own key. The companion app is a good fit: it is open source, ships no proprietary binaries in the repo, and the copyrighted ROM and disk files are handled entirely at runtime by the user.

3.1 Inclusion policy check

F-Droid's key requirement is that everything needed to build the app is in the repo and is free/open-source. Verify:

• VICE 3.8 source is GPLv2 (tarball in res/). ✓
• nibtools source is GPLv2 (tarball in res/). ✓
• No prebuilt binaries committed (.a/.so files are build outputs in .gitignore). ✓
• No non-free SDKs or closed-source dependencies in build.gradle.kts. ✓
• C64 ROMs and game disks are not bundled — user-supplied at runtime. ✓

3.2 Prepare the fdroiddata metadata file

F-Droid apps are registered by adding a YAML file to the fdroiddata repository. Fork it, then create metadata/de.ladkau.schwertundmagieonpebblecompanionapp.yml:

Categories:
  - Games
License: GPL-2.0-or-later
AuthorName: Matthias Ladkau
SourceCode: https://github.com/<your-repo>
IssueTracker: https://github.com/<your-repo>/issues

AutoName: Schwert und Magie on Pebble

RepoType: git
Repo: https://github.com/<your-repo>

Builds:
  - versionName: '1.0'
    versionCode: 1
    commit: <git-tag-or-sha>
    subdir: SchwertUndMagieOnPebbleCompanionApp
    gradle:
      - release
    ndk: 30.0.14904198
    prebuild:
      - bash app/src/main/jni/build_vice.sh
      - bash app/src/main/jni/build_nibtools.sh

AutoUpdateMode: None
UpdateCheckMode: None

Key points:

• subdir points to the Gradle project root (where gradlew lives).
• gradle: [release] tells F-Droid to run ./gradlew assembleRelease.
• ndk must match the ndkVersion in app/build.gradle.kts (30.0.14904198). F-Droid's build server installs the requested NDK version automatically.
• prebuild runs the VICE and nibtools cross-compilation before Gradle invokes CMake. The NDK environment variable is set by F-Droid's build server, matching what build_vice.sh and build_nibtools.sh expect.
• F-Droid signs with its own key, so keystore.properties is not needed on the build server. The signing config in build.gradle.kts degrades gracefully when the file is absent.

3.3 Test the build locally with fdroid-server

Before submitting, reproduce the F-Droid build environment locally:

# Install fdroid-server (Debian/Ubuntu)
sudo apt install fdroidserver

# In the fdroiddata checkout:
fdroid build de.ladkau.schwertundmagieonpebblecompanionapp --latest

This runs the build inside a Docker container that mirrors the F-Droid build server. A successful local build means the merge request is very likely to pass.

3.4 Submit the merge request

Push your metadata/ addition to your fdroiddata fork and open a merge request against gitlab.com/fdroid/fdroiddata. The F-Droid team reviews the metadata and, if the build passes on their infrastructure, merges it and includes the app in the next index update (published roughly weekly).

3.5 Versioning for F-Droid updates

Each new release requires a new Builds entry in the metadata file with an incremented versionCode and the corresponding git commit or tag. versionCode must match the value in app/build.gradle.kts.

5. Pebble watch app → Rebble app store / direct distribution

The official Pebble app store shut down years ago; the community-run Rebble store is the closest equivalent today, alongside the 2025 Core Devices relaunch of Pebble hardware. Check Rebble's current developer portal directly for their exact submission flow and requirements — that's outside this repo and changes independently of it.

5.1 Build the artifact

cd SchwertUndMagieOnPebbleWatchApp
pebble build   # produces build/SchwertUndMagieOnPebbleWatchApp.pbw

The .pbw is the complete distributable — it bundles all target platforms (aplite/basalt/chalk/diorite/emery/flint/gabbro) declared in package.json. There is no signing step analogous to Android; Pebble apps are not cryptographically signed by the developer.

5.2 Direct distribution (no store)

Anyone with the .pbw file and Core for Pebble installed can sideload it — this is the lowest-friction path and doesn't depend on any third party's store being operational. This watch app is tightly coupled to the companion app's HTTP bridge (see docs/architecture.md §1), so it's not really meaningful as a standalone listing anyway — distribute both together.

5.3 Store submission (if Rebble's process applies)

Expect to need: an app icon resource (not yet configured in package.json — there's no icon/menu-icon entry currently, only the in-app IMAGE_SPLASH bitmap), a short description, and screenshots per platform. Generate screenshots the same way used during development:

pebble install --emulator emery --vnc
pebble screenshot --vnc --no-open docs/screenshots/emery.png

(repeat per target platform you want a store screenshot for).

5.4 Versioning

Bump version in SchwertUndMagieOnPebbleWatchApp/package.json before each release build.

6. Pre-publish checklist

• Release keystore generated, passwords saved in a password manager, both gitignored (§1, §2.1)
• keystore.properties exists locally and is not tracked by git
• ./gradlew bundleRelease succeeds and installs/runs on a real device from the resulting AAB (test via bundletool or Play internal testing)
• Play Console store listing content complete (icon, screenshots, privacy policy, content rating, data safety form)
• F-Droid metadata YAML created and fdroid build passes locally (§3)
• pebble build succeeds for all target platforms; .pbw sideloads and runs correctly against the signed companion app build
• versionCode/versionName (Android) and version (Pebble) bumped