mirror of
https://github.com/godotengine/godot-contributing-docs.git
synced 2025-12-31 05:48:13 +03:00
6b0295a1d3
* Reorganized some things that got split in the move * Reformatted the areas and teams for readability * Merged the now stub page for trackers into areas (pending more detailed page on that area)
123 lines
5.5 KiB
ReStructuredText
123 lines
5.5 KiB
ReStructuredText
.. _doc_bug_triage_intro:
|
||
|
||
Introduction to issue triage
|
||
============================
|
||
|
||
So you are looking to help with bug triage? First of all, thank you!
|
||
Your help means a lot!
|
||
|
||
Bug triage is a fundamental part of our development, this should not be
|
||
surprising, but this process is far more than just confirming that a bug
|
||
is happening. The more information we have on a bug, what problems it
|
||
causes, when it was introduced, what areas it affects, and so on makes a
|
||
lot of difference. A bug being thoroughly triaged bug helps other
|
||
contributors a lot. Knowing something was an intentional change means
|
||
not wasting time trying to “fix” it, knowing all the details means
|
||
solving the complete issue and not just part of it, and it minimizes the
|
||
risk of introducing new bugs due to not having the complete picture.
|
||
|
||
Tasks
|
||
-----
|
||
|
||
Listed below are basic instructions and descriptions of different triage
|
||
tasks. When relevant these sections link to more detailed documentation
|
||
on these tasks. For more detailed instructions on the triage process in
|
||
general, please see :ref:`doc_bug_triage_overview`.
|
||
|
||
Confirming report details
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
The most basic step of triage is to make sure an issue report is filled
|
||
in properly. For details on what a report should contain please see :ref:`doc_bug_triage_overview`.
|
||
|
||
Identifying duplicates
|
||
~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Duplicate reports add a lot of clutter to the tracker, and critical
|
||
details reported on one report might not be present on others.
|
||
Identifying duplicate issues is very helpful to ensure everything is
|
||
tracked in one place. This can be difficult due to different wording,
|
||
but using tags can help narrow things down, make sure to also look at
|
||
the pinned issues at the top of the issue page in case the author missed
|
||
these.
|
||
|
||
Another tool that can help identifying duplicates are the team trackers,
|
||
for a list of these see :ref:`doc_areas`.
|
||
|
||
|
||
Testing bugs
|
||
~~~~~~~~~~~~
|
||
|
||
Testing bugs is a critical part of bug triage. Even just confirming that
|
||
a bug occurs is useful. Any information here is helpful, not being able
|
||
to reproduce a bug with the provided steps or MRP adds information about
|
||
what might be going on.
|
||
|
||
If you’re unable to reproduce the bug it could mean that the steps are
|
||
incomplete, or that the MRP is incorrect. In this case you might need to
|
||
ask the author for further details or ask them to create an MRP.
|
||
|
||
|
||
Creating MRPs
|
||
~~~~~~~~~~~~~
|
||
|
||
If you are able to reproduce a bug, but there is no attached MRP, you
|
||
can help by creating one. This is especially important if the steps are
|
||
more complex, or if the issue requires specific content, like a 3D model
|
||
or a texture. Having an MRP is very useful for the process of solving
|
||
issues and testing solutions, and not having to create the conditions
|
||
again streamlines this process.
|
||
|
||
Bisecting regressions
|
||
~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Figuring out when a particular bug occurred can greatly help fixing the
|
||
issue, or at least pointing to what might have caused it. Knowing when a
|
||
bug occurred also helps with deciding if a fix for a bug should be
|
||
cherry-picked to a previous version. When a bug is reproducible in a
|
||
current release but not in a previous one (i.e. a feature broke), we
|
||
call it a regression.
|
||
|
||
Bisecting can be done at multiple levels, the basic level is checking
|
||
if, for example, a bug that was confirmed on ``4.4`` is also
|
||
reproducible on ``4.3``. Next you can test development releases, such as
|
||
``4.4.beta1``, these can be found in the `Godot archive <https://godotengine.org/download/archive/>`__.
|
||
Once the specific development release has been identified you can go one step
|
||
further and :ref:`bisect <doc_bisecting_regressions>` the regression.
|
||
|
||
Make sure to announce the fact that you are bisecting a bug on the issue
|
||
report to make sure no one else starts bisecting it as well, as
|
||
bisecting can take some time.
|
||
|
||
Testing confirmed bugs with other environments
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Some bugs may have platform-specific components which may or may not be
|
||
apparent in the initial report. Notably issues that relate to areas like
|
||
rendering, windowing, input, audio, file I/O, or buildsystem - or
|
||
outright crash reports - can often be platform specific. If you have a
|
||
different setup from the bug reporter (operating system, GPU, etc.) and
|
||
the issue can reasonably be expected to involve platform-specific
|
||
components, it can be very useful to test the bug with your setup.
|
||
Testing the bug and reporting if you can reproduce it, or if you can’t,
|
||
adds important information that can help identifying the cause of the
|
||
bug, and making sure that contributors know how to reproduce it. This
|
||
applies especially if someone reports that they can’t reproduce the bug
|
||
on Windows but you are able to do so on macOS for example.
|
||
|
||
Here extra details like your graphics driver version, different hardware
|
||
like a specific sound card or similar can also be relevant.
|
||
|
||
Bringing bugs to the attention of maintainers
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
In cases where a report might have gone unnoticed by maintainers, for
|
||
example when a report has been confirmed but nothing has happened for a
|
||
long time (and you can reproduce it too), linking the issue in the
|
||
team’s RC channel can help bringing attention to the issue.
|
||
|
||
For more information see :ref:`doc_areas`, you can also
|
||
mention it in the `#bugsquad <https://chat.godotengine.org/channel/bugsquad>`__
|
||
channel if it needs more attention by triagers. For editor related bugs you can
|
||
mention it in the `#editor <https://chat.godotengine.org/channel/editor>`__ channel.
|