Jump to content

How to report issues

From postmarketOS Wiki

This page covers the process of reporting an issue.

Prerequisites

  • Not using AI to submit the issue. This is according to the Code of Conduct, including the the AI Policy which bans the submission of contributions made in full or in part using generative AI, which includes submitting issues.
  • Checking the list of open issues in postmarketOS repositories.
  • If it occurred on the postmarketOS edge branch, check known issues on postmarketos.org/edge.
  • Updating the system to make sure the issue hasn't been fixed in a recent update. Note that some updates (such as kernel updates) require a reboot to be applied.
  • Optionally asking about the issue on Matrix/IRC. Someone might be able to resolve your issue there; otherwise, the helpful folks there can also help you decide where to file the bug report if you're not sure.
Hint If you have some time on your hands, you can try troubleshooting the issue first, because it can be particularly helpful when reporting an issue. See Troubleshooting for more info.

Where to report the issue

Because issues differ in scope and nature, it may be reported in our own repositories or externally. External sources are more commonly known as upstream. By reporting it in the right place, we keep everything organized for our developers, and help the other projects that are incorporated into pmOS. When in doubt, ask in Matrix/IRC.

Device-specific issues

Devices not booting, graphical glitches, crashes and general instability, driver bugs and non-working components (apart from those explicitly mentioned as "not working" on your device's wiki page) should be reported in the pmaports repository.

Issues with applications and interfaces

Note If an app has missing dependencies, or you can't install it due to conflicts, or seems to be missing some files, it might be a packaging issue instead.

When encountering issues with an application or interface, it's likely an issue beyond our scope and governance. In this case, it should be reported to the upstream repositories.

  • Phosh: See Phosh repositories; use the issue trackers in the appropriate repository.
    • GNOME apps: Click the "Report an Issue" button in the About menu - this should take you to the app's repository.
      • If there is no such button, find the repository for your app on gitlab.gnome.org (most apps are in the GNOME and World groups; note that using the regular GitLab search will also show forks!).
  • Plasma Mobile/KDE apps: See Plasma Mobile Issue Tracking.
  • Sxmo: sxmo-tickets.
  • Other projects: find the project website (apk info <package-name> can point you in the right direction).
    • Searching on GitHub or GitLab might help you find the project's repository and its bug tracker.

Issues during installation

It depends on the exact way you're installing postmarketOS, and which you're having trouble with:

Packaging issues

Native packages on postmarketOS come from 2 sources: its own repository, and from upstream Alpine Linux. While most come from Alpine Linux, here's how to figure it out for a specific package:

Then report it to the appropriate repository:

If you encounter a package-related issue in pmbootstrap, report it to the pmbootstrap issue tracker.

How to format the issue

When creating an issue in the pmaports repository, the formatting is created automatically due to a template. But not all repositories have templates; in such cases, there should be at least the following information:

  • The version you're using (such as v26.06, edge, etc).
  • The codename of the device you're using and its CPU architecture.
    • This information is listed on the device's wiki page.
  • The environment you're using, such as Phosh, Plasma Mobile, Sxmo, etc. If in doubt, check interfaces, which has some screenshots that should help you identify your interface.
  • If your report is specifically about an application, mention the application's version.
    • The app version can often be found by finding an About button.
Hint For terminal apps, run <command> -v or command --version. For packages in general, check apk info --installed <package-name>.
  • If the issue involves something breaking, crashing, behaving inconsistently etc (also called a bug), then adding steps to reproduce and logs is really helpful for the developers.

Steps to reproduce

Involves listing steps someone else can take to (hopefully) reproduce the issue, from the beginning. For touch or mouse interactions, make sure to describe them in detail in order to avoid confusion. Optionally, if you have some time on your hands, test the steps yourself and see if you can reproduce it first.

Logs

Involves adding relevant logs for the affected application by running it from the terminal and copying the output. On Xorg-based interfaces, you may find some logs for launched apps in ~/.xsession-errors.

Hint The repository you're submitting an issue to might have an issue template that can contain other useful tips on how to get relevant log output to provide with your issue.

Other ways to get relevant logs:

Additional help

If you get stuck or need assistance, there are Matrix/IRC chats for general support questions.

If something on this page is unclear, let us know by adding a work item to the wiki project describing what needs additional clarification. The wiki aims to be for all postmarketOS users, from from novices to experienced ones. See the wiki style guide for more info.

See also

Retrieved from "https://wiki.postmarketos.org/index.php?title=How_to_report_issues&oldid=104802"