Process/Bug Reports/Triaging Playbook

=Blender Bug Triaging Playbook=

This assumes you are already familiar with gitea (blenders bugtacking system) and the bug fixing process as a whole. For additional information, reading How to help triaging bugs? and A Bugs Life is encouraged. If you encounter a situation that is not clear what to do, then is probably a new scenario (and should be added below).

Missing Scenarios:

Add them here if you want them discussed before we create an action template for them.
 * Issue building blender (these should be handled here instead

Spam Scenario:
 * Task is spam

Should Close Task Scenarios:
 * No reply after a week
 * Low quality report
 * Too complex file report, where user could not simplify enough
 * Feature request
 * Accidental feature request
 * Request for support
 * Multi-report (many reports in a single report)
 * Valid report, but fixed already
 * Complete report, but on a feature branch
 * Complete report, but out of memory
 * Complete report, but performance
 * Complete report, but corrupted mesh
 * Complete report, but dependency cycle
 * Unsupported graphics card or driver
 * Blender doesn't run / crashes

Need More Information Scenarios:
 * Unexpected UI/Tool behaviour
 * Complete report, but cannot reproduce

Valid Bug Reports:
 * Valid report general instructions
 * Valid crash report, can confirm
 * Valid crash report, can confirm it crashes "at random"
 * Valid generic report, can confirm, known working version

Task is spam
Example:

Action:
 * Close the report.
 * Change the `Status >` label to `Status > Archived` (a bot should do this automatically - but only visible after a manual refresh of the page).
 * Re-title report to "Removed spam", and empty the description and subscribers.
 * Notify Thomas Dinges (@ThomasDinges) in blender.chat with link to the bug report for further action regarding user account.

No reply after a week
Example:

Action:
 * If the report status is "Needs Information From User" but there was no reply within a week, Close the report.
 * Change the `Status >` label to `Status > Archived` (a bot should do this automatically - but only visible after a manual refresh of the page).
 * Explain our policy.

Low quality report
Example:, ,

Action:
 * Close the report.
 * Change the `Status >` label to `Status > Archived` (a bot should do this automatically - but only visible after a manual refresh of the page).
 * Explain that report doesn’t contain enough information.

Too complex file report, where user could not simplify enough
Example:

Note: Python code is prone to introduce errors, so we are more strict on drawing the line for simplification in these cases.

Action:
 * Close the report.
 * Change the `Status >` label to `Status > Archived` (a bot should do this automatically - but only visible after a manual refresh of the page).
 * Explain our limitations in tackle complex files.

Feature request
Example:

Action:
 * Close the report.
 * Change the `Status >` label to `Status > Archived` (a bot should do this automatically - but only visible after a manual refresh of the page).
 * Direct the user to the proper place for feature requests.

Accidental feature request
Example:

Note 1: Users may use tools for purposes they weren’t originally intended to solve and find they behave poorly. Even though it may seem like a bug. If they are trying to use functionality in a way it’s not intended - then it’s not considered a bug.

Note 2: If this seems like a generally useful improvement, we can consider adding it as a TODO as long as a developer has time to work on this. See: T63725

Action:
 * Close the report.
 * Change the `Status >` label to `Status > Archived` (a bot should do this automatically - but only visible after a manual refresh of the page).
 * Explain that we do only bugs here.

Request for support
Action:
 * Close the report.
 * Change the `Status >` label to `Status > Archived` (a bot should do this automatically - but only visible after a manual refresh of the page).

Multi-report
Example:

Action:
 * Close the report.
 * Change the `Status >` label to `Status > Archived` (a bot should do this automatically - but only visible after a manual refresh of the page).
 * Reply that users may edit to only include a single issue, opening new reports for all other issues.

Valid report, but fixed already
Example:

Note 1: To be sure of this you need to have tested with both the reported blender version, and the latest (main branch) revision or daily build.

Note 2: If you don't have the blender version used, and cannot reproduce the crash in any old version DO NOT close this report, refer to the "Complete report, but cannot reproduce".

Action:
 * Close the report.
 * Change the `Status >` label to `Status > Resolved`
 * Be explicit on the versions used to test and ask users to download a new blender.
 * (Optional) find the commit that fixed the issue (e.g. by bisecting) and leave this as a comment (this can help to determine if this commit should be backported to LTS).

Valid report, but duplicate exists
Action:
 * Mention the duplicate issue in a comment (reference its issue number including the dash character, e.g. `#12345` so this correctly shows up in the report this will get merged to)
 * Close the report. Change the `Status >` label to `Status > Duplicate`
 * Ask the user to subscribe in the report this is merged to (this will not happen automatically).

Complete report, but on a feature branch
Example:, , ,

Action:
 * Close the report.
 * Change the `Status >` label to `Status > Archived` (a bot should do this automatically - but only visible after a manual refresh of the page).
 * Explain that feature branches are not open for bug reports.

Complete report, but out of memory
Example:

Action:
 * Close the report.
 * Change the `Status >` label to `Status > Archived` (a bot should do this automatically - but only visible after a manual refresh of the page).
 * Explain that the user needs more memory for production scenes.

Complete report, but performance
Example:

Action: Unless this is a lag with decent hardware, recent drivers and not-so-insane geometry/shader (or performance regressed from a previous version of blender):
 * Close the report.
 * Change the `Status >` label to `Status > Archived` (a bot should do this automatically - but only visible after a manual refresh of the page).

Complete report, but corrupted mesh
Example:

Action: Unless we have a way to reproduce it from scratch with the latest Blender:
 * Close the report.
 * Change the `Status >` label to `Status > Archived` (a bot should do this automatically - but only visible after a manual refresh of the page).
 * Mention that corruptions can be found (and corrected) using Mesh.validate and/or Mesh.validate_material_indices

Complete report, but dependency cycle
Example:

Action:
 * Close the report.
 * Change the `Status >` label to `Status > Archived` (a bot should do this automatically - but only visible after a manual refresh of the page).
 * Change the `Type >` label to `Type > Known Issue`

Unsupported graphics card or driver
Action:
 * Change the `Status >` label to `Status > Needs Information from User`.

Action:
 * Close the report.
 * Change the `Status >` label to `Status > Archived` (a bot should do this automatically - but only visible after a manual refresh of the page).

Blender doesn't run / crashes
Example:

Action: Unless the Worked field is properly filled, in which case we are talking about a valid regression:
 * Close the report.
 * Change the `Status >` label to `Status > Archived` (a bot should do this automatically - but only visible after a manual refresh of the page).

Unexpected UI/Tool behaviour
Example:

Action:
 * Change the `Status >` label to `Status > Needs Information from User`
 * Ask for more information from user.

Complete report, but cannot reproduce
Example:

Note: Assumes triager tested both the latest stable Blender and the latest HEAD.

Actions:


 * Change the `Status >` label to `Status > Needs Information from User`
 * If user was not using the latest stable or a recent nightly build blender and ask for they to test with recent Blender;
 * Otherwise ask for more clear instructions.

Missing version of Blender that still worked
Knowing whether a problem was introduced recently or has been in Blender for years can help prioritising and triaging reports. For this the bug report template has a field "newest version of Blender that worked as expected". This field is often not filled out, or even removed by people.

Actions:


 * Change the `Status >` label to `Status > Needs Information from User`
 * Ask for testing with a few older versions of Blender.

Crashes or errors involving your own C/C++ code (Python C/API for example)
Example:

Actions:


 * Change the `Status >` label to `Status > Needs Information from User`
 * Ask for identifying the error in Blender's code.

Valid Bug Reports
Even valid confirmed reports can benefit from asking extra assistance from the reporter. In these cases (proven the files are not over complex) we can still go ahead and set their priorities.

Some of these topics have Advanced actions instructions. To follow these we presume the triager is already capable of building blender in release or debug modes.

Valid report general instructions
Action:
 * Tag the corresponding module (change the `Module >` label). If unsure about their choice of module, CC the @blender/Module team which consists of the module owners.
 * Change the `Status >` label to `Status > Confirmed`
 * Check if the title is good otherwise edit it.
 * If the file is complex enough that a developer would need to spend time further simplifying it, ask user to help.

Valid crash report, can confirm
Example: ,

Note 1: Change the `Priority >` label to `Priority > High` unless it is a really obscure bug. If you think it should be Unbreak Now! contact the corresponding module developers or one of our coordinators.

Action:
 * Tag the corresponding module (change the `Module >` label). If unsure about their choice of module, CC the @blender/Module team which consists of the module owners.
 * Change the `Status >` label to `Status > Confirmed`
 * Check if the title is good otherwise edit it.
 * If the file is complex enough that a developer would need to spend time further simplifying it, ask user to help.

Advanced Actions:
 * If possible also include a one line crash message with a full backtrace as inline code or text file
 * If the issue was nailed down to a recent faulty commit, contact the commit author and/or subscribe the autor in the issue to raise awareness.

Valid crash report, can confirm it crashes "at random"
Example: ,

Note: We need first to determine if it is a thread "run condition" or memory access issue.

Action: Run Blender with --debug-depsgraph-no-threads --threads 1 to see if crash still happens (can use a regular release Blender)

Action:
 * Tag the corresponding module (change the `Module >` label). If unsure about their choice of module, CC the @blender/Module team which consists of the module owners.
 * Change the `Status >` label to `Status > Confirmed`
 * Check if the title is good otherwise edit it.
 * If the file is complex enough that a developer would need to spend time further simplifying it, ask user to help.

Advanced Action: Build a debug Blender with CMAKE_BUILD_TYPE=Debug WITH_COMPILER_ASAN=ON and WITH_ASSERT_ABORT=ON. If that still failed to catch the issue rebuild without the ASAN option, but with WITH_MEM_VALGRIND=ON instead. Include a one line error message with a full backtrace stored in https://developer.blender.org/paste (see example tasks).'''

Valid generic report, can confirm, known working version
Example:

Action:
 * Tag the corresponding module (change the `Module >` label). If unsure about their choice of module, CC the @blender/Module team which consists of the module owners.
 * Change the `Status >` label to `Status > Confirmed`
 * Check if the title is good otherwise edit it.
 * If the file is complex enough that a developer would need to spend time further simplifying it, ask user to help.
 * If the issue was introduced within approximately the last 6 months this is a regression so change the `Priority >` label to `Priority > High`.

Advanced Action:
 * If the triager has the time, or user volunteers to help, give general bisect instructions. After bisect update the task description with the known problematic issue.
 * Contact the commit author and/or subscribe the author in the issue to raise awareness.