How to Report a Bug in Vorssaint-Utils: A Step-by-Step Guide

To report a bug in Vorssaint-utils, use the GitHub issue template at /.github/ISSUE_TEMPLATE/bug_report.yml, complete the permission checklist from docs/TROUBLESHOOTING.md, and provide version details and reproduction steps.

The Vorssaint-utils repository provides a structured workflow for bug reporting that helps maintainers reproduce and fix issues quickly. This guide walks through the exact process defined in the source code, from pre-flight checks to submission.

Check the Troubleshooting Guide First

Before filing any issue, review docs/TROUBLESHOOTING.md to rule out common permission problems. The guide covers four critical macOS permissions that cause most "bugs":

• Accessibility — required for window manipulation
• Screen Recording — needed for window detection
• System Audio Recording — enables sound-related features
• Automation — allows inter-app scripting

The document explains how to toggle these permissions off and back on, which resolves many apparent bugs without code changes.

Use the Built-In GitHub Bug Report Template

The repository enforces a standardized format through /.github/ISSUE_TEMPLATE/bug_report.yml. This YAML file automatically generates a form when you navigate to Issues → New issue → 🐛 Bug Report.

Required Pre-Flight Checklist

The template requires two confirmations before submission:

1. Permission verification — you must confirm that Vorssaint is listed and enabled in System Settings → Privacy & Security, with the permission toggled off and back on
2. Version confirmation — you must verify the bug persists on the latest released version

These checkboxes are implemented as required fields in the template definition.

Information Fields You Must Complete

Field	Purpose
Description	Expected behavior vs. actual behavior
Steps to Reproduce	Numbered list to replicate the bug
Feature Area	Category like "Windows and Dock" or "Sound"
Screenshots/Recordings	Visual evidence (optional but recommended)
Vorssaint Version	From Settings → About
macOS Version	Selected from dropdown
Language	Interface language
Mac and Displays	Hardware and monitor configuration
Installation Method	Homebrew, manual download, or built from source

Complete Your Bug Report: A Working Example

Below is a properly formatted bug report that matches the template structure. You can adapt this pattern for your submission:

## Description

When I click the **Window Layout** shortcut *⌃⌘L*, nothing happens. I expect the active window to snap to the left half of the screen.

## Steps to Reproduce

1. Open Vorssaint.
2. Press **⌃⌘L** (the default "snap left" shortcut).
3. Observe that the window does not move.

## Feature Area

- Windows and Dock

## Screenshots / Recordings

*(attach screen recording showing shortcut with no effect)*

## Vorssaint Version

3.1.4

## macOS Version

macOS 14 (Sonoma)

## Language

English

## Mac and Displays

MacBook Pro 14 (M3 Pro) · built-in + one 4K external, scaled, two Spaces

## Installation Method

Homebrew

Additional Steps for Source Builds

If you compiled Vorssaint from source, run the self-test before reporting:

./build/Vorssaint --selftest

Attach this output to your issue. The self-test provides a health snapshot that accelerates diagnosis for build-specific problems.

Key Files Reference

Understanding these source files helps you provide better bug reports:

• /.github/ISSUE_TEMPLATE/bug_report.yml — defines form fields, required checkboxes, and automatic bug label assignment
• docs/TROUBLESHOOTING.md — contains permission reset procedures and the "Reporting a useful bug" section with maintainer expectations
• Sources/Vorssaint/main.swift — entry point; relevant for startup or core logic bugs
• Tools/uninstall.sh — clean removal script if reinstallation is needed

Summary

• Always check docs/TROUBLESHOOTING.md before reporting — permission issues masquerade as bugs
• Use the GitHub template at /.github/ISSUE_TEMPLATE/bug_report.yml for structured submission
• Complete both required checkboxes — permission verification and version confirmation
• Include version numbers for Vorssaint and macOS, plus reproduction steps
• Attach the --selftest output if you built from source
• Add screenshots or recordings whenever possible for visual bugs

Frequently Asked Questions

What if I can't find the bug report template on GitHub?

Navigate directly to https://github.com/vorssaint/vorssaint-utils/issues/new/choose and select 🐛 Bug Report. If the template doesn't appear, the repository may be outdated — in that case, manually structure your issue using the example in this guide.

Do I need to include my Mac model and display setup?

Yes. The template's Mac and Displays field exists because window management bugs often depend on specific hardware configurations, external monitor scaling, and Spaces usage. Omitting this information may prevent reproduction.

Can I report a bug if I'm using an older version of Vorssaint?

The template requires you to confirm testing on the latest version. Maintainers close stale-version reports automatically unless you can demonstrate the bug is a regression or the latest version is unavailable for your system.

What should I do if the bug involves a crash?

Include the crash report from Console.app (Applications → Utilities → Console) and any relevant log show output. Reference Sources/Vorssaint/main.swift in your description if the crash occurs during app startup.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}