You've already forked godot
mirror of
https://github.com/godotengine/godot.git
synced 2025-11-04 12:00:25 +00:00
Cleanup various repository documentation files
- Reformat logo license as a plain text file. - Fix outdated links or references to SFC or Visual Script. - Tweak contents of `CONTRIBUTING.md` to highlight contributor docs more prominently, and make it easier to parse. - Tweak formatting and contents in `thirdparty/README.md` for consistency.
This commit is contained in:
Rémi Verschelde
206
CONTRIBUTING.md
206
CONTRIBUTING.md
@@ -1,11 +1,17 @@
|
||||
# How to contribute efficiently
|
||||
# Contributors guidelines
|
||||
|
||||
This document summarizes the most important points for people interested in
|
||||
contributing to Godot, especially via bug reports or pull requests.
|
||||
|
||||
The Godot documentation has a dedicated [Contributing section](https://docs.godotengine.org/en/latest/contributing/ways_to_contribute.html)
|
||||
which details these points and more, and is a recommended read.
|
||||
|
||||
## Table of contents
|
||||
|
||||
- [Reporting bugs](#reporting-bugs)
|
||||
- [Proposing features or improvements](#proposing-features-or-improvements)
|
||||
- [Contributing pull requests](#contributing-pull-requests)
|
||||
- [Contributing to Godot's translation](#contributing-to-godots-translation)
|
||||
- [Contributing to Godot translations](#contributing-to-godot-translations)
|
||||
- [Communicating with developers](#communicating-with-developers)
|
||||
|
||||
## Reporting bugs
|
||||
@@ -13,16 +19,26 @@
|
||||
Report bugs [here](https://github.com/godotengine/godot/issues/new?assignees=&labels=&template=bug_report.yml).
|
||||
Please follow the instructions in the template when you do.
|
||||
|
||||
Notably, please include a Minimal Reproduction Project (MRP), which is a small
|
||||
Godot project which reproduces the issue, with no unnecessary files included.
|
||||
Be sure to not include the `.godot` folder in the archive to save space.
|
||||
|
||||
Make sure that the bug you are experiencing is reproducible in the latest Godot
|
||||
releases. You can find an overview of all Godot releases [on the website](https://godotengine.org/download/archive/)
|
||||
to confirm whether your current version is the latest one. It's worth testing
|
||||
against both the latest stable release and the latest dev snapshot for the next
|
||||
Godot release.
|
||||
|
||||
If you run into a bug which wasn't present in an earlier Godot version (what we
|
||||
call a _regression_), please mention it and clarify which versions you tested
|
||||
(both the one(s) working and the one(s) exhibiting the bug).
|
||||
|
||||
## Proposing features or improvements
|
||||
|
||||
**Since August 2019, the main issue tracker no longer accepts feature proposals.**
|
||||
Instead, head to the [Godot Proposals repository](https://github.com/godotengine/godot-proposals)
|
||||
and follow the instructions in the README file. High-quality feature proposals
|
||||
are more likely to be well-received by the maintainers and community, so do
|
||||
your best :)
|
||||
**The main issue tracker is for bug reports and does not accept feature proposals.**
|
||||
|
||||
See [this article](https://godotengine.org/article/introducing-godot-proposals-repository)
|
||||
for detailed rationale on this change.
|
||||
Instead, head to the [Godot Proposals repository](https://github.com/godotengine/godot-proposals)
|
||||
and follow the instructions in the README file and issue template.
|
||||
|
||||
## Contributing pull requests
|
||||
|
||||
@@ -39,10 +55,9 @@ Similar rules can be applied when contributing bug fixes - it's always best to
|
||||
discuss the implementation in the bug report first if you are not 100% about
|
||||
what would be the best fix.
|
||||
|
||||
[This blog post](https://godotengine.org/article/will-your-contribution-be-merged-heres-how-tell)
|
||||
outlines the process used by core developers when assessing PRs. We strongly
|
||||
recommend that you have a look at it to know what's important to take into
|
||||
account for a PR to be considered for merging.
|
||||
You can refer to the [Pull request review process](https://docs.godotengine.org/en/latest/contributing/workflow/pr_review_guidelines.html)
|
||||
for insights into the intended lifecycle of pull requests. This should help you
|
||||
ensure that your pull request fulfills the requirements.
|
||||
|
||||
In addition to the following tips, also take a look at the
|
||||
[Engine development guide](https://docs.godotengine.org/en/latest/contributing/development/index.html)
|
||||
@@ -50,7 +65,79 @@ for an introduction to developing on Godot.
|
||||
|
||||
The [Contributing docs](https://docs.godotengine.org/en/latest/contributing/ways_to_contribute.html)
|
||||
also have important information on the [PR workflow](https://docs.godotengine.org/en/latest/contributing/workflow/pr_workflow.html)
|
||||
and the [code style](https://docs.godotengine.org/en/latest/contributing/development/code_style_guidelines.html) we use.
|
||||
(with a helpful guide for Git usage), and our [Code style guidelines](https://docs.godotengine.org/en/latest/contributing/development/code_style_guidelines.html)
|
||||
which all contributions need to follow.
|
||||
|
||||
### Be mindful of your commits
|
||||
|
||||
Try to make simple PRs that handle one specific topic. Just like for reporting
|
||||
issues, it's better to open 3 different PRs that each address a different issue
|
||||
than one big PR with three commits. This makes it easier to review, approve, and
|
||||
merge the changes independently.
|
||||
|
||||
When updating your fork with upstream changes, please use ``git pull --rebase``
|
||||
to avoid creating "merge commits". Those commits unnecessarily pollute the git
|
||||
history when coming from PRs.
|
||||
|
||||
Also try to make commits that bring the engine from one stable state to another
|
||||
stable state, i.e. if your first commit has a bug that you fixed in the second
|
||||
commit, try to merge them together before making your pull request. This
|
||||
includes fixing build issues or typos, adding documentation, etc.
|
||||
|
||||
See our [PR workflow](https://docs.godotengine.org/en/latest/contributing/workflow/pr_workflow.html)
|
||||
documentation for tips on using Git, amending commits and rebasing branches.
|
||||
|
||||
This [Git style guide](https://github.com/agis-/git-style-guide) also has some
|
||||
good practices to have in mind.
|
||||
|
||||
### Format your commit messages with readability in mind
|
||||
|
||||
The way you format your commit messages is quite important to ensure that the
|
||||
commit history and changelog will be easy to read and understand. A Git commit
|
||||
message is formatted as a short title (first line) and an extended description
|
||||
(everything after the first line and an empty separation line).
|
||||
|
||||
The short title is the most important part, as it is what will appear in the
|
||||
changelog or in the GitHub interface unless you click the "expand" button.
|
||||
Try to keep that first line under 72 characters, but you can go slightly above
|
||||
if necessary to keep the sentence clear.
|
||||
|
||||
It should be written in English, starting with a capital letter, and usually
|
||||
with a verb in imperative form. A typical bugfix would start with "Fix", while
|
||||
the addition of a new feature would start with "Add". A prefix can be added to
|
||||
specify the engine area affected by the commit. Some examples:
|
||||
|
||||
- Add C# iOS support
|
||||
- Show doc tooltips when hovering properties in the theme editor
|
||||
- Fix GLES3 instanced rendering color and custom data defaults
|
||||
- Core: Fix `Object::has_method()` for script static methods
|
||||
|
||||
If your commit fixes a reported issue, please include it in the _description_
|
||||
of the commit (not in the title) using one of the
|
||||
[GitHub closing keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)
|
||||
such as "Fixes #1234". This will cause the issue to be closed automatically if
|
||||
the PR is merged.
|
||||
|
||||
Here's an example of a well-formatted commit message (note how the extended
|
||||
description is also manually wrapped at 80 chars for readability):
|
||||
|
||||
```text
|
||||
Prevent French fries carbonization by fixing heat regulation
|
||||
|
||||
When using the French fries frying module, Godot would not regulate the heat
|
||||
and thus bring the oil bath to supercritical liquid conditions, thus causing
|
||||
unwanted side effects in the physics engine.
|
||||
|
||||
By fixing the regulation system via an added binding to the internal feature,
|
||||
this commit now ensures that Godot will not go past the ebullition temperature
|
||||
of cooking oil under normal atmospheric conditions.
|
||||
|
||||
Fixes #1340.
|
||||
```
|
||||
|
||||
**Note:** When using the GitHub online editor or its drag-and-drop
|
||||
feature, *please* edit the commit title to something meaningful. Commits named
|
||||
"Update my_file.cpp" won't be accepted.
|
||||
|
||||
### Document your changes
|
||||
|
||||
@@ -59,14 +146,14 @@ scripting APIs, you **must** update the class reference to document those.
|
||||
This is to ensure the documentation coverage doesn't decrease as contributions
|
||||
are merged.
|
||||
|
||||
[Update documentation XML files](https://docs.godotengine.org/en/latest/contributing/documentation/updating_the_class_reference.html#updating-class-reference-when-working-on-the-engine)
|
||||
[Update documentation XML files](https://docs.godotengine.org/en/latest/contributing/documentation/updating_the_class_reference.html)
|
||||
using your compiled binary, then fill in the descriptions.
|
||||
Follow the style guide described in the
|
||||
[Writing guidelines](https://docs.godotengine.org/en/latest/contributing/documentation/docs_writing_guidelines.html).
|
||||
[Documentation writing guidelines](https://docs.godotengine.org/en/latest/contributing/documentation/docs_writing_guidelines.html).
|
||||
|
||||
If your pull request modifies parts of the code in a non-obvious way, make sure
|
||||
to add comments in the code as well. This helps other people understand the
|
||||
change without having to look at `git blame`.
|
||||
change without having to dive into the Git history.
|
||||
|
||||
### Write unit tests
|
||||
|
||||
@@ -91,74 +178,13 @@ existing tests as well.
|
||||
See [Unit testing](https://docs.godotengine.org/en/latest/contributing/development/core_and_modules/unit_testing.html)
|
||||
for information on writing tests in Godot's C++ codebase.
|
||||
|
||||
### Be nice to the Git history
|
||||
## Contributing to Godot translations
|
||||
|
||||
Try to make simple PRs that handle one specific topic. Just like for reporting
|
||||
issues, it's better to open 3 different PRs that each address a different issue
|
||||
than one big PR with three commits.
|
||||
You can contribute to Godot translations on [Hosted Weblate](https://hosted.weblate.org/projects/godot-engine/),
|
||||
an open source and web-based translation platform.
|
||||
|
||||
When updating your fork with upstream changes, please use ``git pull --rebase``
|
||||
to avoid creating "merge commits". Those commits unnecessarily pollute the git
|
||||
history when coming from PRs.
|
||||
|
||||
Also try to make commits that bring the engine from one stable state to another
|
||||
stable state, i.e. if your first commit has a bug that you fixed in the second
|
||||
commit, try to merge them together before making your pull request (see ``git
|
||||
rebase -i`` and relevant help about rebasing or amending commits on the
|
||||
Internet).
|
||||
|
||||
This [Git style guide](https://github.com/agis-/git-style-guide) has some
|
||||
good practices to have in mind.
|
||||
|
||||
See our [PR workflow](https://docs.godotengine.org/en/latest/contributing/workflow/pr_workflow.html)
|
||||
documentation for tips on using Git, amending commits and rebasing branches.
|
||||
|
||||
### Format your commit messages with readability in mind
|
||||
|
||||
The way you format your commit messages is quite important to ensure that the
|
||||
commit history and changelog will be easy to read and understand. A Git commit
|
||||
message is formatted as a short title (first line) and an extended description
|
||||
(everything after the first line and an empty separation line).
|
||||
|
||||
The short title is the most important part, as it is what will appear in the
|
||||
`shortlog` changelog (one line per commit, so no description shown) or in the
|
||||
GitHub interface unless you click the "expand" button. As the name says, try to
|
||||
keep that first line under 72 characters. It should describe what the commit
|
||||
does globally, while details would go in the description. Typically, if you
|
||||
can't keep the title short because you have too much stuff to mention, it means
|
||||
you should probably split your changes in several commits :)
|
||||
|
||||
Here's an example of a well-formatted commit message (note how the extended
|
||||
description is also manually wrapped at 80 chars for readability):
|
||||
|
||||
```text
|
||||
Prevent French fries carbonization by fixing heat regulation
|
||||
|
||||
When using the French fries frying module, Godot would not regulate the heat
|
||||
and thus bring the oil bath to supercritical liquid conditions, thus causing
|
||||
unwanted side effects in the physics engine.
|
||||
|
||||
By fixing the regulation system via an added binding to the internal feature,
|
||||
this commit now ensures that Godot will not go past the ebullition temperature
|
||||
of cooking oil under normal atmospheric conditions.
|
||||
|
||||
Fixes #1789, long live the Realm!
|
||||
```
|
||||
|
||||
**Note:** When using the GitHub online editor or its drag-and-drop
|
||||
feature, *please* edit the commit title to something meaningful. Commits named
|
||||
"Update my_file.cpp" won't be accepted.
|
||||
|
||||
## Contributing to Godot's translation
|
||||
|
||||
You can contribute to Godot's translation from the [Hosted
|
||||
Weblate](https://hosted.weblate.org/projects/godot-engine/godot), an open
|
||||
source and web-based translation platform. Please refer to the [translation
|
||||
readme](editor/translations/README.md) for more information.
|
||||
|
||||
You can also help translate [Godot's
|
||||
documentation](https://hosted.weblate.org/projects/godot-engine/godot-docs/)
|
||||
on Weblate.
|
||||
Please refer to our [editor and documentation localization guidelines](https://docs.godotengine.org/en/latest/contributing/documentation/editor_and_docs_localization.html)
|
||||
for an overview of the translation resources and what they correspond to.
|
||||
|
||||
## Communicating with developers
|
||||
|
||||
@@ -171,15 +197,13 @@ or a bug you want to fix), the following channels can be used:
|
||||
|
||||
- [Godot Contributors Chat](https://chat.godotengine.org): You will
|
||||
find most core developers there, so it's the go-to platform for direct chat
|
||||
about Godot Engine development. Feel free to start discussing something there
|
||||
to get some early feedback before writing up a detailed proposal in a GitHub
|
||||
issue.
|
||||
about Godot Engine development. Browse the [Directory](https://chat.godotengine.org/directory/channels)
|
||||
for an overview of public channels focusing on various engine areas which you
|
||||
might be interested in.
|
||||
- [Bug tracker](https://github.com/godotengine/godot/issues): If there is an
|
||||
existing issue about a topic you want to discuss, just add a comment to it -
|
||||
many developers watch the repository and will get a notification. You can
|
||||
also create a new issue - please keep in mind to create issues only to
|
||||
discuss quite specific points about the development, and not general user
|
||||
feedback or support requests.
|
||||
existing issue about a topic you want to discuss, you can participate directly.
|
||||
If not, you can open a new issue. Please mind the guidelines outlined above
|
||||
for bug reporting.
|
||||
- [Feature proposals](https://github.com/godotengine/godot-proposals/issues):
|
||||
To propose a new feature, we have a dedicated issue tracker for that. Don't
|
||||
hesitate to start by talking about your idea on the Godot Contributors Chat
|
||||
|
||||
Reference in New Issue
Block a user