mirror of
https://github.com/godotengine/godot-contributing-docs.git
synced 2026-02-25 02:34:39 +03:00
137572d4a1
Rename "pull request guidelines" to "pull request rules and guidelines". Explain how to contribute by testing pull requests a bit better. Improve "Explain your contributions" w.r.t. overly verbose text.
119 lines
6.3 KiB
ReStructuredText
119 lines
6.3 KiB
ReStructuredText
.. _doc_pull_request_guidelines:
|
|
|
|
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 <https://godotengine.org/code-of-conduct/>`__.
|
|
|
|
.. _doc_licenses:
|
|
|
|
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 <https://github.com/godotengine/godot/blob/master/LICENSE.txt>`__.
|
|
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 <https://github.com/godotengine/godot/issues>`__ or `proposal <https://github.com/godotengine/godot-proposals/issues>`__.
|
|
- **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 :ref:`doc_optimization`).
|
|
- **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 :ref:`compatibility breakages <doc_handling_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.
|