Differential D13647 Diff 36431 contributors_manual/untranslatable_pages/triaging_bugs.rst

Changeset View

Standalone View

contributors_manual/untranslatable_pages/triaging_bugs.rst

This file was added.

		1		.. meta::
		2		:description:
		3		Manual for bug triagers
		4
		5		.. metadata-placeholder
		6
		7		:authors: - Boudewijn Rempt <boud@valdyas.org
		8
		9		:license: GNU free documentation license 1.3 or later.
		10
		11		.. _triaging_bugs:
		12
		13		=============
		14		Triaging Bugs
		15		=============
		16
		17		There are over 1000 bugs and 350 wishes reported against Krita per year, and that number is rising.
		18		The Krita developers cannot handle that stream on their own! Please consider helping out by triaging bugs. This document gives some simple guidelines to get started, and some common cases that can often be answered with a standard text.
		19
		20		For more details, see also https://community.kde.org/Guidelines_and_HOWTOs/Bug_triaging
		21
		22		Status flow
		23		-----------
		24		A bug begins as UNCONFIRMED. When triaging, only UNCONFIRMED bugs are still relevant.
		25
		26		Platform
		27		~~~~~~~~
		28
		29		If the user has not entered the Platform correctly (i.e., it is "unspecified/Linux"), then ask which platform they are using. Mark the bug as NEEDDINFO/WAITINFORINFO.
		30
		31		Text to paste:
		32
		33		* "Please indicate your operating system correctly. For Linux, select the distribution, appimage or compiled from sources and Linux, for Windows, select MS Windows/MS Windows, for OSX or macOS, select macports, disk images or homebrew and OSX."
		34
		35		If the user has selected Windows CE for platform, set it to MS Windows without asking them.
		36
		37		Version
		38		~~~~~~~
		39		If the user has not entered the version (i.e., the version is unspecified), ask them for the version and mark the bug as NEEDDINFO/WAITINFORINFO.
		40
		41		Text to paste:
		42
		43		* "Please select the version of Krita you are using. You can find the version in Help/About Krita."
		44
		45
		46		Can Reproduce
		47		~~~~~~~~~~~~~
		48		*If you can reproduce the bug, add a comment indicating you can reproduce it, maybe with clearer steps to reproduce and anything pertinent that you observed. If you have a backtrace, also add it. Set the bug status to CONFIRMED and add the 'triaged' keyword to the keywords.
		49		*If you can reproduce the bug, and want to go the extra mile, use an older version of Krita to see whether you could reproduce it there as well. If you couldn't, it's a _regression_, so add the regression keyword to the keywords and mark which version of Krita the latest was that did not have the bug.
		50
		51		Cannot Reproduce
		52		~~~~~~~~~~~~~~~~
		53		*If you cannot reproduce, the user either has not given enough information or the bug is specific to their system.
		54
		55		*If there is not enough information, ask for more information. Depending on the report, the steps to reproduce might need to be described more clearly and/or a screenshot, a screen recording or the original files might be necessary. Set text (ask for what you think is needed):
		56		**"I am sorry, I cannot reproduce your issue. Could you specify the steps to reproduce more clearly, and maybe add a screen recording/screenshot/original file"
		57		**Mark the bug as NEEDINFO/WAITINGFORINFO.
		58		*If the issue seems to be specific to the user's system, ask for the output of help/System information for bug reports as well. Set text:
		59		**"I am sorry, but I cannot reproduce the bug on my system. Please add the output of help/System Information for Bug reports as well."
		60		** Mark the bug as NEEDINFO/WAITINGFORINFO.
		61
		62		Importance
		63		~~~~~~~~~~
		64		Importance is a tool for developers, not for bug reports. It's developers and triagers who decide what the importance is. If a bug reporter complains about a change in importance, use this text:
		65
		66		* "I am sorry, but the importance field is a tool for the developers to work with. Please do not change the importance back."
		67
		68		There are the following Importances:
		69
		70		*Critical: the bug leads to immediate dataloss. Example: a saved file cannot be opened in Krita
		71		*Grave: shouldn't be used, it doesn't mean a thing
		72		*Major: it's a bug, but it's kinda important.
		73		*Crash: the bug is about a crash or an assert (1)
		74		*Normal: it's a bug
		75		*Minor: it's a bug, but it's kinda unimportant
		76		*Wish: it's a feature request
		77		*Task: not used.
		78
		79		The main difference is between Wish and the rest: Wishes are feature requests, and don't need immediate triaging. A wish bug is a bug that asks whether some functionality can be added to Krita, or complains that some functionality is missing.
		80
		81		The rest are bugs, that is, problems in Krita that can be fixed by changing Krita's code.
		82
		83		However, we also get many reports that are not bugs and not wishes: reports that are basically users asking for help because they do not understand Krita or their computer, or what a file is, or that Krita isn't the same application as Photoshop. Those reports need to be weeded out, and the status set to INVALID.
		84
		85		Guidance for using Importance
		86		~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
		87
		88		*If you encounter a bug that reports dataloss when loading a saved file, set it to critical.
		89		*If you encounter a bug that reports a crash or an assert but is not set to crash, set it to crash.
		90		*If you encounter a report that asks for functionality that is not currently present, set it to wish.
		91		*If you encounter a report that is a user request, check whether you can reply with a link to the faq (https://docs.krita.org/KritaFAQ), and maybe a canned answer, and change the status of the bug to INVALID.
		92
		93		Asserts and Crashes
		94		~~~~~~~~~~~~~~~~~~~
		95
		96		1. Crash or assert. These are different things. A crash happens when Krita spontaneously stops working _or_ hangs. An assert happens when Krita stops working because we, developers, have added some code to detect an invalid state.
		97
		98		Asserts are printed to the terminal or shown in a popup window. You can identify an assert by asking for terminal output, debugview output or by checking the backtrace, if there is one.
		99
		100		If the backtrace contains a line like
		101		'''> SAFE ASSERT (krita): "!sanityCheckPointer.isValid()" in file /tmp/nix-build-krita-4.0.0-pre2c.drv-0/krita-1b1695a/libs/ui/KisDocument.cpp, line 490'''
		102
		103		Or another mention of assert, Q_ASSERT or similar, it's an assert, not a crash.
		104
		105		Canned Answers and Recognizing Common Reports
		106		---------------------------------------------
		107
		108		We get a lot of duplicate bug reports. Sometimes it's clear that it's a duplicate, and you can mark it a such. In all cases, we want to give the reporter useful information so they can solve their problems. Of course, (almost) all solutions are also in the FAQ, but just pointing people to the FAQ is often considered impolite.
		109
		110		So, do never reply to a bug report with
		111
		112		* "Just read the FAQ."
		113
		114		It takes a bit of experience to recognize a bug from an often incomplete description. Here are a couple of common cases:
		115
		116		Cannot Save
		117		^^^^^^^^^^^
		118
		119		For instance:
		120		"I cannot save/my file doesn't get saved/it says it cannot copy the file"
		121
		122		This happens most often on Windows, if the user has got any security software installed that doesn't come with Windows. Examples are Sandboxie, Totaldefender, orothers. Mark the bug as NEEDSINFO, WAITINGFORINFO and add this text:
		123
		124		* "Are you using Windows? If so, do you have any non-standard security software installed such as Total Defender, Sandboxie or XXX? Please make an exception for Krita in the settings, or uninstall this software. Since Windows 10, it is no longer necessary to have any security software installed other than what comes with Windows."
		125
		126		If the user replies that they are using extra security software, close the bug as "RESOLVED, INVALID".
		127
		128		Broken Canvas
		129		^^^^^^^^^^^^^
		130
		131
		132		This happens on Windows. Symptoms will be: the canvas is black, the canvas stays blank, the canvas only updates when the user clicks outside the canvas. Mark the bug as a duplicate of https://bugs.kde.org/show_bug.cgi?id=360601, and add the following text:
		133
		134		* "You probably are using a Windows system with an Intel display chip. Please update to Krita 3.3.3, which enables the Direct3D (Angle) renderer by default. If you do not want to update, check https://docs.krita.org/KritaFAQ#Krita_starts_with_a_black_or_blank_canvas_and_nothing_changes_when_you_try_to_draw.2Fshows_a_black_or_blank_screen_on_my_Windows_system_with_an_Intel_GPU ."
		135
		136		My stylus has an offset
		137		^^^^^^^^^^^^^^^^^^^^^^^
		138
		139		This happens on Windows. Symptoms will be: the user reports that the stylus cursor has an offset or moves the cursor on another screen. Usually, the user will have a misconfigured multi-monitor system. Mark the bug as NEEDSINFO, WAITINGFORINFO and ask the user:
		140
		141		* "Do you have a multi-monitor setup? If so, this is a configuration issue. Please reset your tablet driver's configuration and Krita's configuration (https://docs.krita.org/en/KritaFAQ.html#resetting-krita-configuration). If you have a single-monitor setup, then please calibrate your tablet."
		142
		143		If the user checks back and tells us the problems are solved, mark the bug as RESOLVED,UPSTREAM.
		144
		145		Other tablet issues
		146		^^^^^^^^^^^^^^^^^^^
		147
		148		Often, the user will tell you that their tablet will work perfectly with another application. This is not relevant. Tell the user:
		149
		150		* "Windows tablet drivers often have special code for different applications. Whether an application works or not depends on whether the programmers have tested their driver with an application or not. Tablet issues are almost always caused by the drivers being broken."
		151
		152		Krita lags
		153		^^^^^^^^^^
		154
		155		The word "lag" is meaningless. Complaints about "lag" are not bug reports. However, we should help the complainer.
		156
		157		Mark the bug as NEEDSINFO/WAITINFORINFO and ask the user"
		158
		159		* "Have you enabled the stabilizer? Check the tool options panel for the freehand tool. Also check the other possibilities mentioned here: https://docs.krita.org/KritaFAQ#Krita_is_slow"
		160
		161		I cannot paint at all, in a particular document
		162		^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
		163
		164		The user probably created, accidentally, a tiny selection, and saved that with the document. Mark as NEEDSINFO/WAITINGFORINFO and ask them:
		165
		166		* "Do you have a selection saved with that document. Use select/deselect on your image and check whether you can paint again. If not, please attach the .kra document to this bug report or make it available."