Development workflow

Branches

The development branch is master. Stable releases are cut from versioned branches like 4.6 and 4.5; bugfix backports go to those branches via cherry-pick PRs. New features only land on master.

Setting up a fork

git clone https://github.com/<your-fork>/godot.git
cd godot
git remote add upstream https://github.com/godotengine/godot.git
git fetch upstream
git checkout -b feature/short-description upstream/master

A short, descriptive branch name is appreciated.

The change loop

1. Build for your platform — see Getting started. Use dev_build=yes for fast incremental compiles while iterating.
2. Make the change. Match the surrounding style; clang-format will canonicalize it on commit.
3. Build again. Most Godot subsystems are heavily templated; SCons handles the dependency tracking.
4. Run targeted tests — bin/godot.<platform>.editor.<arch> --headless --test --test-case='*Vector3*'.
5. Run the editor / a sample project to validate end-to-end behaviour where unit tests aren't enough (rendering, audio, UI).
6. Run pre-commit — pre-commit run --files <changed files> or pre-commit run --all-files.
7. Commit. Use imperative mood, prefix with the area when helpful (Core: , Editor: , GDScript: , Rendering: , Physics: , …). Keep the title under 72 characters.

Squash, rebase, and force-push

Godot's standard practice: keep your branch rebased on upstream/master and squash unwanted intermediate commits before review. PR reviewers may ask for additional commits to be squashed before merging. Force-pushing your own PR branch is fine and expected.

git fetch upstream
git rebase upstream/master
git push --force-with-lease

The master branch never receives merge commits — maintainers rebase-merge or squash on master.

PR review process

The detailed workflow lives in the Pull request review process, but the short version:

1. Assigned reviewers (often based on which area the file you touched belongs to) read the PR.
2. They request changes, ask for tests, or approve.
3. Two approvals from maintainers are typically required for a PR to merge.
4. The maintainer with merge rights does the squash-or-rebase merge.

Reviews can sit for a while — Godot is volunteer-driven and reviewer time is finite. Pinging is OK after a week with no activity; ping in the relevant Godot Contributors Chat channel rather than (or in addition to) GitHub.

CI

PRs trigger GitHub Actions workflows under .github/workflows/. The matrix typically covers:

• Linux/BSD with GCC + Clang.
• Windows with MSVC.
• macOS with Apple Clang.
• Android editor + templates.
• iOS templates.
• Web templates.
• A "static checks" job that runs pre-commit, clang-tidy, doc coverage, and a few project-level lints.

A green CI is necessary but not sufficient — reviewers also want behavioural verification.

Cherry-picking

Bug fixes are typically targeted at master first, then cherry-picked to active stable branches by maintainers (or by the contributor in a follow-up PR). Tag your bugfix PR with the version you would like backported to in the description.

Maintaining the class reference

Adding methods/properties/signals to a ClassDB-bound class? Update doc/classes/<ClassName>.xml:

./bin/godot.linuxbsd.editor.x86_64 --headless --doctool .

This regenerates the XML from the bound API. Existing descriptions are preserved; only the structural elements (method signatures, types, defaults) are updated. Then commit the regenerated file alongside your code change. CI will fail if structure and code drift.