How to report issues
This guide will walk you through the process of reporting an issue.
Before reporting an issue
- Check if there isn't already an open issue ticket similar to yours; see all issues in postmarketOS repositories.
- Check the Troubleshooting page and the subpages linked there.
- Ask in Matrix/IRC; see Category:Community for a list of help channels. 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.
- If you're using postmarketOS edge, check postmarketos.org/edge, which has a list of known issues on the edge branch.
- Try updating your system to make sure the issue hasn't been fixed in a recent update.
Where to report the issue
Depending on the exact scope and nature of the issue, it may be reported in various places.
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 apps or interfaces/shells
It's likely that the issue you're having isn't exclusive to postmarketOS - in this case, it should be reported to the upstream repositories.
- Phosh: See Phosh repositories; use the issue trackers in the appropriate repository.
- GNOME/GNOME apps: 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).
Issues during installation
This depends on the exact way you're installing postmarketOS, and which step you're having trouble with:
- If you find an issue when using pmbootstrap, report it to the pmbootstrap issue tracker.
- If you find an issue with the on-device installer, report it to the postmarketos-ondev issue tracker.
- If you find an issue with the Android recovery installer, report it to the postmarketos-android-recovery-installer issue tracker.
- If your issue is device-specific, such as a flash method failing or the device package being broken, report it to the pmaports repository.
Packages, distro-specific issues
|This section refers specifically to the app packages, not the apps themselves; for apps, see the #Issues with apps or interfaces/shells section.|
If an app has missing dependencies, or you can't install it due to conflicts, or seems to be missing some files, you might be dealing with a package issue.
postmarketOS is based on Alpine Linux; as such, before you report a bug, you should first know where the package for the app you're having trouble with is located:
- All device-specific packages (
device-<name>-<codename>; and kernels other than
linux-rpi) are in postmarketOS repositories (pmaports).
- For other packages, search pkgs.postmarketos.org, then pkgs.alpinelinux.org.
- Note that we carry a few forks of Alpine packages; most of them can be found in the temp directory in pmaports.
If you encounter a package-related issue in pmbootstrap, report it to the pmbootstrap issue tracker.
Writing a good bug report
The pmaports repository has a template for issues; in general, no matter the project, you should mention the following information:
- The version of postmarketOS you're using (i.e. v21.12, edge, etc.);
- The device you're using and its architecture (you can find this information on the device's wiki page);
- The UI you're using (Phosh, Plasma Mobile, Sxmo, etc. - if in doubt, check Interfaces, which has some screenshots that should help you identify your UI);
- If your report is related to an application, provide the application's version (for GUI apps - find an About dialog, for CLI apps - run
command --version; for packages in general - check
apk info --installed <package-name>);
- Detailed instructions on how to reproduce the bug, as well as any relevant logs (for apps - try running the affected app from the terminal and see if there's any output there).