How to report bugs
Is it a security problem? Then this is not the page you are looking for. Do not open a public issue: it leaves the problem in plain sight of anyone while there is still no fix. It goes through the private report, explained in Security .
Before reporting#
Before reporting a bug, check whether it has already been reported:
- Visit Vasak Desktop GitHub Issues
- Use the search to find similar problems
- If you find a similar issue, add a comment with your information
Information needed for a good report#
A good bug report should include:
Description of the problem#
- What you were trying to do when the error occurred
- What you expected to happen
- What actually happened
- Can it be reproduced? (Yes/No/Sometimes)
System information#
| |
Steps to reproduce#
List the exact steps to reproduce the error:
| |
Relevant logs#
The messages are copied from the System Monitor, on the Logs screen (see Errors and logs in the monitor ):
- Open System Monitor → Logs.
- In Application leave The whole ecosystem and turn on Errors only.
- Reproduce the error and copy the messages from that moment, with the time.
If the desktop does not start, the same messages come out of the journal with
journalctl, as told in
The desktop does not start
. And if the
failure is in the desktop itself, its file for the day carries more detail:
~/.local/share/vasak-desktop/logs/vasak-desktop-YYYY-MM-DD.log.
Useful attachments#
If relevant, include:
- Screenshot - Shows the visual state of the error
- Video - If it is hard to reproduce in text
- Configuration file - If the error is related to the configuration
1cat ~/.config/vasak/vasak.conf
Report template#
Use this template when creating an issue:
| |
Creating an issue on GitHub#
Step 1: Gather your information#
| |
Step 2: Go to GitHub#
- Open https://github.com/Vasak-OS/vasak-desktop/issues/new
- Click “New Issue”
- Select “Bug Report” (if there are templates)
- Fill in the information
Step 3: Provide context#
Clear title: do not use “Error”, “Bug” or “It doesn’t work”
- ❌ Bad: “Error with the panel”
- ✅ Good: “Panel disappears when an external monitor is connected”
Detailed description: the more detail, the easier it is to fix
Logs: paste the relevant logs between triple backticks
Crashes#
If the application closes unexpectedly:
Capture the core dump#
| |
Gather debug information#
The desktop’s file for the day already carries the detail of the crash: reproduce the
failure and attach ~/.local/share/vasak-desktop/logs/vasak-desktop-YYYY-MM-DD.log together
with the output of coredumpctl info. The messages from the other applications are copied
from System Monitor → Logs.
Attach to the report#
- The complete log file
- The output of
coredumpctl info - System information
Hardware/peripheral errors#
If the error is related to:
Bluetooth#
| |
Audio (PipeWire)#
| |
Network/WiFi#
| |
Following up on the report#
After reporting:
- Answer questions - Developers may ask for more information
- Try solutions - If they suggest one, try it and report the result
- Check on new versions - The bug may already be fixed in the next version
- Close it if it is resolved - When it is fixed, you can close the issue
Tips for better reports#
✅ Do:
- Be specific and detailed
- Include relevant logs
- Be courteous and respectful
- Update with new information
- Test on new versions
❌ Do not:
- Report “it doesn’t work” with no details
- Include 10,000 lines of unfiltered logs
- Be rude or demanding
- Report the same bug several times
- Completely change the subject of the issue
Alternative reporting channels#
- GitHub Issues: https://github.com/Vasak-OS/vasak-desktop/issues
- Vasak OS forum: Not yet available
- Telegram: https://t.me/VasakOS
- Discord: Not yet available
Contact information#
For critical security bugs, contact:
- Security email: [email protected]
- Do not open a public issue for security vulnerabilities