How to file issues

While we try to help people as much as we can, we prefer that issues are triaged through GitHub so they can be tracked and labelled properly. Here’s a quick guide.

If you’ve been redirected here it means one of us wants to track this in GitHub. Don’t worry, you didn’t mess up, we just need to put it in the system. This forum and GitHub support markdown formatting, so usually it’s just a matter of copying and pasting it into GitHub.

Read the GitHub Quickstart

Quick tips

  • One issue per problem please!
  • Try to fill out the form as best you can
  • Remember we’re enthusiasts with jobs, sometimes it might take a while, especially if it’s a nice-to-have and not a critical issue

Setting Expectations

We’re Linux geeks, but most of us come from an ops background and not deep technical distribution work. More hands on deck are always welcome!

  • Kernel issues like freezes and crashes can be tough to diagnose, we’ll do our best
  • There’s not much we can do in certain situations, if you’re using an Nvidia closed source driver sometimes you might get an issue that is completely out of our control - the gift that keeps on giving!
  • Check Fedora’s How to File a Bug docs - please be respectful when reporting issues to Fedora - it doesn’t hurt to rule out a Universal Blue issue before reporting something for Fedora. Our intended mission is to help Fedora as efficiently as possible.
  • Some days the t-rex just gets you - If you’re treading off the beaten path it’s entirely possible that you are the first person trying it. Thanks for volunteering by filing issues and submitting documentation. :smile:

Finding where to file an issue

Depending on where you find an issue, it might need to go in a certain repository. Don’t worry if you mess this up, we can move them, here’s a quick guide to save you some time.

Aurora, Bazzite, and Bluefin

If you have a Framework laptop file an issue in one of these, depending on what you’re using.

Universal Blue Repositories

  • ublue-os/config - for just commands, udev rules, and service units. Things in this repo end up on every Universal Blue image.

  • ublue-os/akmods - extra kernel modules. Usually for that awful piece of hardware that doesn’t have inkernel driver support. :smile:

  • ublue-os/main - for base images. Issues about codecs, and general issues. This is usually our catch all repo and will have issues relating to things that affect the entire project. These don’t integrate akmods so no weird hardware things don’t go in here.

  • ublue-os/hwe - hwe means “hardware enablement”. If you have an issue with Nvidia, Asus, or Surface devices, file it in this repo.

  • ublue-os/toolboxes - Anything related to our distroboxes and associated podman quadlets.

For everything else check out the list of repositories.

(Learn something useful? This is a wiki page, feel free to submit an edit or just post in the thread and we can integrate the lessons you’ve learned!)