Bug Issue Reporting Guidelines

Bug reports and feedback are what keep Better Tray Icons stable across different GNOME versions and operating systems. A clear, complete report saves hours of back and forth and helps fix the problem faster. This page explains what to include, how to collect the logs that help with diagnosis, and what kinds of reports are accepted.

Before opening an issue

1. Make sure you're running the latest version of Better Tray Icons. The version is shown on the About tab of the preferences window, and the latest release is listed on the [GNOME Extensions website](https://extensions.gnome.org/).
2. Search the existing issues, including closed ones. Your problem may already be tracked, scheduled or solved.
3. Check the README for known conflicts. Other tray or AppIndicator extensions claim the same DBus names and will cause symptoms that look like bugs in this extension.
4. If you can, restart the shell once before reproducing the problem. Log out of your GNOME session and back in. A clean session rules out leftover state from older extension versions.

What every report needs

A useful report contains all of the following.

• A short, descriptive title. For example, Steam tray icon disappears after closing Discord.
• System information. GNOME Shell version (gnome-shell --version) and the distribution and its version (cat /etc/os-release | grep PRETTY_NAME).
• Extension version. Shown on the About tab of the preferences window.
• Affected application. The tray icon source matters, because SNI implementations differ per app. Mention the exact application and its version.
• Steps to reproduce. A numbered list, written so somebody else can follow it without prior context.
• Expected behavior. What you thought would happen.
• Actual behavior. What actually happened.
• Logs. Have a look at the next section.
• Screenshots or short screen recordings. Optional but very helpful for layout, styling or animation bugs. The more specific these points are, the faster the bug can be triaged and fixed.

Collecting logs

GNOME Shell writes errors and warnings from the extension to the system journal. journalctl is the way to retrieve them.

For a clean trace, start a capture in a terminal first, then reproduce the bug:

journalctl --user -f -o cat /usr/bin/gnome-shell | tee shell.log

Switch back to your GNOME session, perform the exact steps that trigger the bug, then return to the terminal and press Ctrl+C to stop. The captured output is in shell.log in the current directory.

If you've already reproduced the bug, grab the recent entries in one go instead:

journalctl --user --since "10 minutes ago" /usr/bin/gnome-shell > shell.log

Paste the relevant lines into your issue inside a fenced code block (three backticks before and after), or drag the shell.log file into the GitHub comment box to attach it. GitHub also accepts file attachments through the paperclip icon at the bottom of the editor.

Redact anything sensitive before submitting, like usernames in file paths or window titles that contain private content.

Without these logs, most non-trivial bugs cannot be traced back to their root cause, so this step is the single most important part of the report.

Bug report template

Copy the block below into the issue body and fill in the fields. Sections that don't apply can stay empty.

### Summary
<one or two sentences describing the problem>

### Environment
- GNOME Shell version:
- Distribution:
- Extension version:
- Affected application(s):

### Steps to reproduce
1.
2.
3.
### Expected behavior

### Actual behavior

### Logs
<paste the relevant journalctl output here inside a code block, or attach the saved shell.log file>

### Screenshots
<optional>

### Additional context
<other tray-related extensions installed, recent system updates, anything that might be related>

Labels

GitHub uses labels to filter and prioritise issues. If the issue form allows it, apply the label that best describes the report so it can be triaged faster.

• bug for unexpected or broken behavior.
• enhancement for new feature requests or improvements to existing ones.
• documentation for issues that only concern the README or the wiki.
• question for clarification requests that aren't bug reports.
• regression when the behavior worked in an earlier release and stopped working after an update.
• experimental when the report concerns a feature that is flagged as experimental in the preferences, like drag and drop on long press.
• translation for issues that only concern an existing translation file. Maintainers add or adjust labels during triage. Status labels like duplicate, invalid or wontfix are set by maintainers when the report is closed.

What is not accepted

The following reports will be closed without further investigation.

• Reports without a clear description of the problem or without reproduction steps.
• Reports for unsupported GNOME Shell versions. Have a look at the shell-version key in metadata.json for the supported range.
• Reports about behavior that is documented as known or experimental.
• Reports that contain offensive, insulting, defamatory, harassing or otherwise harmful language.
• Reports that include personal data of third parties, secrets, credentials or other private information. Redact log lines before pasting them if necessary.
• Reports that violate applicable laws.

After opening the issue

• Stay reachable for follow-up questions. Most bugs need at least one round of clarification before a fix is possible.
• If the problem resolves itself before a maintainer responds, leave a short comment explaining what changed and close the issue.
• Progress updates appear in the issue thread itself. There's no separate notification channel. Thanks for taking the time to file the report. Good bug reports are what keep an open source project moving forward.