Issues.rst

.. _issues:

Report an Issue
===============

Issues for the Librem 5 project are kept track of in our `GitLab instance <https://source.puri.sm/search?group_id=33&scope=issues>`_. This page aims to help you navigate where to find already existing issues and file new ones. 

For example if you were looking for an issue relating to a weather application, you can go search for "weather" and you should find an issue that says "Need to port GNOME weather". If your search returns nothing, then no wishlist issue has been filed under `apps issues <https://source.puri.sm/Librem5/Apps_Issues/issues>`_ and you should file a wishlist issue (using the wishlist issue template). 

Some common scenarios would be:

* You have a problem to report in the *operating system*
* You have a problem to report in a *specific application*

.. note:: Remember that to avoid duplicate issues, you should *always* search for the existing issue first before filing a new one.

If you search for an issue and do not find an existing issue, then go ahead and open a new one.

Issue in the Operating System
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Issues for the **base OS** will be tracked in `OS_issues <https://source.puri.sm/Librem5/OS_issues/issues>`_. Your issue would go here if you have a concern with something that is *not application specific*.

Some examples would be:

* boot issues
* kernel crashes
* trouble installing packages

Issue in Librem 5 Application
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

First, you will need to identify what type of application your issue is related to. There are two types of Librem 5 applications:

1. Base applications that the Librem 5 team has added and would have its own repository.
2. Other applications

Base Applications
-----------------

Issues for **base applications** should be filed under the issues for that repository.

An example of a **base application** would be:

* If you have an issue with the `chatty application <https://source.puri.sm/Librem5/chatty>`_ then you would file your issue under the `chatty issues <https://source.puri.sm/Librem5/chatty/issues>`_.

For a list of these base applications, see `Apps_issues README <https://source.puri.sm/Librem5/Apps_Issues/blob/master/README.md>`_. You can also search `the existing GitLab repositories <https://source.puri.sm/Librem5/>`_.

Other Applications
------------------

Issues for **other applications** will be tracked in `Apps_issues <https://source.puri.sm/Librem5/Apps_Issues/issues>`_. Your issue would go here if you have a concern with a phone application for which there is no *base application* corresponding repository.

Some examples of *other application* issues would be:

* You have an issue with certain application that has been added for the phone and there is not a specific GitLab repository for said application to file issues under. 
* You wish there to be a certain application available for the phone and want to file an issue about it in hopes someone creates it. Please follow the wishlist template provided in the Apps_issues repo when filing out these types of wishlist item issues.

If you would like to work on any of these issues, please see our :ref:`working on issues <working-on-issues>` section.

Using Labels
------------

There are global labels that are available to all projects and there are project-specific labels. Here is some info on the available labels and their suggested usage.

.. note:: Librem 5 issues will be closed only when the fix is being shipped in a recent image build.

Global Labels
^^^^^^^^^^^^^

To gauge how serious the issue is, we've provided severity labels that correspond to the same `bug severities used by Debian <https://www.debian.org/Bugs/Developer#severities>`_: 

* **critical** - makes unrelated software on the system (or the whole system) break, or causes serious data loss, or introduces a security hole on systems where you install the package
* **grave** - makes the package in question unusable or mostly so, or causes data loss, or introduces a security hole allowing access to the accounts of users who use the package
* **serious** - the package has an issue with licensing (non-free), privacy, or security, or (in the package maintainer's or release manager's opinion) makes the package unsuitable for release
* **important** - a bug which has a major effect on the usability of a package, without rendering it completely unusable to everyone
* **normal** - the default value, applicable to most bugs
* **minor** - a problem which doesn't affect the package's usefulness, and is presumably trivial to fix
* **wishlist** - for any feature request, and also for any bugs that are very difficult to fix due to major design considerations

Please add an appropriate severity label to the issue you are filing.

There are also some other optional labels that are globally available to all projects:

* **needsupstreamwork** - the issue has an upstream component that will need to be fixed
* **fixedupstream** - the issue has been fixed upstream but the fix has not trickled down to the Librem 5 project yet
* **helpwanted** - anyone can sign up to work on this issue
* **needsdesign** - the issue is a good idea but the implementation and next steps needs to be investigated and identified
* **wontfix** - the issue will not be resolved and a reason should be in the comments

Please add any of the optional labels that make sense for the issue being filed.

Project Labels
^^^^^^^^^^^^^^

Some projects have some project-specific labels defined, most notably the `Apps_issues <https://source.puri.sm/Librem5/Apps_Issues/issues>`_ repository. Because the Apps_issues repo contains issues about many different projects that do not have their own repositories, there are labels created to identify each application. This allows issues that all relate to say a weather application to be grouped under the "weather" label.

Please add any project specific labels that make sense.