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, andkotlin-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'ssettings.gradle.ktsresolves the plugin from it, and the editor compares it with thekanama-scripts.versionstampbuildScriptswrites),addons/kanama/mavenwith the Kanama runtime, annotations and processor, the Kanama Gradle plugin (net.multigesture.kanama, which addsbuildAndroidScripts,buildIosScriptsandexportWeb), the Android runtime AAR (kanama-android) and the Web runtime klibs (kanama-weband thewasmJsklib ofkanama-common-api),addons/kanama/webwith the Web bridge, page shell, export preset andserve_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, andkanama.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-kitbuilds and smokes a desktop kit per platform, and the store native library for each.cross-runtimesbuilds the Windows and Linux game runtime images on macOS, andexported-gameboots a real export with each image on its own runner, so cross-target export is proven on every tag.store-addonassembles 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.jsonledger 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:
- Version. Change
versioninbuild.gradle.ktsandproject-scripts/build.gradle.kts, andversioninexample_project/addons/kanama_tools/plugin.cfg(scripts/check_kit_version_pins.pychecks it against the root build). Then change the places that name the release in words: the status badge and the Godot wording inREADME.md, and the pages listed in step 2. Check withgit grep -n -I -E '<old version>' -- . ':!CHANGELOG.md' ':!scripts/web/package-lock.json'; what is left should be history, not the current release. - Wording.
scripts/upgrade_godot.shedits none of the pages that name the Godot or the release, so change them by hand. Find them withgit 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 inwrapper-maintenance.md, which names a Godot source commit. Platform Status changes only on evidence (Support Levels). - Changelog. Turn
## Unreleasedinto## <version> - <date>, keeping its "What's new" summary and its### Detailsentries under it, and open a new, empty## Unreleasedabove it:check_public_signature_changes.pycounts no break as announced without one. Keep everySource breakline. 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### Detailsare####and carry no task ids. - Gates. Check that the pin is a stable Godot:
python3 scripts/check_godot_version_pin.py --release. A beta or rc pin may live onmain, but the package workflow stops on a tag that carries one, so move the pin first (Godot Upgrade Runbook). Runscripts/local_ci.shwith the pinned Godot, then the isolated gates from clean clones:scripts/fresh_clone_smoke.shand, for Web,scripts/web_fresh_checkout_smoke.sh. Smoke the packages as Gates and Claims shows.scripts/fresh_clone_smoke.shclones 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). - 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.shinstalls 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. - 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 thev<version>tag. The workflow builds and smokes every package and, when every job passes, creates the release (titledv<version>, with a one-line note) and uploads the four desktop kits and the store addon. - 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, becausepublish-releasewaits 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, rungh release delete v<version> --yesbefore you re-tag. (The recovery is plain git; it has not been rehearsed.) - Demos. Follow "Update For A New Kanama Release" in the
AGENTS.mdofkanama-demos: bump the version, the README badges andKANAMA_REF, merge, then tag the demos repositoryv<version>(its earlier tags arev0.1.0tov0.2.2). Then bumpDEMOS_REFin.github/workflows/web.ymlto the demos commit. - 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.mdlinks to it); reword only its first sentence.