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.

No features from new contributors

The Godot project has grown considerably over the years and reviewing contributions takes a heavy toll on maintainers, while also creating risks for the stability of the existing codebase. Given this we want to ensure that new contributors take the time to learn the codebase and engage with maintainers to build trust by working on bug fixes and documentation before diving into significant projects.

As a consequence, new features or significant re-factoring from new contributors will not be accepted without explicit permission from maintainers in advance. We consider a new contributor to be someone with 3 or fewer merged pull requests.

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

This policy is intended to provide clarity for contributors and maintainers as to what amount of AI-assistance is acceptable. These rules should be applied with empathy and considering code of conduct. Ultimately, our goal is to reduce the review burden on maintainers and to review PRs with a focus on quality and maintainability.

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. Translation software used only for communicating is not considered AI in the context of this policy.

This policy does not apply to thirdparty libraries which the Godot project relies on.

For contributors

• Do not use AI-generated text in human-to-human communication

  • This includes all interactions on GitHub, RocketChat, and in official Godot communities.

  • Machine translations are still acceptable as long as the original text was written by a human.

• Do not allow an AI agent to submit PRs on your behalf

• Do not use AI to generate substantial pieces of code

  • AI should not be used to author code. Code authoring is more than typing, it includes making decisions about where the code should go, what techniques/algorithms should be used, and ultimately what the code should look like. All those decisions need to be made by a human.

  • For example using AI for code completion is permissible. The important consideration is whether the AI is producing the same code you would have written manually or not. If you do not have the knowledge/ability to write the code yourself, you are not allowed to use AI to write it.

  • You must understand and take responsibility for everything that you submit.

• Do not use AI to generate user-facing media (e.g. documentation, images and audio)

If you do use AI, in compliance with the above principles, we expect that you put in effort to proofread and improve anything it generates. 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. Repeated submission of low-effort contributions may result in limits or bans being placed on your account.

For maintainers

• Maintainers are not obliged to review AI-assisted PRs

• Maintainers must pay special attention to quality and maintainability when reviewing AI-assisted PRs

• All PRs must be reviewed and approved by a human before merging

  • We want humans to have the last word on every review and approval.

• Remember the code of conduct and always presume good intent

"Substantial code" definition

“Substantial code” is code that poses potential risks to quality and maintainability of the engine and is to be measured on the basis of: the amount of code involved, its degree of complexity, the level of experience of the contributor in the Godot project, the area of the codebase, and ultimately the risk of merging the code.

It is commonly accepted that code changes of 15 lines or less are generally trivial (and cannot be the subject of copyright). Accordingly, we presume that anything under 15 lines should be considered trivial unless otherwise shown.