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-buildsrelease for the new version (Godot_v<version>_macos.arm64.ziporGodot_v<version>_macos.universal.zip, whichever the release ships, andGodot_v<version>_export_templates.tpz;<version>is the dash form the workflows use, such as4.8-stable, and a prerelease is4.8-beta2).GODOT_VERSION=<version> scripts/download_godot_macos.sh <zip>downloads the macOS editor. JEXTRACT_HOMEpointing 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 itsgodot-buildsrelease. KDoc is synced from itsdoc/classes(--godot-docs), and the script checks the checkout'sversion.pyagainst the pin. Never sync frommaster, or from a tree of another build. A prerelease takes the commit of that build: itsversion.pysaysbetawithout the number. - A clean working tree apart from the pin edit, so the bump diff stays reviewable.
The Bump¶
-
Edit the pin, and only the pin. Change
kanamaGodotVersioningradle.propertiesandGODOT_VERSIONin the four workflows. On a new major.minor, also setcompatibility_minimumin the two committedkanama.gdextensiondescriptors to it (python3 scripts/check_godot_version_pin.py --list-filesnames them all). -
Look at the plan (optional).
--planruns 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
- Run the bump with the same arguments, without
--plan. Add--templates /path/to/Godot_vX_export_templates.tpzto 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.
-
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:
-
Public API signatures. Each removed or changed signature needs a
- **Source break:**line inCHANGELOG.mdunder## Unreleased(see the top of the CHANGELOG), thenpython3 scripts/check_public_signature_changes.py --write. - Adopted-list classes.
check_wrapper_generator.pyholds a list of classes to "no skipped method". When Godot gives one of them a method whose call shape has noObjectCallshelper yet, the drift gate prints it as pending, with thePENDING_HELPER_SKIPSrow to paste: the reason, the task or issue that adds the helper (replace thetask <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. - Gate evidence. A pin move makes every entry of
evidence/gates.jsonstale. Re-run each gate on the new pin, or accept it stale with a reason and an expiry date. Then re-runpython3 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'sconfig/features, the iOS size claim) and insert a row into a table likePENDING_HELPER_SKIPSinstead of replacing an empty one, so a bump needs no edit togate_red_runs.py. A few cases still mutate a Godot-generated wrapper by its literal signature (Node.setProcessMode,Label.setText, theNode.getParenthash); 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/buildinstalled by another Godot version ("Unable to set up Android build directory").android_smoke.shandandroid_export_minified.shdelete a template whoseandroid/.build_versionis not the pin and reinstall it. For a demo exported by hand, deleteres://android/build. Editor Settings > Export > Android > Build > Automatically Delete Build Directory deletes all ofres://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.shdoes, orKANAMA_API_EXERCISE=1 KANAMA_API_EXERCISE_TRACE=1onapi_exercise_smoke.tscnwith a-PkanamaApiExercise=trueaddon). A row that crashes, hangs, writes outside the scratch directory or would change a running game's state on a device gets aMETHOD_OVERRIDESor exclusion entry with that reason inscripts/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" inwrapper-maintenance.md). - When Godot adds a builtin member (a new
Vector2method, 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.jsonwithscripts/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.shwith the fresh starter step and the demo matrix on the iPhone, andscripts/android_smoke.shon 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
.importchurn in the demos repo, and moveDEMOS_REFin.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 withgit 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' syncedkanama.gdextensioncopies take the newcompatibility_minimumwhen the demos re-sync the addon. - Bump the KDoc docs-pin commit hash in
docs/contributing/wrapper-maintenance.mdto the new stable tag. - Scan
gdextension/gdextension_interface.hfor newly@deprecatedfunctions 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 (desktopconstruct_object2vs iOSconstruct_object3, issue #91 / task 61). Both must bind the same, newest construct/register/script-instance functions.scripts/check_gdextension_modernization.py(step 9 andlocal_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-stdlibandkotlinx-coroutinesof Godot's Android build template (kotlinVersioninconfig.gradleinside the export templates'android_source.zip, and./gradlew :dependencies --configuration standardDebugRuntimeClasspaththere; 4.7.2: stdlib 2.1.21, coroutines 1.6.4), soandroid/godot-plugin/{plugin,scripts}/build.gradle.ktscompile withapiVersionset to that stdlib version and against that coroutines version (kanamaAndroidCoroutinesVersioninandroid/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.
--resetrestores 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-refnames the commit whoseextension_api.jsonis 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_byon 4.8 beta 2. On this buildNode.replace_byalso moves internal children and takeskeep_owned_children. Upstream reverted that change onmaster(06e0b37ce). At the next bump, confirm that:- the parameter is gone from
extension_api.jsonand fromNode.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.replaceByis one of the 4. Losing the parameter is a change against the snapshot, so keep itsSource breakline inCHANGELOG.mduntil--writehas recorded it, then remove the line: no release ever had the parameter; - internal children stay put: a node with an
INTERNAL_MODE_FRONTchild keeps that child afterreplace_by.
- the parameter is gone from
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.
maincan 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.shtakes themacos.arm64zip when a release has one, andmacos.universalwhen 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.