Skip to content

Release Process

How the distributable zips are built and checked. Users download them from the releases page; see Install from a Release Kit and Add Kanama to an Existing Project.

Desktop Packages

Kanama has two desktop distribution shapes:

  • Desktop kit: a complete starter Godot project for new users.
  • Store addon: an install-safe addon zip for existing projects and future Godot Asset Store submission.

The package tasks produce local zips; they become public download flows only when matching GitHub release artifacts are published. Build the host desktop kit and the local host store addon together with:

./gradlew packageDistributions

Every package carries the Android runtime AAR, so packaging needs the Android SDK, NDK and CMake, or -PkanamaAndroidPackageDir; see Desktop Kit.

Desktop Kit

A desktop kit is built per platform:

./gradlew packageDesktopKit

The output is:

build/distributions/kanama-desktop-kit-v<version>-<platform>.zip

The zip is rooted at the Godot project directory and contains:

  • project.godot, main.tscn, and kotlin-src/HelloScript.kt,
  • build.gradle.kts, settings.gradle.kts, gradlew, and Gradle wrapper files,
  • addons/kanama/kanama.jar,
  • addons/kanama/kanama.version, the one line that ties the addon, the Kanama Gradle plugin and the runtime dependencies to one version (the template's settings.gradle.kts resolves the plugin from it, and the editor compares it with the kanama-scripts.version stamp buildScripts writes),
  • addons/kanama/maven with the Kanama runtime, annotations and processor, the Kanama Gradle plugin (net.multigesture.kanama, which adds buildAndroidScripts, buildIosScripts and exportWeb), the Android runtime AAR (kanama-android) and the Web runtime klibs (kanama-web and the wasmJs klib of kanama-common-api),
  • addons/kanama/web with the Web bridge, page shell, export preset and serve_export.py,
  • addons/kanama/bin/<platform>/ with the native bootstrap,
  • addons/kanama/kanama.gdextension,
  • addons/kanama_tools, and
  • .godot/extension_list.cfg.

Validate a kit from a temporary project:

scripts/package_install_smoke.sh \
  build/distributions/kanama-desktop-kit-v<version>-<platform>.zip \
  /absolute/path/to/godot

The smoke unzips the kit, runs ./gradlew buildScripts, confirms kanama-scripts.jar and its version stamp, and, when a binary is provided, launches Godot and checks that a pack export holds nothing from build/. Add --android to also run buildAndroidScripts and a headless Android export from the kit alone, and check the APK (no device). On a Mac, add --ios to run buildIosScripts, a headless iOS export of an Xcode project, and an unsigned xcodebuild of it for the device SDK (no device either). Add --web to run exportWeb and play the export in headless Chrome with the browser smoke's starter driver; it needs Node.js and Chrome, and takes --web-template <zip> when the Web template is not in Godot's templates folder.

Packaging builds the Android runtime AAR with the nested Android build, so it needs the Android SDK (ANDROID_HOME) with the NDK 29.0.14206865 and CMake 3.22.1 packages (Export for Android lists the SDK packages; CMake is the runtime build's own). Without them, pass -PkanamaAndroidPackageDir=<dir>: a directory that holds a kanama-android Maven tree of the same Kanama version (<dir>/net/multigesture/kanama/kanama-android/<version>/), such as the addons/kanama/maven of a kit built elsewhere, or the kanama-android-maven artifact of a package workflow run. The package workflow builds the AAR once and passes it to every kit job this way.

The macOS kit also carries the iOS runtime: the iosArm64 klib of the runtime (kanama-iosarm64, with its cinterop klib) and a zip of the C shim and its headers (kanama-ios-shim), published by publishKanamaIosPackage. Kotlin/Native builds them on a Mac only, so the Linux and Windows kits carry neither. A store addon built off a Mac takes them from -PkanamaIosPackageDir=<dir>, a directory with both Maven trees (<dir>/net/multigesture/kanama/kanama-iosarm64/<version>/ and .../kanama-ios-shim/<version>/), such as the kanama-ios-maven artifact of a package workflow run.

Store Addon

The store addon is intentionally safer for existing projects. It does not place files at the project root. It contains:

  • addons/kanama,
  • addons/kanama_tools,
  • all available desktop native bootstrap binaries under addons/kanama/bin/<platform>/,
  • the local Maven repo under addons/kanama/maven, with the Kanama Gradle plugin, the Android runtime AAR and the Web runtime klibs as in the kit, and kanama.version,
  • the Web export's files under addons/kanama/web, as in the kit,
  • release-kit Gradle and wrapper templates under addons/kanama/templates/release-kit.

The store addon intentionally does not include nested project.godot or main.tscn files under addons/, so installing it into an existing Godot project does not create a second embedded Godot project.

Build a local host-only store addon:

./gradlew packageStoreAddon

The all-platform store addon is assembled by the GitHub package workflow after the matrix builds macOS arm64, Linux x64, Linux ARM64, and Windows x64 native artifacts. The workflow smokes every desktop kit and the assembled store addon before uploading artifacts.

Validate a store addon from a temporary project:

scripts/package_install_smoke.sh \
  --store-addon \
  --require-all-store-platforms \
  build/distributions/kanama-store-addon-v<version>.zip \
  /absolute/path/to/godot

For a local host-only packageStoreAddon build, omit --require-all-store-platforms.

Mobile and Web Exports

No export platform has a separate zip. Kits and the store addon carry the Android runtime AAR and the Web runtime klibs, and the macOS kit and the store addon carry the iOS runtime klib and shim; the Kanama Gradle plugin compiles a project's scripts against them (buildAndroidScripts, buildIosScripts, exportWeb; see Android, iOS and Web). Packaging checks that the bridge in addons/kanama/web speaks the Web protocol the processor generates (verifyKanamaWebPackageProtocol).

Package Workflow

The package workflow (.github/workflows/package.yml) runs only on manual dispatch and v* tags. It does not run on pull requests. On a tag, its first job refuses a Godot pin that is not stable, and every other job waits for that one, so a tag on a beta or rc builds and publishes nothing. Its jobs, in file order: gdextension-header (the pin guard), android-aar, desktop-kit, cross-runtimes, exported-game, store-addon, store-addon-windows, android-export, ios-export, web-export and publish-release. The main ones:

  • desktop-kit builds and smokes a desktop kit per platform, and the store native library for each.
  • cross-runtimes builds the Windows and Linux game runtime images on macOS, and exported-game boots a real export with each image on its own runner, so cross-target export is proven on every tag.
  • store-addon assembles and smokes the all-platform store addon.
  • publish-release, on a tag only, creates the GitHub release if it does not exist and uploads the desktop kits and the store addon.

Matrix targets:

Platform Runner Artifact classifier
macOS arm64 macos-15 macos-arm64
Linux x64 ubuntu-24.04 linux-x64
Linux ARM64 ubuntu-24.04-arm linux-arm64
Windows x64 windows-2025 windows-x64

android-aar builds the Android runtime AAR once, on Linux, for every kit job and the store addon. android-export then unzips the Linux kit and the store addon into fresh projects and runs package_install_smoke.sh --android on each: buildAndroidScripts and a headless Godot export with a fresh GRADLE_USER_HOME, then the APK checks. The macOS kit job also uploads the iOS runtime trees (kanama-ios-maven) for the store addon, and ios-export runs package_install_smoke.sh --ios on macos-15 for the macOS kit and the store addon: buildIosScripts, a headless export of an Xcode project, and xcodebuild for the device SDK without signing, with the newest Xcode on the runner. web-export unzips the Linux kit and the store addon into fresh projects and runs package_install_smoke.sh --web on each, on ubuntu-24.04: exportWeb with a fresh GRADLE_USER_HOME and the Web template where Godot installs it, then the export played in headless Chrome.

The release job grants contents: write only when publishing assets for a tag. All other package jobs use read-only repository permissions.

Native Bootstrap Libraries

Native bootstrap libraries are generated build artifacts. Source repositories ignore kanama_bootstrap.dll, libkanama_bootstrap.so, and libkanama_bootstrap.dylib; rebuild the matching library locally for the platform under test instead of committing it.

Support Levels

Requirements and Platform Status gives each platform one word:

  • Supported: a user can build and ship their own game on it.
  • Experimental: it runs the Kanama demos, and nothing is promised for a user's own game.

A platform moves to Supported only on evidence, on the current Godot pin:

  • its smoke path passed: local CI and the desktop demo smokes for a desktop platform, the device matrix for a mobile one, the browser matrix for Web (Device and Browser Runs), recorded in the evidence/gates.json ledger that the Gates Index shows;
  • for a mobile platform, the bar Android and iOS met: device-matrix breadth (the demo matrix on more than one device model), renderer coverage, release-grade packaging (a release build runs, not only a debug one), and a heavy demo;
  • a user's own project, not only a demo, builds and exports by following the user pages.

The runs, dates and devices go on Platform Evidence. The status word then changes in the same pull request on Requirements and Platform Status, in README.md and in CHANGELOG.md. Never word a claim wider than the device or browser runs validated: a package zip that installs is not proof that exported games work, and a desktop pass says nothing about a device.

Cutting a Release

The maintainer decides when a release is cut. Use a fresh branch name for the release pull request: the release branches of earlier attempts stay in the history. For 0.5.0, origin/release/0.5.0 already exists from an earlier attempt, so use a name such as release/0.5.0-cut. The steps:

  1. Version. Change version in build.gradle.kts and project-scripts/build.gradle.kts, and version in example_project/addons/kanama_tools/plugin.cfg (scripts/check_kit_version_pins.py checks it against the root build). Then change the places that name the release in words: the status badge and the Godot wording in README.md, and the pages listed in step 2. Check with git grep -n -I -E '<old version>' -- . ':!CHANGELOG.md' ':!scripts/web/package-lock.json'; what is left should be history, not the current release.
  2. Wording. scripts/upgrade_godot.sh edits none of the pages that name the Godot or the release, so change them by hand. Find them with git grep -n -I -E '<old release>|<old Godot>|beta ?[0-9]' -- README.md docs/index.md docs/getting-started docs/exporting docs/reference/version-support.md docs/contributing/wrapper-maintenance.md. These pages name the Godot a release is built on: the README badges, Get Started, the kit and store addon pages, the source checkout page, the Web export page, Requirements and Platform Status, and the KDoc docs pin in wrapper-maintenance.md, which names a Godot source commit. Platform Status changes only on evidence (Support Levels).
  3. Changelog. Turn ## Unreleased into ## <version> - <date>, keeping its "What's new" summary and its ### Details entries under it, and open a new, empty ## Unreleased above it: check_public_signature_changes.py counts no break as announced without one. Keep every Source break line. Check that the summary still matches the entries, in particular the toolchain line (Kotlin, KSP and Godot versions). If there is no ### What's new in <x.y> yet, write one: at most 25 lines, second person, one link per paragraph (docs-style.md). Entry headings under ### Details are #### and carry no task ids.
  4. Gates. Check that the pin is a stable Godot: python3 scripts/check_godot_version_pin.py --release. A beta or rc pin may live on main, but the package workflow stops on a tag that carries one, so move the pin first (Godot Upgrade Runbook). Run scripts/local_ci.sh with the pinned Godot, then the isolated gates from clean clones: scripts/fresh_clone_smoke.sh and, for Web, scripts/web_fresh_checkout_smoke.sh. Smoke the packages as Gates and Claims shows. scripts/fresh_clone_smoke.sh clones Kanama and the demos from GitHub, at their default branch, so run it after the release pull request is merged, or pass --kanama-source <path> and --demos-source <path> to test local checkouts (a path clones the checkout's current commit).
  5. Evidence. Check the Gates Index ledger: every local-only gate behind a Supported claim has a passing run on the current Godot pin. Run the ones that do not. A device gate needs the phone unlocked, and an iOS device gate needs Xcode signed in to an Apple account. A free Apple account allows only three apps on a device at a time, and the phone trusts the developer only while one of them is installed. scripts/ios_device_gate.sh installs each app before it removes the others; when the phone is full it may remove one other Kanama app first, never the last one, and it says so when your other apps fill the phone. If a run says the developer is not trusted, trust it on the phone under Settings > General > VPN & Device Management and run it again. The ledger fails the build when an accepted-stale entry's date has passed (acceptedStaleUntil). If the release slips past that date, re-run the gates or renew the dates with a reason.
  6. Tag. Run the package workflow by hand on the release commit first (gh workflow run package.yml --ref main; it takes about an hour). Then push the v<version> tag. The workflow builds and smokes every package and, when every job passes, creates the release (titled v<version>, with a one-line note) and uploads the four desktop kits and the store addon.
  7. Release page. Check that those five zips are attached, then replace the title and the note with the real ones: gh release edit v<version> --title <version> --notes-file <notes>. The changelog section is the full record. If the tag run fails, nothing is published, because publish-release waits for every other job: fix the cause in a pull request, delete the tag (git push --delete origin v<version>) and push it again on the new commit. If a release was created anyway, run gh release delete v<version> --yes before you re-tag. (The recovery is plain git; it has not been rehearsed.)
  8. Demos. Follow "Update For A New Kanama Release" in the AGENTS.md of kanama-demos: bump the version, the README badges and KANAMA_REF, merge, then tag the demos repository v<version> (its earlier tags are v0.1.0 to v0.2.2). Then bump DEMOS_REF in .github/workflows/web.yml to the demos commit.
  9. Docs notes. Remove the "Until Kanama 0.5.0 is released" notes once the kits are on the release page: find them with git grep -n -i -E 'until (kanama )?0\.5|until the 0\.5|published so far are for Kanama 0\.4|not out yet' -- README.md docs. One small docs pull request; the docs site redeploys when it merges. Keep the "Building the Addon from Source" heading on the store addon page (source-checkout.md links to it); reword only its first sentence.