From a6dc35e5cf9a66c64efeff6388a1c4b66f8d1e61 Mon Sep 17 00:00:00 2001 From: Jason Yundt Date: Thu, 24 Feb 2022 17:14:29 -0500 Subject: [PATCH] Streamline and centralize bug reporting guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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: [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 --- .github/ISSUE_TEMPLATE/bug_report.yml | 21 ++++--- CONTRIBUTING.md | 81 +-------------------------- 2 files changed, 15 insertions(+), 87 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 0b4abac1afc..1050f259a07 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -5,9 +5,10 @@ body: - type: markdown attributes: value: | - - Read our [CONTRIBUTING.md guide](https://github.com/godotengine/godot/blob/master/CONTRIBUTING.md#reporting-bugs) on reporting bugs. + - When reporting bugs, you'll make our life simpler (and the fix will come sooner) if you follow the guidelines in this template. - Write a descriptive issue title above. - - Search [open](https://github.com/godotengine/godot/issues) and [closed](https://github.com/godotengine/godot/issues?q=is%3Aissue+is%3Aclosed) issues to ensure it has not already been reported. + - 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. + - Search [open](https://github.com/godotengine/godot/issues) and [closed](https://github.com/godotengine/godot/issues?q=is%3Aissue+is%3Aclosed) issues to ensure it has not already been reported. 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. - Verify that you are using a [supported Godot version](https://docs.godotengine.org/en/stable/about/release_policy.html). - type: input @@ -24,9 +25,11 @@ body: attributes: label: System information description: | - Specify the OS version, and when relevant hardware information. - For graphics-related issues, specify the GPU model, driver version, and the rendering backend (GLES2, GLES3, Vulkan). - placeholder: Windows 10, GLES3, Intel HD Graphics 620 (27.20.100.9616) + - Specify the OS version, and when relevant hardware information. + - For issues that are likely OS-specific and/or graphics-related, please specify the CPU model and architecture. + - For graphics-related issues, specify the GPU model, driver version, and the rendering backend (GLES2, GLES3, Vulkan). + - **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. + placeholder: Windows 10, Intel Core i5-7200U, GLES3, Intel HD Graphics 620 (27.20.100.9616) validations: required: true @@ -52,8 +55,10 @@ body: attributes: label: Minimal reproduction project description: | - A small Godot project which reproduces the issue, with no unnecessary files included. Be sure to not include the `.godot` folder in the archive (but keep `project.godot`). - Required, unless the reproduction steps are trivial and don't require any project files to be followed. In this case, write "N/A" in the field. - Drag and drop a ZIP archive to upload it. **Do not select another field until the project is done uploading.** + - A small Godot project which reproduces the issue, with no unnecessary files included. Be sure to not include the `.godot` folder in the archive (but keep `project.godot`). + - Required, unless the reproduction steps are trivial and don't require any project files to be followed. In this case, write "N/A" in the field. + - Drag and drop a ZIP archive to upload it. **Do not select another field until the project is done uploading.** + - **Note for C# users:** If your issue is *not* Mono-specific, please upload a minimal reproduction project written in GDScript or VisualScript. This will make it easier for contributors to reproduce the issue locally as not everyone has a Mono setup available. + - **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. validations: required: true diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index aea1c8c5ffc..30934dcf9b4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,87 +8,10 @@ - [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 -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. - -If you're reporting a new bug, you'll make our life simpler (and the -fix will come 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. - -### Specify the platform - -Godot runs on a large variety of platforms and operating systems and devices. -**In your bug reports, please always specify:** - -- 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_64, arm64, 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. If you're describing a procedure to follow -in the editor, don't hesitate to include screenshots. - -Making your bug report easy to reproduce will make it easier for contributors -to fix the bug. - -### 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 - and then figure out why it's failing. -- On the contributors' end, recreating a test project from scratch takes valuable - time that can be saved by uploading a *minimal* project. - -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**. -We recommend attaching a ZIP file with the minimal project directly to the bug report, -by drag and dropping the file in the GitHub edition field. This ensures the file -can remain available for a long period of time. Only use third-party file hosts -if your ZIP file isn't accepted by GitHub because it's too large. - -We recommend always attaching a minimal reproduction project, even if the issue -may seem simple to reproduce manually. - -**Note for C# users:** If your issue is *not* .NET-specific, please upload a -minimal reproduction project written in GDScript. -This will make it easier for contributors to reproduce the issue -locally as not everyone has a .NET setup available. - -**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.yml)** +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