Skip to content

Godot Upgrade Runbook

This page is the process for moving Kanama to a new Godot release. It is maintainer material; game projects never need it. You edit the pin, run one script, and then do the parts that need a person: source-break notes, device runs and release wording.

Upgrade Policy

A release ships only on a stable Godot. main may sit on a beta or rc while the next Godot is on its way, so that the bump is found and fixed before the stable arrives, but no release is cut from it: on a v* tag the package workflow runs python3 scripts/check_godot_version_pin.py --release, which fails on a non-stable pin, and nothing is published (see Pinning a Prerelease). A dev build is never the baseline. A bump is planned work, not an automatic follow; wrapper-coverage work in flight should land first.

The baseline has one source of truth: kanamaGodotVersion in gradle.properties, in Godot's own spelling (4.8.stable for a .0 release, 4.7.2.stable for a maintenance release, 4.8.beta2 for a prerelease). The CI workflows carry the same version in dash form (GODOT_VERSION: 4.8-stable or 4.8-beta2, the GitHub release tag) in package.yml, ci.yml, web.yml and gate-red-runs-nightly.yml, and web.yml derives the export-template folder from it. Everything else reads the property. scripts/check_godot_version_pin.py fails the build when a pin drifts, and --list-files prints the files a pin edit touches. Maintenance releases follow the same runbook; the diff is just smaller.

What You Need

  • The Godot editor and export templates from the godot-builds release for the new version (Godot_v<version>_macos.arm64.zip or Godot_v<version>_macos.universal.zip, whichever the release ships, and Godot_v<version>_export_templates.tpz; <version> is the dash form the workflows use, such as 4.8-stable, and a prerelease is 4.8-beta2). GODOT_VERSION=<version> scripts/download_godot_macos.sh <zip> downloads the macOS editor.
  • JEXTRACT_HOME pointing at a jextract 25+ install, unpacked from the OpenJDK jextract downloads.
  • A Godot source checkout at the matching tag: a stable tag such as 4.8-stable (git clone --depth 1 --branch 4.8-stable https://github.com/godotengine/godot.git); for a prerelease, check out the commit named in its godot-builds release. KDoc is synced from its doc/classes (--godot-docs), and the script checks the checkout's version.py against the pin. Never sync from master, or from a tree of another build. A prerelease takes the commit of that build: its version.py says beta without the number.
  • A clean working tree apart from the pin edit, so the bump diff stays reviewable.

The Bump

  1. Edit the pin, and only the pin. Change kanamaGodotVersion in gradle.properties and GODOT_VERSION in the four workflows. On a new major.minor, also set compatibility_minimum in the two committed kanama.gdextension descriptors to it (python3 scripts/check_godot_version_pin.py --list-files names them all).

  2. Look at the plan (optional). --plan runs the read-only checks and prints every step with its command, changing nothing:

JEXTRACT_HOME=/absolute/path/to/jextract-25 \
scripts/upgrade_godot.sh --plan \
  --godot-docs /absolute/path/to/godot-source/doc/classes \
  /absolute/path/to/new_godot_binary
  1. Run the bump with the same arguments, without --plan. Add --templates /path/to/Godot_vX_export_templates.tpz to install the export templates when they are not installed yet. A run takes about two to three minutes:
JEXTRACT_HOME=/absolute/path/to/jextract-25 \
scripts/upgrade_godot.sh \
  --godot-docs /absolute/path/to/godot-source/doc/classes \
  --templates /absolute/path/to/export_templates.tpz \
  /absolute/path/to/new_godot_binary

The script works through these steps in order:

Step What it does
1. preflight checks the pin policy, the binary's version, jextract, the docs checkout's version, the export templates, and that only the pin files are dirty; lists every problem before stopping
2. refresh refresh_godot_api.sh --skip-validate: dumps extension_api.json and gdextension_interface.h from the binary, runs jextract, regenerates the virtual-signature table
3. classify diffs the new API against HEAD: no-op, metadata-only, or an API change with the added and removed classes and the removed methods, properties, signals, constants and enums
4. constants generate_name_constants.py
5. tree generate_api_wrapper.py --write-tree: re-renders every wrapper on every platform, adopts every class the new API adds, keeps the desktop ObjectCalls actual set in step with the expect, and repeats until a pass writes nothing
6. outputs the release kit's config/features (templates/release-kit/project.godot, moved to the pin's major.minor), the builtin operators and methods, the engine-method table, the Web backend, wrappers and exercise, the API exercise, the generator, coverage, enum-migration and iOS-handwritten pages, the iOS scene-init unsafe-class list (scripts/ios_scene_init_unsafe_classes.json, scanned from the source checkout), then the KDoc sync
7. format ./gradlew ktfmtFormat (the regen leaves the iOS ObjectCalls region, the expect and toggled desktop members unformatted)
8. gates index docs/reference/generated/gates.md, last because it reads the gate list
9. gates every drift gate, ktfmtCheck, the version pins (including the release kit's, check_kit_version_pins.py), and the API validation, run to the end

API validation runs in step 9, after the re-adopt. Before step 5 the committed wrappers still call the methods the new Godot removed, so a removal is a line in the step 3 inventory and a source break for step 4 below, not a reason to stop.

  1. Read the summary. A step that fails is listed with its command; nothing is hidden behind the first failure. Three checks are listed as human decisions rather than failures, because an API change is expected to trip them:

  2. Public API signatures. Each removed or changed signature needs a - **Source break:** line in CHANGELOG.md under ## Unreleased (see the top of the CHANGELOG), then python3 scripts/check_public_signature_changes.py --write.

  3. Adopted-list classes. check_wrapper_generator.py holds a list of classes to "no skipped method". When Godot gives one of them a method whose call shape has no ObjectCalls helper yet, the drift gate prints it as pending, with the PENDING_HELPER_SKIPS row to paste: the reason, the task or issue that adds the helper (replace the task <n> placeholder) and today's date. Add the helper (see Wrapper Maintenance), or the row. Do not take the class out of its list. This item only appears when the drift gate itself passed; a real drift failure is listed as a failure.
  4. Gate evidence. A pin move makes every entry of evidence/gates.json stale. Re-run each gate on the new pin, or accept it stale with a reason and an expiry date. Then re-run python3 scripts/generate_gates_index.py --markdown docs/reference/generated/gates.md: the index page shows the ledger, so it is stale again once you edit it.

The summary also lists the classes this Godot added, all adopted by step 5, with the editor-only ones (api_type editor) marked; step 5's own output gives each one's count of skipped methods. They are generated like every other class; review the list, and the new rows they get on the API exercise page.

The exit status says where you are: 0 when every gate is green, 3 when the mechanical work is done and only the listed decisions remain (local CI stays red until you make them), 1 when a step or gate failed.

After the Script

These steps need a person or a device, so the script prints them and stops:

  • Run local CI against the new binary: scripts/local_ci.sh /absolute/path/to/new_godot_binary.
  • Run the red runs: python3 scripts/gate_red_runs.py --strict. The cases that depend on what a bump moves read it from the tree (the pin, the release kit's config/features, the iOS size claim) and insert a row into a table like PENDING_HELPER_SKIPS instead of replacing an empty one, so a bump needs no edit to gate_red_runs.py. A few cases still mutate a Godot-generated wrapper by its literal signature (Node.setProcessMode, Label.setText, the Node.getParent hash); if a new Godot changes one, that case stops with "cannot apply the mutation" and names the file: update the case, the same way (read the value, or pick a member Godot did not touch).
  • Delete stale Android build templates. Since Godot 4.8 an Android export refuses a res://android/build installed by another Godot version ("Unable to set up Android build directory"). android_smoke.sh and android_export_minified.sh delete a template whose android/.build_version is not the pin and reinstall it. For a demo exported by hand, delete res://android/build. Editor Settings > Export > Android > Build > Automatically Delete Build Directory deletes all of res://android, android/plugins (Kanama's plugin) too; the export guard then ends a command-line export, marks an editor export as failed and keeps a one-click deploy from installing, and the plugin has to be installed again.
  • Run the API exercise before any device gate. The page (docs/reference/generated/api-exercise.md) is already regenerated; review its diff, since every new class gets rows that have never run. Then run the rows headless with the trace on (runtime_smoke.sh does, or KANAMA_API_EXERCISE=1 KANAMA_API_EXERCISE_TRACE=1 on api_exercise_smoke.tscn with a -PkanamaApiExercise=true addon). A row that crashes, hangs, writes outside the scratch directory or would change a running game's state on a device gets a METHOD_OVERRIDES or exclusion entry with that reason in scripts/api_exercise_policy.py; a row that fails is a finding to fix. Only then the iOS and Android device runs, which run the same rows (see "The exercise rows" in wrapper-maintenance.md).
  • When Godot adds a builtin member (a new Vector2 method, a new operator), the Web builtin parity hashes need one more row, recorded from a runtime smoke log: python3 scripts/generate_builtin_ops.py --record-parity <log>, then --write. Each entry draws its inputs from a stream of its own, keyed by its name, so the other rows do not move, and the output is ktfmt-clean.
  • Re-run the platform smoke and device gates listed in the "Local-only gates" table of the Gates Index, and record each run in evidence/gates.json with scripts/record_gate_evidence.py. Device and Browser Runs says how to run them. Support claims move only after the matching gate passes; the upgrade tooling never edits support wording.
  • Run one full device pass while the new pin is still a trial, not only at the release. That means scripts/ios_device_gate.sh with the fresh starter step and the demo matrix on the iPhone, and scripts/android_smoke.sh on the Pixel. A device step can go stale without CI noticing, because CI has no phone: in November 2026 the iOS starter probe still expected the String form of a NodePath three weeks after #364 changed the decode, and the first iPhone run on the 4.8 beta found it. Before the iPhone run, check that the phone still trusts the developer (Settings > General > VPN & Device Management), and keep at least one Kanama app on it: on a free Apple account, removing the last one drops that trust.
  • Re-import the demos with the new editor, commit the .import churn in the demos repo, and move DEMOS_REF in .github/workflows/web.yml.
  • Refresh release-facing wording by hand: CHANGELOG.md, README.md, docs badges and version wording, templates (the release kit's Godot version is already moved, step 6), and companion demo defaults. Find the pages with git grep -n -I -E '<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; Cutting a Release lists them. The demos' synced kanama.gdextension copies take the new compatibility_minimum when the demos re-sync the addon.
  • Bump the KDoc docs-pin commit hash in docs/contributing/wrapper-maintenance.md to the new stable tag.
  • Scan gdextension/gdextension_interface.h for newly @deprecated functions and migrate off them. 4.7 is the baseline: we don't carry deprecated GDExtension callbacks. grep -B1 '@deprecated' gdextension/gdextension_interface.h | grep '@name' lists them; cross-check each against the FFI lookups every backend binds (grep -rnE 'classdb_construct_object|script_instance_create|register_extension_class|get_godot_version' src ios --include '*.kt' --include '*.c') and move to the newest variant.
  • Check the backends have not diverged. The desktop/Android JVM backend (src/jvmMain) and the iOS Kotlin/Native shim (ios/bootstrap/kanama_ios_shim.c) choose their own GDExtension entry points and have silently drifted before (desktop construct_object2 vs iOS construct_object3, issue #91 / task 61). Both must bind the same, newest construct/register/script-instance functions. scripts/check_gdextension_modernization.py (step 9 and local_ci.sh) fails on a deprecated binding or a divergence.
  • Re-check the Android template's Kotlin libraries. An exported APK runs on the kotlin-stdlib and kotlinx-coroutines of Godot's Android build template (kotlinVersion in config.gradle inside the export templates' android_source.zip, and ./gradlew :dependencies --configuration standardDebugRuntimeClasspath there; 4.7.2: stdlib 2.1.21, coroutines 1.6.4), so android/godot-plugin/{plugin,scripts}/build.gradle.kts compile with apiVersion set to that stdlib version and against that coroutines version (kanamaAndroidCoroutinesVersion in android/godot-plugin/gradle.properties). Move both with the template. The other direction matters too: Kotlin 2.4 already warns that API version 2.1 is deprecated, and a later Kotlin (around 2.6, if the usual cycle holds) refuses it. A root Kotlin bump then fails the Android build until Godot's template ships a newer stdlib; keep the older Kotlin until it does, rather than raising the API level past the APK's.
  • Before tagging: scripts/fresh_clone_smoke.sh /absolute/path/to/new_godot_binary.

A Godot bump also invalidates the Web evidence: the export template, the generated proxy and the bridge protocol all move with it, and CI's Web matrix only covers Chrome and Firefox. Re-run the full corpus on all three browsers, including the Safari local gate, and re-run the fresh-checkout gate against a clone built on the new pin; see Regression Cadence for which gate runs when.

When a Bump Stops Half-Way

A bump that stops (a hard step failed, the machine slept, you pressed Ctrl-C) leaves a half-regenerated tree, and the preflight refuses to start on it. Every step regenerates its outputs from scratch, so the fix is always to run the whole bump again, from one of two starting points:

  • Nothing committed yet: reset, then re-run. --reset restores every tracked file except the pin files and deletes the untracked wrapper and generated-page files a run created (it lists them). It needs no binary. Anything else you changed by hand since the bump started is discarded too, so commit that first.
scripts/upgrade_godot.sh --reset
JEXTRACT_HOME=/absolute/path/to/jextract-25 \
scripts/upgrade_godot.sh --godot-docs /absolute/path/to/godot-source/doc/classes \
  /absolute/path/to/new_godot_binary
  • You committed the half-done result: re-run against the pre-bump commit. --baseline-ref names the commit whose extension_api.json is the previous Godot. The classification, the drift gate's pending-helper report and the list of added classes all diff against it, so they come out as on the first run instead of empty:
JEXTRACT_HOME=/absolute/path/to/jextract-25 \
scripts/upgrade_godot.sh --baseline-ref <commit before the bump> \
  --godot-docs /absolute/path/to/godot-source/doc/classes \
  /absolute/path/to/new_godot_binary

Either way the re-run ends with the same tree, the same exit status and the same lists as a bump that never stopped. scripts/upgrade_godot_rerun_selftest.sh proves it: from a checkout carrying a pin edit, with the options you give the bump, it runs the bump once start to end, once stopped after step 5 then reset and re-run, and once stopped after step 6, committed and re-run with --baseline-ref, and compares the three (10 to 15 minutes). With --dry-run it checks that a stopped dry run restores the tree.

Never Finish With a Red Gate

The drift gate is the safety net: a botched bump leaves wrappers drifted, the gate catches it, and the fix is to re-run the bump as above, so mistakes are recoverable. But a bump is never "done" over a red gate. Step 9 runs the generator gates; the full set is local CI:

./scripts/local_ci.sh /absolute/path/to/new_godot_binary
mkdocs build --strict

Proving the Pipeline: Dry Run

Run the pipeline against the current pin as a no-op bump:

JEXTRACT_HOME=/absolute/path/to/jextract-25 \
scripts/upgrade_godot.sh --dry-run \
  --godot-docs /absolute/path/to/godot-source/doc/classes \
  /absolute/path/to/current_godot_binary

The dry run starts from a clean tree, runs every step in write mode, requires the API diff to be a no-op and every gate (the three human-decision checks included) to pass, and fails unless the tree is byte-identical afterwards: the status, the tracked diff, every untracked file's content and the jextract output under src/generated/godot (on a fresh clone, which has none yet, the dry run creates it as the build would). It writes in place, so on every exit, a failure included, it lists what it changed and restores it. It installs no export templates. Run it after a toolchain or generator change, so the next real bump starts from a proven pipeline.

Re-check at the Next Bump

Behaviour of the pinned Godot that is not expected to last. Read this list at every bump, confirm each item, and delete it once it is settled.

  • Node.replace_by on 4.8 beta 2. On this build Node.replace_by also moves internal children and takes keep_owned_children. Upstream reverted that change on master (06e0b37ce). At the next bump, confirm that:
    • the parameter is gone from extension_api.json and from Node.replaceBy;
    • the API changes since 4.7.2 drop from 19 signatures to 18. The signature gate counts 15 of the 19 as breaks and 4 as compatible; Node.replaceBy is one of the 4. Losing the parameter is a change against the snapshot, so keep its Source break line in CHANGELOG.md until --write has recorded it, then remove the line: no release ever had the parameter;
    • internal children stay put: a node with an INTERNAL_MODE_FRONT child keeps that child after replace_by.

Pinning a Prerelease

To put main on a beta or rc, or to see what one would break on a throwaway branch, add --prerelease to the same commands. It accepts a pin such as 4.8.beta2 and a source checkout whose version.py says beta. A prerelease differs from a stable bump in two ways:

  • A tag refuses it. main can merge the pin and run every gate on it, but no release is cut until the pin is stable. Manual runs of the package workflow still build, for testing the packages.
  • The download names change. The release tag and the files carry the same dash form (4.8-beta2, Godot_v4.8-beta2_linux.x86_64.zip), so the workflows need nothing for that. A 4.8 prerelease has no universal macOS zip; scripts/download_godot_macos.sh takes the macos.arm64 zip when a release has one, and macos.universal when not.

Leaving a prerelease is an ordinary bump: edit the pin to 4.8.stable, and run the script with the stable editor, its templates and its source tag, without --prerelease.