mirror of
https://github.com/godotengine/godot.git
synced 2024-12-03 09:52:18 +08:00
a6dc35e5cf
Before this change, there was three different bug reporting guides: - [“Filing an issue on GitHub”][1] - [“Reporting bugs”][2] - [The issue template][3] This commit: 1. makes sure that [the issue template][3] contains all of the same information that [“Filing an issue on GitHub”][1] and [“Reporting bugs”][2] did and 2. makes [“Reporting bugs”][2] simply tell users to fill out the template. The goal of this change is to make reporting bugs easier. This change accomplishes that goal by presenting bug reporters with all of the information they need to know on the bug reporting page itself. This commit partially implements this proposal: <https://github.com/godotengine/godot-proposals/discussions/4083> [1]: https://docs.godotengine.org/en/stable/community/contributing/ways_to_contribute.html#filing-an-issue-on-github [2]: ./CONTRIBUTING.md#reporting-bugs [3]: ./.github/ISSUE_TEMPLATE/bug_report.yml
191 lines
9.0 KiB
Markdown
191 lines
9.0 KiB
Markdown
# How to contribute efficiently
|
|
|
|
## 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)
|
|
- [Communicating with developers](#communicating-with-developers)
|
|
|
|
## Reporting bugs
|
|
|
|
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.
|
|
|
|
## 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 :)
|
|
|
|
See [this article](https://godotengine.org/article/introducing-godot-proposals-repository)
|
|
for detailed rationale on this change.
|
|
|
|
## Contributing pull requests
|
|
|
|
If you want to add new engine features, please make sure that:
|
|
|
|
- This functionality is desired, which means that it solves a common use case
|
|
that several users will need in their real-life projects.
|
|
- You talked to other developers on how to implement it best. See also
|
|
[Proposing features or improvements](#proposing-features-or-improvements).
|
|
- Even if it doesn't get merged, your PR is useful for future work by another
|
|
developer.
|
|
|
|
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.
|
|
|
|
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)
|
|
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.
|
|
|
|
### Document your changes
|
|
|
|
If your pull request adds methods, properties or signals that are exposed to
|
|
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)
|
|
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).
|
|
|
|
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`.
|
|
|
|
### Write unit tests
|
|
|
|
When fixing a bug or contributing a new feature, we recommend including unit
|
|
tests in the same commit as the rest of the pull request. Unit tests are pieces
|
|
of code that compare the output to a predetermined *expected result* to detect
|
|
regressions. Tests are compiled and run on GitHub Actions for every commit and
|
|
pull request.
|
|
|
|
Pull requests that include tests are more likely to be merged, since we can have
|
|
greater confidence in them not being the target of regressions in the future.
|
|
|
|
For bugs, the unit tests should cover the functionality that was previously
|
|
broken. If done well, this ensures regressions won't appear in the future
|
|
again. For new features, the unit tests should cover the newly added
|
|
functionality, testing both the "success" and "expected failure" cases if
|
|
applicable.
|
|
|
|
Feel free to contribute standalone pull requests to add new tests or improve
|
|
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
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Communicating with developers
|
|
|
|
The Godot Engine community has [many communication
|
|
channels](https://godotengine.org/community), some used more for user-level
|
|
discussions and support, others more for development discussions.
|
|
|
|
To communicate with developers (e.g. to discuss a feature you want to implement
|
|
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.
|
|
- [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.
|
|
- [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
|
|
to make sure that it makes sense in Godot's context.
|
|
|
|
Thanks for your interest in contributing!
|
|
|
|
—The Godot development team
|