Bug Reporting

Bug Reporting

Overview

The Icarus Pet Editor includes a built-in bug reporting system that submits structured issue reports directly to a private GitLab intake project. Reports can optionally include a screenshot of the editor window and copies of the user's Mounts.json save data (before and after edits) to help with debugging.

How to Report a Bug

  1. Click the 🐛 Report Bug button in the toolbar (right side, next to About)
  2. Fill out the structured form:
  3. Title (required) — a short summary of the issue
  4. What happened? — describe the problem you encountered
  5. Steps to reproduce — numbered steps to trigger the bug
  6. Expected behavior — what should have happened instead
  7. Review the optional attachment checkboxes:
  8. ☑ Include system info — auto-collects app version, OS, Python version, loaded file info
  9. ☑ Attach screenshot of editor window — captures the editor window only (not your desktop)
  10. ☑ Attach Mounts.json (before & after edits) — sends a copy of the original save file and the current edited state
  11. Click 📤 Submit Bug Report
  12. A confirmation dialog will appear with the issue number and link

What Gets Submitted

Structured Report

The bug report is formatted as a clean markdown issue with sections:

## What happened?
[Your description]

## Steps to reproduce
1. [Step 1]
2. [Step 2]

## Expected behavior
[What you expected]

## System Info
**App Version:** 2.1.0
**OS:** Windows 10 10.0.19045
**Python:** 3.12.1
**Frozen:** No (source)
**Loaded File:** Mounts.json
**Mounts Loaded:** 6
**Current Mount:** Higgs (Buffalo)

System Info (auto-collected)

When the "Include system info" checkbox is enabled (default), the following is automatically gathered:

Field Description
App Version From the VERSION file
OS Operating system name, release, and build
Python Python interpreter version
Frozen Whether running as a PyInstaller exe or from source
Loaded File Filename only (not the full path — your directory structure stays private)
Mounts Loaded How many mounts are in the loaded file
Current Mount Name and type of the mount currently being edited

Screenshot Attachment

When enabled, the editor captures a PNG screenshot of only the editor window — not your desktop, other applications, or browser. The screenshot is uploaded to the GitLab intake project and embedded directly in the issue.

Note: Screenshot capture requires the Pillow library. If Pillow is not installed, the checkbox will be disabled with a note to install it. The standalone .exe build includes Pillow by default.

Save Data Attachment (Mounts.json before & after)

When enabled, two copies of the save data are uploaded:

File Description
Mounts_before.json The original file on disk (the version that was loaded)
Mounts_after.json The current in-memory state including all pending edits

This allows developers to compare exactly what changed and reproduce issues with the exact data that triggered them.

Privacy note: Save files contain mount names, stats, and Steam player data directory names. No personal information beyond what is in the save file is transmitted.

Where Reports Go

Bug reports are submitted to a separate private GitLab project (icarus-bug-reports) that is isolated from the main source code repository. The embedded reporter token has Reporter-level access on the intake project only — it cannot read or modify the source code, settings, or any other project.

Labels

Reports are automatically tagged with:

Label Description
user-submitted Submitted via the in-app bug reporter
from-client Created by the Icarus Pet Editor client
has-screenshot Report includes a screenshot attachment
has-save-data Report includes Mounts.json before/after

Security

  • The reporter token is scoped to the intake project only (cannot access icarus-pets)
  • Reporter role: can create issues and upload files, cannot read code or settings
  • Token is base64-encoded in the client (light obfuscation)
  • If the token is compromised, worst case is spam issues — revoke and rotate with next release
  • No arbitrary file uploads — only the app-controlled screenshot and save data

Offline / Error Handling

  • If GitLab is unreachable (no internet, server down), you'll see a clear error message
  • The submit button is disabled during submission to prevent accidental double-clicks
  • If a screenshot or file upload fails, the report is still submitted without the failed attachment
  • Progress updates are shown in the dialog during submission

Technical Details

Module

The bug reporting system is implemented in editor/bug_report.py:

Component Description
BugReportDialog Modal tkinter dialog with structured form fields
_api_post_json() Creates GitLab issues via REST API
_api_upload_file() Uploads files via multipart/form-data POST
_capture_window_screenshot() Captures editor window via PIL ImageGrab
_collect_system_info() Gathers version, OS, Python, app state info

Dependencies

  • Required: Python standard library (tkinter, urllib, json, threading)
  • Optional: Pillow for screenshot capture

See also: GUI Guide — Toolbar · Architecture · Development Setup

Back to Docs