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 typefeature
Where	Which device-(category), UI, release	device-nokia-n900
When	During installation, during boot, suddenly	porting
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. graphics
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 statusneedmoreinfo

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
1. typefeature
2. and other labels like ci if it is a ci-related idea
problem/bug: ideally any issue of this type should like to have labels for:
1. device/device-classification device-nokia-n900
2. release v24.06
3. UI UIphosh
4. subsystem graphics
5. status statusnotoutbug

Labels for issues

Initial status and type

New issues get statusreported and are also given one of:

typebug - the issue is a well defined bug report
typesupport - the issue is a question or support request, not a bug
typefeature - 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.

device-categorymain - affects at least one device in the main category
device-categorycommunity - affects at least one device in the community category
device-categorytesting - 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 device-nokia-n900. 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:

a11y - Issues related to accessibility.
audio - Issues related to audio.
camera - Issues related to camera.
chromeos - Issues related to ChromeOS hard- & software.
ci - Issues related to the continuous integration (CI) testing infrastructure.
gnss - Issues related to satelite navigation (GPS, Beidu, Gallileo...).
graphics - Issues related to graphics.
immutability - Issues related to immutability.
initramfs - Issues related to initramfs.
kernel-config - Issues related to kernel-config.
network::bluetooth - Issues related to Bluetooth connectivity.
network::mobile - Issues related to mobile connectivity (Data & Voice).
network::wlan - Issues related to wireless network connectivity.
security - Issues related to security.
systemd - Issues related to systemd.
Waydroid - Issues related to Waydroid.

Status change

During the lifetime of the issue, the status may change:

statusconfirmed - issue has been confirmed (bug reproduced or it has been agreed upon implementing a feature request)
statusneedmoreinfo - issue is blocked because the reporter needs to provide more information
statuswontfix - the bug report describes intended behaviour or for some reason we won't fix this
statusnotourbug - this issue describes a bug in an upstream project.
statusinvalid - this is not a valid issue
statusduplicate - this is a duplicate of an existing issue.
statusfixed - 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, statusnotourbug is applied but the issue is kept open. Once it's fixed upstream AND fixed in postmarketOS, the statusfixed 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 statusnotourbug.

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 type of either typefix or typefeature. As well as appropriate device and device-category.

status labels only necessary for MRs that are closed instead of merged, only statusinvalid makes sense here.