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

> Learn how to report a bug in vorssaint-utils. Follow our step-by-step guide using the GitHub issue template and troubleshooting checklist for effective bug reporting.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: how-to-guide
- Published: 2026-09-05

---

**To report a bug in Vorssaint-utils, use the GitHub issue template at [`/.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/vorssaint/vorssaint-utils/blob/main//.github/ISSUE_TEMPLATE/bug_report.yml), complete the permission checklist from [`docs/TROUBLESHOOTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main//.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:

```markdown

## 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:

```bash
./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`](https://github.com/vorssaint/vorssaint-utils/blob/main//.github/ISSUE_TEMPLATE/bug_report.yml)** — defines form fields, required checkboxes, and automatic `bug` label assignment
- **[`docs/TROUBLESHOOTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/docs/TROUBLESHOOTING.md)** — contains permission reset procedures and the "Reporting a useful bug" section with maintainer expectations
- **[`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift)** — entry point; relevant for startup or core logic bugs
- **[`Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/uninstall.sh)** — clean removal script if reinstallation is needed

## Summary

- **Always check [`docs/TROUBLESHOOTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/docs/TROUBLESHOOTING.md)** before reporting — permission issues masquerade as bugs
- **Use the GitHub template at [`/.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/vorssaint/vorssaint-utils/blob/main//.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`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift)** in your description if the crash occurs during app startup.