godotengine
/
godot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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 2020-01-30 01:29:54 +01:00 committed by Rémi Verschelde
parent 8e8861ed06
commit c39c3e3237
1 changed files with 91 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
CONTRIBUTING.md
View File

@ -1,70 +1,106 @@
# How to contribute efficiently # How to contribute efficiently
Sections covered in this file: ## Table of contents
* [Reporting bugs or proposing features](#reporting-bugs-or-proposing-features) - [Reporting bugs](#reporting-bugs)
* [Contributing pull requests](#contributing-pull-requests) - [Proposing features or improvements](#proposing-features-or-improvements)
* [Contributing to Godot's translation](#contributing-to-godots-translation) - [Contributing pull requests](#contributing-pull-requests)
* [Communicating with developers](#communicating-with-developers) - [Contributing to Godot's translation](#contributing-to-godots-translation)
- [Communicating with developers](#communicating-with-developers)
**Please read the first section before reporting a bug!** **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 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 several bugs and want to report them, make sure to create one new issue for
each of them. 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 ### Search first in the existing database
fix come much sooner) by following these guidelines:
#### 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 ### Specify the platform
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
Godot runs on a large variety of platforms and operating systems and devices. 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 **In your bug reports, please always specify:**
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)
#### 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 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 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: 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. 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**. 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. 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 ## 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. that several users will need in their real-life projects.
* You talked to other developers on how to implement it best (on either - You talked to other developers on how to implement it best. See also
communication channel, and maybe in a GitHub issue first before making your [Proposing features or improvements](#proposing-features-or-improvements).
PR). - Even if it doesn't get merged, your PR is useful for future work by another
* Even if it does not get merged, your PR is useful for future work by another
developer. developer.
Similar rules can be applied when contributing bug fixes - it's always best to 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) 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. 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 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 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 rebase -i`` and relevant help about rebasing or amending commits on the
Internet). Internet).
This git style guide has some good practices to have in mind: This [Git style guide](https://github.com/agis-/git-style-guide) has some
[Git Style Guide](https://github.com/agis-/git-style-guide) good practices to have in mind.
See our [PR workflow](https://docs.godotengine.org/en/latest/community/contributing/pr_workflow.html) 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. 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 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 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 message is formatted as a short title (first line) and an extended description
(everything after the first line and an empty separation line). (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 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 `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, GitHub interface unless you click the "expand" button. As the name says, try to
try to keep that first line relatively short (ideally <= 50 chars, though it's keep that first line under 72 characters. It should describe what the commit
rare to be able to tell enough in so few characters, so you can go a bit does globally, while details would go in the description. Typically, if you
higher) - it should describe what the commit does globally, while details would can't keep the title short because you have too much stuff to mention, it means
go in the description. Typically, if you can't keep the title short because you you should probably split your changes in several commits :)
have too much stuff to mention, it means that 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): description is also manually wrapped at 80 chars for readability):
``` ```text
Prevent French fries carbonization by fixing heat regulation Prevent French fries carbonization by fixing heat regulation
When using the French fries frying module, Godot would not regulate the heat 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! Fixes #1789, long live the Realm!
``` ```
*Note:* When using the GitHub online editor (or worse, the drag and drop **Note:** When using the GitHub online editor or its drag-and-drop
feature), *please* edit the commit title to something meaningful. Commits named feature, *please* edit the commit title to something meaningful. Commits named
"Update my_file.cpp" will not be accepted. "Update my_file.cpp" won't be accepted.
## Contributing to Godot's translation ## 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 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: 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 - [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 - 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 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 page](https://listengine.tuxfamily.org/godotengine.org/devel/) for
subscription instructions. subscription instructions.
Thanks! Thanks for your interest in contributing!
The Godot development team —The Godot development team