Improve `CONTRIBUTING.md` and update it to follow recent changes
- Improve the bug reporting guidelines for readability.
- Make some guidelines more strictly applied in the interest of
bug report quality.
- Mention that feature proposals should now be opened on the
Godot Proposals repository.
- Update the Git commit message guide to be easier to follow.
- Fix warnings reported by markdownlint.
(cherry picked from commit 7b5c502ba5)
This commit is contained in:
Hugo Locurcio
Rémi Verschelde
parent
8e8861ed06
commit
c39c3e3237
147
CONTRIBUTING.md
147
CONTRIBUTING.md
|
|
@ -1,70 +1,106 @@
|
|||
# How to contribute efficiently
|
||||
|
||||
Sections covered in this file:
|
||||
## Table of contents
|
||||
|
||||
* [Reporting bugs or proposing features](#reporting-bugs-or-proposing-features)
|
||||
* [Contributing pull requests](#contributing-pull-requests)
|
||||
* [Contributing to Godot's translation](#contributing-to-godots-translation)
|
||||
* [Communicating with developers](#communicating-with-developers)
|
||||
- [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)
|
||||
|
||||
**Please read the first section before reporting a bug!**
|
||||
|
||||
## Reporting bugs or proposing features
|
||||
## Reporting bugs
|
||||
|
||||
The golden rule is to **always open *one* issue for *one* bug**. If you notice
|
||||
several bugs and want to report them, make sure to create one new issue for
|
||||
each of them.
|
||||
|
||||
Everything referred to hereafter as "bug" also applies for feature requests.
|
||||
If you're reporting a new bug, you'll make our life simpler (and the
|
||||
fix will come sooner) by following these guidelines:
|
||||
|
||||
If you are reporting a new issue, you will make our life much simpler (and the
|
||||
fix come much sooner) by following these guidelines:
|
||||
### Search first in the existing database
|
||||
|
||||
#### Search first in the existing database
|
||||
Issues are often reported several times by various users. It's good practice to
|
||||
**search first in the [issue tracker](https://github.com/godotengine/godot/issues)
|
||||
before reporting your issue**. If you don't find a relevant match or if you're
|
||||
unsure, don't hesitate to **open a new issue**. The bugsquad will handle it
|
||||
from there if it's a duplicate.
|
||||
|
||||
Issues are often reported several times by various users. It's a good practice
|
||||
to **search first** in the issues database before reporting your issue. If you
|
||||
don't find a relevant match or if you are unsure, don't hesitate to **open a
|
||||
new issue**. The bugsquad will handle it from there if it's a duplicate.
|
||||
|
||||
#### Specify the platform
|
||||
### Specify the platform
|
||||
|
||||
Godot runs on a large variety of platforms and operating systems and devices.
|
||||
If you believe your issue is device/platform dependent (for example if it is
|
||||
related to the rendering, crashes or compilation errors), please specify:
|
||||
* Operating system
|
||||
* Device (including architecture, e.g. x86, x86_64, arm, etc.)
|
||||
* GPU model (and driver in use if you know it)
|
||||
**In your bug reports, please always specify:**
|
||||
|
||||
#### Specify steps to reproduce
|
||||
- Operating system and version (e.g. Windows 10, macOS 10.15, Ubuntu 19.10)
|
||||
- Godot version (e.g. 3.2, 3.1.2, or the Git commit hash if you're using a development branch)
|
||||
|
||||
For bugs that are likely OS-specific and/or graphics-related, please also specify:
|
||||
|
||||
- Device (CPU model including architecture, e.g. x86, x86_64, ARM, etc.)
|
||||
- GPU model (and the driver version in use if you know it)
|
||||
|
||||
**Bug reports not including the required information may be closed at the
|
||||
maintainers' discretion.** If in doubt, always include all the requested
|
||||
information; it's better to include too much information than not enough
|
||||
information.
|
||||
|
||||
### Specify steps to reproduce
|
||||
|
||||
Many bugs can't be reproduced unless specific steps are taken. Please **specify
|
||||
the exact steps** that must be taken to reproduce the condition, and try to
|
||||
keep them as minimal as possible.
|
||||
keep them as minimal as possible. If you're describing a procedure to follow
|
||||
in the editor, don't hesitate to include screenshots.
|
||||
|
||||
#### Provide a simple, example project
|
||||
Making your bug report easy to reproduce will make it easier for contributors
|
||||
to fix the bug.
|
||||
|
||||
Sometimes an unexpected behavior happens in your project. In such case,
|
||||
### Provide a simple, example project
|
||||
|
||||
Sometimes, unexpected behavior can happen in your project. In such case,
|
||||
understand that:
|
||||
* What happens to you may not happen to other users.
|
||||
* We can't take the time to look at your project, understand how it is set up
|
||||
|
||||
- What happens to you may not happen to other users.
|
||||
- We can't take the time to look at your project, understand how it is set up
|
||||
and then figure out why it's failing.
|
||||
|
||||
To speed up our work, please prepare for us **a simple project** that isolates
|
||||
To speed up our work, **please upload a minimal project** that isolates
|
||||
and reproduces the issue. This is always the **best way for us to fix it**.
|
||||
You can attach a zip file with the minimal project directly to the bug report,
|
||||
You can attach a ZIP file with the minimal project directly to the bug report,
|
||||
by drag and dropping the file in the GitHub edition field.
|
||||
|
||||
We recommend always attaching a minimal reproduction project, even if the issue
|
||||
may seem simple to reproduce manually.
|
||||
|
||||
**If you've been asked by a maintainer to upload a minimal reproduction project,
|
||||
you *must* do so within 7 days.** Otherwise, your bug report will be closed as
|
||||
it'll be considered too difficult to diagnose.
|
||||
|
||||
Now that you've read the guidelines, click the link below to create a
|
||||
bug report:
|
||||
|
||||
- **[Report a bug](https://github.com/godotengine/godot/issues/new?assignees=&labels=&template=bug_report.md&title=)**
|
||||
|
||||
## 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 functionalities, please make sure that:
|
||||
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
|
||||
- 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 (on either
|
||||
communication channel, and maybe in a GitHub issue first before making your
|
||||
PR).
|
||||
* Even if it does not get merged, your PR is useful for future work by another
|
||||
- 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
|
||||
|
|
@ -83,7 +119,7 @@ for an introduction to developing on Godot.
|
|||
The [Contributing docs](https://docs.godotengine.org/en/latest/community/contributing/index.html)
|
||||
also have important information on the PR workflow and the code style we use.
|
||||
|
||||
#### Be nice to the git history
|
||||
### 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
|
||||
|
|
@ -99,33 +135,31 @@ 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 has some good practices to have in mind:
|
||||
[Git Style Guide](https://github.com/agis-/git-style-guide)
|
||||
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/community/contributing/pr_workflow.html)
|
||||
documentation for tips on using Git, amending commits and rebasing branches.
|
||||
|
||||
#### Format your commit logs with readability in mind
|
||||
### Format your commit messages with readability in mind
|
||||
|
||||
The way you format your commit logs is quite important to ensure that the
|
||||
commit history and changelog will be easy to read and understand. A git commit
|
||||
log is formatted as a short title (first line) and an extended description
|
||||
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 tells it,
|
||||
try to keep that first line relatively short (ideally <= 50 chars, though it's
|
||||
rare to be able to tell enough in so few characters, so you can go a bit
|
||||
higher) - 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 that you should probably split your
|
||||
changes in several commits :)
|
||||
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 log (note how the extended
|
||||
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
|
||||
|
|
@ -139,9 +173,9 @@ of cooking oil under normal atmospheric conditions.
|
|||
Fixes #1789, long live the Realm!
|
||||
```
|
||||
|
||||
*Note:* When using the GitHub online editor (or worse, the drag and drop
|
||||
feature), *please* edit the commit title to something meaningful. Commits named
|
||||
"Update my_file.cpp" will not be accepted.
|
||||
**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
|
||||
|
||||
|
|
@ -162,6 +196,7 @@ 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:
|
||||
|
||||
- [GitHub issues](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 -
|
||||
all developers watch the repository and will get an email notification. You
|
||||
|
|
@ -182,6 +217,6 @@ or a bug you want to fix), the following channels can be used:
|
|||
page](https://listengine.tuxfamily.org/godotengine.org/devel/) for
|
||||
subscription instructions.
|
||||
|
||||
Thanks!
|
||||
Thanks for your interest in contributing!
|
||||
|
||||
The Godot development team
|
||||
—The Godot development team
|
||||
|
|
|
|||
Loading…
Reference in New Issue