Bug Issue Reporting Guidelines

Bug reports and feedback are essential to 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 debug information from the extension, and what kinds of reports are accepted.

Before opening an issue

1. Make sure you are 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.
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. 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.
• Debug logs. See 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 debug logs

The extension keeps an internal log buffer. With Debug Mode enabled, that buffer captures the relevant events while the problem happens, so the trace can be attached to your report.

1. Open the extension preferences. From a terminal:

   gnome-extensions prefs BetterTrayIcons@nexaknight.com
   

   From the GNOME Extensions app, click the cogwheel next to Better Tray Icons.
2. Go to the General tab and scroll to the Advanced group at the bottom.
3. Switch Debug Mode on. The row turns red to confirm that detailed logging is active.
4. Reproduce the bug exactly as it happens. Click the icons, open the popup, trigger the action that breaks. Every step you perform from this point on ends up in the log buffer.
5. Click the copy icon next to the Debug Mode switch, labelled Copy Logs to Clipboard. A toast confirms with Logs copied to clipboard.
6. Paste the clipboard content into your issue inside a fenced code block (three backticks before and after the log lines). The code block keeps the formatting readable and stops GitHub from interpreting the log content as markdown.
7. If the log is very long, click Save Logs to File instead of copying. Pick any location, then attach the saved .log or .txt file to your issue. GitHub accepts file attachments by drag-and-drop into the comment box, or via the paperclip icon at the bottom of the editor.
8. Switch Debug Mode off once you are done. Leaving it on writes a lot of data to the system journal and slightly slows down the shell.

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 do not 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


### Debug logs
<paste the clipboard content here inside a code block, or attach the saved 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 are not 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, for example 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. See the README 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 is 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.