Triaging

This page explains the triage process for issues and merge requests. It's written for pmaports and pmbootstrap but also applies to other postmarketOS maintained repositories.
== Triaging process ==
For triaging it is important to keep in mind that the person reporting might not be a native English speaker and might also be not familiar with text formatting in GitLabs editor.
We use labels as described below for categorizing and organizing issues.
Ideally for each of the items listed one label is assigned.
# bug/support/feature
# release
# device/device-category
# UI
# sub-system
Note: Items 2-5 are mostly for bug/support cases, ideas/features could get label as matching.
For bug/support issues a analysis with a modified 5W2H schema can be applied, our default issue-template does already ask questions in a similar fashion.
 Troubleshooting with 5W2H
Question 	In the pmOS-context 	comment / example for label
What 	Title of the issue 	Bug report or idea/discussion
Where 	Which device-(category), UI, release 	
When 	During installation, during boot, suddenly 	
Who 	Issue creator, but could also be a reference for others having same problem	no label needed
Why 	What could have triggered the problem 	could point to the subsystem affected, e.g.
How often 	Is this a continuous problem or only sporadic? 	
How to reproduce	 	for confirming the problem
=== Handling of new issues ===
Ideally the reviewer of the new issue tried to assign as many of the of the labels as mentioned above.
Sometimes details are needed, please use comments on the issue to ask for the required information.
In this case please also change the status to 
==== Reworking the issue ====
If the body of the issue contains text copied from a shell without source tags, please edit the issue text for better readability (if access rights in gitlab are sufficient).
Also it could happen that the title of the issue or the description is not clear, in this case please carefully improve the wording. (This of course also applies to the case that the issue contains foul language or similar.)
==== Moving of issues ====
It happens sometimes, that issues are created in the wrong repository. Especially device troubles during installation with pmboostrap sometimes are opened in pmboostrap repo. Gitlab rights depending issues can be moved. If you should not have the correct rights in gitlab, please comment on the issue and/or ping a CC or TC in the chats.
=== Examples ===
# Improvement idea/discussion: these type should be labels with 
## 
## and other labels like if it is a ci-related idea
# problem/bug: ideally any issue of this type should like to have labels for:
## device/device-classification 
## release 
## UI 
## subsystem 
## status 
== Labels for issues ==
==== Initial status and type ====
New issues get and are also given one of:
* - the issue is a well defined bug report
* - the issue is a question or support request, not a bug
* - the issue describes a missing feature
==== Device category ====
If the issue affects devices, a device-category label for the highest affected device category is added.
* - affects at least one device in the main category
* - affects at least one device in the community category
* - affects at least one device in the testing category
For devices in main and community categories, we also have one issue label per device, for example . These get added as well.
==== Additional categories ====
Some topics are important enough they have their own categories so that people can monitor them specifically. These include:
* - Issues related to accessibility.
* - Issues related to audio.
* - Issues related to boot-loaders.
* - Issues related to camera.
* - Issues related to ChromeOS hard- & software.
* - Issues related to the continuous integration (CI) testing infrastructure.
* - Issues related to initramfs
* - Issues related to satellite navigation (GPS, Beidu, Gallileo...).
* - Issues related to graphics.
* - Issues related to immutability.
* - Issues related to initramfs.
* - Issues related to kernel-config.
* - Issues related to Bluetooth connectivity.
* - Issues related to mobile connectivity (Data & Voice).
* - Issues related to wireless network connectivity.
* - Issues related to security.
* - Issues related to sensors (except camera).
* - Issues related to systemd.
* - Issues related to Waydroid.
=== Status change ===
During the lifetime of the issue, the status may change:
* - issue has been confirmed (bug reproduced or it has been agreed upon implementing a feature request)
* - issue is blocked because the reporter needs to provide more information
* - the bug report describes intended behaviour or for some reason we won't fix this
* - this issue describes a bug in an upstream project.
* - this is not a valid issue
* - this is a duplicate of an existing issue.
* - the issue has been fixed!
==== Upstream issue ====
If the issue reported is an upstream bug, it doesn't always make sense to close it immediately. If having a local issue to track it adds value, for example if this is a very important bug and we need to know when it is fixed in postmarketOS, is applied but the issue is kept open. Once it's fixed upstream AND fixed in postmarketOS, the gets applied and the issue gets closed.
On the other hand, if it it doesn't add value to keep the bug around in postmarketOS, it should be closed after applying .
In any case, a link to the upstream issue should be added to the issue - preferably edited into the top post so it's immediately visible when reading the issue.
== Merge Requests ==
Similarly to issues, MRs should be assigned of either or . As well as appropriate device and .
 labels only necessary for MRs that are closed instead of merged, only makes sense here.
== See also ==
* https://gitlab.postmarketos.org/postmarketOS/pmaports/-/labels
* https://gitlab.postmarketos.org/groups/postmarketOS/-/labels
Category:Admin