mirror of
https://github.com/baldurk/renderdoc.git
synced 2026-05-29 13:20:54 +00:00
Add guidance on filing good issues, and update issue template
* Issues not following the template will be closed. It is too much of a drain on project resources to deal with bug reports that are not well formatted and unclear. The template is easy to fill out and does not ask much.
This commit is contained in:
baldurk
@@ -26,6 +26,7 @@ You also agree by submitting your code that you grant all transferrable rights t
|
||||
4. [Developing a change](CONTRIBUTING/Developing-Change.md)
|
||||
5. [Testing](CONTRIBUTING/Testing.md)
|
||||
6. [Code Explanation](CONTRIBUTING/Code-Explanation.md)
|
||||
7. [Filing issues](CONTRIBUTING/Filing-Issues.md)
|
||||
|
||||
## Quick Start
|
||||
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
# Filing bug reports
|
||||
|
||||
Sorry that you've run into a bug! I'd like to be able to fix it, but first you need to fill out a good bug report to ensure I can understand the problem.
|
||||
|
||||
# General guidance
|
||||
|
||||
It's extremely rare that you can provide too much information, and by comparison it's quite common to provide too little information. The more information you can provide the better I can determine the bug.
|
||||
|
||||
Avoid the temptation to guess or assume what the problem is based on what you're seeing, unless you have dived into the code to find out. While it's not impossible it's probably not the case that RenderDoc crashes if you read a texture in a pixel shader. Most graphics programs do that! It's probably something more specific than that which is hard to identify without debugging. It's fine not to know what the problem is, that's my job! Just give as much information as possible.
|
||||
|
||||
If you have time, testing the latest nightly build of RenderDoc is a good idea since the bug you're reporting may have been fixed already. If the problem you're seeing is new and wasn't present in an older version of RenderDoc, it would be extremely helpful to know approximately when the problem started. You can download any historical nightly build to test with.
|
||||
|
||||
If you really want to go in-depth there is a lot of writing online about how to make good bug reports! The classic that covers a lot is [Asking smart questions](http://www.catb.org/esr/faqs/smart-questions.html).
|
||||
|
||||
Below is guidance for each section of the issue template.
|
||||
|
||||
# Description
|
||||
|
||||
In the description section you can explain what kind of problem you're running into. The golden rule for this is:
|
||||
|
||||
1. Describe what you see actually happening.
|
||||
2. Describe what you'd expect to see instead.
|
||||
|
||||
The point here is to make it clear to anyone what the bug is, because unless you describe it not everyone may understand what the problem is. If you describe what you're trying to do and where the problem arises, compared to what you would expect to happen if everything worked, it's easier to understand.
|
||||
|
||||
This is mostly relevant for bugs where something doesn't behave right rather than if something crashes where it's clear what is going wrong.
|
||||
|
||||
# Repro steps
|
||||
|
||||
This section is the most important one!
|
||||
|
||||
In order to be able to fix a bug I need to first reproduce it to understand what goes wrong. You need to describe the steps taken.
|
||||
|
||||
Be sure that your repro steps really are steps that anyone can follow. Most of the time these repro steps will include "load my capture" or "capture my application". That is totally fine, but if you say that then you **must** upload and share the capture or the application. If you don't then I can't follow the steps, and they are not useful!
|
||||
|
||||
Github has a file size limit for uploaded files. In most cases your capture or application will be too large, so you can use a free online service such as dropbox, google drive, mega, or others to share your files.
|
||||
|
||||
If you want to share your capture or application privately then please [email me](mailto:baldurk@baldurk.org?subject=RenderDoc%20bug) with it.
|
||||
|
||||
When you have no problems sharing these, please do so as soon as you open your issue. If you open the issue without any reproducing materials, then in many cases I'll have to reply to ask for them anyway!
|
||||
|
||||
If you cannot share your capture or application even privately, then that's understandable. If that's the case please say up front that you can't share any such materials. In this case you have to provide as much information as you possibly can about what your program is doing and where the problem begins - I'll have to start guessing what the problem might be and the more information I have to work with the better my guesses can be.
|
||||
|
||||
# Environment
|
||||
|
||||
Please update the environment section to at least list the main three items:
|
||||
|
||||
1. The RenderDoc version you are using (including the date or commit hash for nightly builds)
|
||||
2. Your OS, such as Windows 7, Ubuntu, Android, Windows 10
|
||||
3. The graphics API where you can reproduce this bug.
|
||||
|
||||
Giving more details here such as your GPU and driver version can't hurt, but you must include the three above since this gives important information about where the problem might be.
|
||||
@@ -0,0 +1,25 @@
|
||||
# Filing feature requests
|
||||
|
||||
(also applies to general questions)
|
||||
|
||||
Below is guidance for each section of the issue template.
|
||||
|
||||
# Description
|
||||
|
||||
When writing the description of a feature request, it's important to describe what your end goal is. If you describe only what you think the solution should be then that makes it harder to understand what you're really after. This is often known as [the XY problem](http://xyproblem.info/). You can of course describe the solution you have in mind as well, just be sure not to _only_ describe that solution.
|
||||
|
||||
Sometimes there is an improvement that may work for you but may solve other problems as well. Or perhaps the solution you have in mind might have unintended side-effects. If you describe what your workflow is and what you're trying to do then it's much easier to understand where you're coming from.
|
||||
|
||||
This can also be a reason why feature requests are turned down. If the problem you are running into is particularly niche, or you want behaviour one way but it's mutually exclusive with behaviour a different way that is generally better for users as a whole, that may be reason to turn down the request. Features don't come for free and even adding alternate options still leads to maintenance and UX burdens.
|
||||
|
||||
If this happens please be aware that it's not a criticism of your use case, and if your change is small or you feel adventurous you could change RenderDoc's source and recompile it to behave as you'd like.
|
||||
|
||||
# Repro Steps
|
||||
|
||||
You can delete this section in the issue template! It is only required for bugs. However if you want to upload a capture to exhibit exactly what problem you're trying to solve that would be very welcome :).
|
||||
|
||||
# Environment
|
||||
|
||||
Please update the environment section to at least list the main three items - the RenderDoc version you are using, your OS, and the graphics API(s) you are interested in.
|
||||
|
||||
This gives context to what you're asking for, even in cases where the feature may apply to all APIs or OSs. The RenderDoc version is also relevant in case you haven't tried the latest version where something may have changed, or if there has been work in this area since the last version was released.
|
||||
@@ -0,0 +1,13 @@
|
||||
# Filing issues
|
||||
|
||||
Thanks for taking the time to look at the guidelines for filing issues! I'm happy to help out with your issue, but badly formatted or poorly described bug reports take too much time to untangle so it's your responsibility to give me the best possible chance to know what I need to fix.
|
||||
|
||||
This document is mostly split into two parts - first for bug reports, and second for feature requests or general questions.
|
||||
|
||||
As a general rule for all issues: Please be aware that RenderDoc is a tool for debugging your programs, not for copyright infringement. If your problem or request relates to violating copyright by extracting assets or injecting into copyrighted applications that are not your own then you will find no help here.
|
||||
|
||||
To read more about how to file an issue click the appropriate link below:
|
||||
|
||||
1. [Filing a bug](Filing-Issues-Bugs.md)
|
||||
2. [Requesting a feature or asking a question](Filing-Issues-Features.md)
|
||||
|
||||
+22
-16
@@ -1,33 +1,39 @@
|
||||
**IF YOU DO NOT FOLLOW THE GUIDELINES, YOUR ISSUE WILL BE CLOSED**
|
||||
|
||||
Guide to filing issues: https://github.com/baldurk/renderdoc/blob/v1.x/docs/CONTRIBUTING/Filing-Issues.md
|
||||
|
||||
I'm happy to help fix bugs and discuss new features, but you have the responsibility to ensure I fully understand what you want and have the information I need to work on it. If you're _at all_ unsure of what is needed, please read the guide above for full information on what is expected for filing issues.
|
||||
|
||||
Delete this section when you know what to do and fill out the template below. If you do not, your issue will be closed because you clearly didn't read this!
|
||||
|
||||
----
|
||||
|
||||
## Description
|
||||
|
||||
<!--
|
||||
PLEASE NOTE: Issues relating to the 'playing for data' fork or any issues
|
||||
relating to capturing copyrighted games that you are not the author of will be
|
||||
closed.
|
||||
-->
|
||||
|
||||
<!--
|
||||
Here you can enter a short description of either the bug that you are
|
||||
encountering, or the feature/improvement you'd like to see happen.
|
||||
Here you can enter a description of either the bug that you are encountering, or the feature/improvement you'd like to see happen.
|
||||
|
||||
If you are requesting a feature please provide as much information as you can
|
||||
about what you'd like to do and also why you'd like to do it - sometimes an
|
||||
alternative approach would better address the need.
|
||||
-->
|
||||
|
||||
## Repro steps
|
||||
|
||||
<!--
|
||||
This only applies for bugs - please outline the steps you took to hit the bug.
|
||||
|
||||
If you are able to share a capture or an application that demonstrates the bug,
|
||||
please upload and link it here.
|
||||
If you're only requesting a feature you can delete this section.
|
||||
|
||||
For bug reports please describe the steps you can take to show the bug, in a way that I can follow them.
|
||||
|
||||
If you are able to share a capture, or your application, PLEASE DO THAT NOW because that is by far the easiest way to show a bug. If you cannot share because of privacy or other reasons, please say that and give as much extra information as you can.
|
||||
|
||||
-->
|
||||
|
||||
## Environment
|
||||
|
||||
* RenderDoc build: e.g. v1.0, or 2018-03-12 nightly build.
|
||||
* Operating System: e.g. Windows 10, Windows 7, Ubuntu Linux, etc
|
||||
* API: e.g. Vulkan, D3D11, OpenGL, etc
|
||||
<!-- if you are running a nightly build, list the date or commit hash for the version -->
|
||||
|
||||
* RenderDoc version: XXX
|
||||
* Operating System: XXX
|
||||
* API: XXX
|
||||
|
||||
<!-- More details here never hurt! For example your GPU, driver version, etc. -->
|
||||
|
||||
Reference in New Issue
Block a user