Pull request rules and guidelines

This page contains rules and guidelines relevant for contributing to any area of Godot.

When contributing to any particular area, please also refer to its respective guidelines.

Respect our Code of Conduct

When you contribute to Godot, we expect that you respect our Code of Conduct.

Respect copyright

You must be mindful of the copyright and patent rights of anything you submit.

If you authored every part of your contribution and own the rights, this is not a problem. You can submit your contribution without reading further.

However, any code or assets you took from somewhere else — including code generated by AI — may be subject to copyright or patent rights, which you must respect. In such cases, you need to check the license of the material. Some licenses are permissive enough to be compatible with Godot's MIT license. You must include this license in your contribution. Examples of compatible licenses include Apache 2.0, BSD, ISC, MPL 2.0, and MIT itself.

Most other licenses are not compatible with Godot's license. This includes "copy-left" licenses like GPL or LGPL, since these licenses effectively disallow static linking in proprietary software (which Godot is distributed as in most exported projects). This also applies for libraries that are only linked in the editor.

"Source-available" is not "open-source". For example, you cannot submit exclusive code or ideas from proprietary game engines like Unreal or Unity, nor use their code as inspiration. We strongly recommend against reading any "source-available" code before contributing to Godot.

Contribute one change at a time

Each pull request should contain a single self-contained change. Avoid pushing multiple unrelated changes in the same pull request.

As a rule of thumb, if your pull request could be split into two pull requests without breaking anything, it should probably be two separate pull requests.

The exception to this rule is "batching changes", where you make the same kind of change to multiple places in the codebase. In this case, it is preferable to make one larger pull request instead of many small ones.

Note

Imagine yourself in the shoes of the reviewer: how can you make the PR easy to review and approve? This is best achieved if your pull request is simple, coherent, and uncontroversial.

Limiting pull requests to one change at a time also simplifies the Git history, makes it possible to revert or cherry-pick specific changes, and reduces the potential of accidentally introducing bugs.

Explain your contributions

When submitting a pull request, please make use of the pull request description.

Your pull request description should, as clearly and succinctly as possible, explain all the necessary information to understand the changes you made.

For example, if you're just fixing a typo, a single sentence description is appropriate.

However, if your change is large, or may affect multiple systems in potentially unexpected ways, we expect you to be more thorough with your explanation.

Here are the components of a thorough pull request description:

Summary of changes: A short overview of what is changed.
Motivation: Why you opened the pull request. Ideally, this is a link to an issue or proposal.
Related work: Link to similar pull requests or ongoing discussions that provide additional context.
Technical overview: Briefly explain each of the changes in this pull request, and why they are necessary.
Testing: How you tested the pull request, and the results of your testing. For example, optimization PRs should be profiled or benchmarked (see Optimization guidelines).
Discussion: How you see the pull request in context. For example, list risks and caveats and how they could be mitigated. If existing projects may be negatively affected, you should disclose this here, with particular attention to possible compatibility breakages and regressions.
Additional work: If applicable, highlight anything you need help with or feedback on, and describe any necessary or potential follow-up work.

Note

You may not need every one of these components, and you do not need to copy this exact structure. Always ask yourself what would be most helpful for reviewers, and try to balance brevity and thoroughness appropriately.

Contribute only what you understand

Please only submit code that you understand and are prepared to explain to a maintainer.

If you do not fully understand the code, please take extra care to test it rigorously, and disclose this in your pull request description.

This especially applies if you implement the idea of another person, copy code from elsewhere, or if you use AI to assist you with your contribution. In all of these cases, you must disclose which part of your submission wasn't fully authored by you.

AI-assisted contributions

The use of AI to contribute to Godot is discouraged, and contributions made entirely by AI are prohibited.

Note

"AI" in this page refers to any LLM/generative AI model like ChatGPT, Claude, Grok, etc., or any other models that fulfill the same role. Using translation software to communicate is fine, and single-line code completion does not have to be disclosed.

We acknowledge that AI can be useful, but we are convinced that human effort results in better and more relevant contributions.

If you do use AI, we expect that you put in effort to proofread and improve anything it generates, and that you disclose what you used AI for. As maintainers spend significant time reviewing your code, please make sure that the code you submit is well-tested and functional. Please be respectful of their time and only submit something you have put thought and effort into.