[Debian-on-mobile-maintainers] Bug#1050762: feedbackd-device-themes: Users are not informed about existing tools from the feedbackd package

[Boud Roukema]

Package: feedbackd-device-themes
Version: 0.0.r3-1
Severity: normal

Dear Maintainer,

    * What led up to the situation?

I tried following the upstream 'feedbackd' README file and spent a lot
of time making wrong guesses about syntax and about testing the effects
of modifying the theme .json files.


    * What exactly did you do (or not do) that was effective (or
      ineffective)?


I checked for /usr/share/doc/feedbackd-device-themes and I searched
through installed versions of the two packages
(feedbackd-device-themes and feedbackd), their Debian git sources, and
their upstream sources for hints.


    * What was the outcome of this action?

I found that there is no installed documentation:

$ ls -l /usr/share/doc/feedbackd-device-themes/
total 3
-rw-r--r-- 1 root root  682 Feb  2  2023 changelog.Debian.gz
-rw-r--r-- 1 root root 1514 Dec 16  2022 copyright


I discovered from browsing sources and git histories that the debian
'feedbackd' package automatically installs several user-level programs
that the user should be informed about:


$ dpkg -L feedbackd | grep /usr/bin

/usr/bin
/usr/bin/fbcli
/usr/bin/fbd-theme-validate




    * What outcome did you expect instead?

I expected to see a useful README.Debian file that informs the
user about Debian tools that are easily made available by installing
'feedbackd':

/usr/share/doc/feedbackd-device-themes/README.Debian.gz

along with a minimal Debian-appropriate hint on customisation.


PROPOSAL:

I propose adding the following file (under GPL-3 for compatibility with
the other files):

cat > debian/feedback-device-themes.README.Debian << EOF
Tools for checking customised themes
====================================

See the upstream README file for hints on how to customise
your feedbackd themes. Example files that can be copied to,
for example, "~/.config/feedbackd/themes/custom.json"
include "/usr/share/feedbackd/themes/default.json"
from the "feedbackd" package and the theme in
"/usr/share/feedbackd/themes/" that matches your device.
You can remove the "parent-theme" parameter if you find
its role unclear.

Use the commands

   gsettings get org.sigxcpu.feedbackd theme
   gsettings set org.sigxcpu.feedbackd theme custom
   gsettings reset org.sigxcpu.feedbackd theme

to get the current theme, set to your custom theme, or reset to
the default theme.

You can use commands from the "feedbackd" package
to check the syntax of your custom.json file and
to check its effects. To check the syntax,

   fbd-theme-validate custom.json

To see the effects of your custom.json file, you will need to restart
the running "feedbackd" daemon, e.g. "killall feedbackd" and then
close and reopen a gui such as chatty that automatically restarts
"feedbackd". Then (or before you switch) you can check individual
effects:

   fbcli --event message-new-sms --profile full
   fbcli --event message-new-sms --profile quiet
   fbcli --event phone-missed-call --profile full
   fbcli --event phone-incoming-call --profile full
   fbcli --event phone-incoming-call --profile quiet
   fbcli --event phone-incoming-call --profile silent

See the man pages on fbd-theme-validate and fbcli for more
information.

[1] https://source.puri.sm/Librem5/feedbackd/README.md
EOF

-- System Information:
Debian Release: trixie/sid
   APT prefers testing
   APT policy: (500, 'testing')
Architecture: arm64 (aarch64)

Kernel: Linux 6.1-sunxi64 (SMP w/4 CPU threads)
Kernel taint flags: TAINT_CRAP, TAINT_UNSIGNED_MODULE
Locale: LANG=en_AU.UTF-8, LC_CTYPE=en_AU.UTF-8 (charmap=UTF-8), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: systemd (via /run/systemd/system)

feedbackd-device-themes depends on no packages.

Versions of packages feedbackd-device-themes recommends:
ii  feedbackd  0.2.0-2

feedbackd-device-themes suggests no packages.

-- no debconf information