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

To report a bug in Vorssaint-Utils, use the structured GitHub issue template at /.github/ISSUE_TEMPLATE/bug_report.yml after verifying macOS permissions via docs/TROUBLESHOOTING.md and completing the mandatory pre-flight checklist.

Reporting bugs effectively ensures maintainers can reproduce and fix issues quickly. In the vorssaint/vorssaint-utils repository, the maintainers enforce a rigorous workflow that filters out configuration errors and captures essential diagnostic data upfront. This guide walks through the exact steps required to submit a valid, actionable bug report for the Vorssaint macOS utility.

Check the Troubleshooting Guide First

Before opening a new issue, consult docs/TROUBLESHOOTING.md in the repository root. This document explains common scenarios where the app appears broken but actually lacks proper system authorization.

According to the source documentation, the troubleshooting guide covers how to verify that Vorssaint is correctly granted Accessibility, Screen Recording, System Audio Recording, or Automation permissions. Many apparent bugs are simply permission denials that can be resolved without code changes.

Resetting Permissions

If a feature does nothing at all, the guide recommends checking System Settings → Privacy & Security to confirm Vorssaint is listed and enabled for the required permission, then toggling it off and back on. If the issue persists after verification, you may need to run Tools/uninstall.sh for a complete removal and fresh install, which clears cached permission states that macOS sometimes fails to refresh.

Use the GitHub Issue Template

The repository provides a dedicated bug report form defined in /.github/ISSUE_TEMPLATE/bug_report.yml. When you navigate to Issues → New Issue → 🐛 Bug Report on GitHub, the interface renders this YAML template into a structured web form with mandatory fields.

This template enforces data quality by requiring specific inputs before the submit button activates, ensuring every report contains the diagnostic information found in the "Reporting a useful bug" section of the troubleshooting guide.

Complete the Pre-Flight Checklist

The template requires you to confirm two prerequisites via checkboxes:

• Permission verification: You have checked that Vorssaint is listed and switched on for the permission it needs in System Settings, and you have toggled it off and back on.
• Latest version: You have confirmed the problem still occurs on the latest released version of Vorssaint.

These checkpoints eliminate false-positive reports caused by misconfigured Accessibility access or outdated builds.

Provide Required Bug Details

The template captures structured data designed to make reports immediately actionable without follow-up questions.

Describe the Bug and Reproduction Steps

You must provide:

• Description: A clear explanation of expected behavior versus actual behavior.
• Reproduction steps: A numbered list starting from application launch.
• Feature area: Categorical selection (e.g., "Windows and Dock", "Sound", "Keyboard").
• Screenshots or recordings: Visual evidence is optional but highly recommended for UI-related issues.

Specify Environment Information

The form requires exact version information to isolate platform-specific bugs:

• Vorssaint Version: Found in Settings → About.
• macOS Version: Selected from a dropdown (e.g., macOS 14 Sonoma).
• Hardware configuration: Mac model and display setup.
• Installation method: Homebrew, direct download, or built from source.

Submit the Issue and Attach Diagnostics

Once all required fields are populated, click Submit new issue. The template automatically applies the bug label and formats the content according to the repository's triage standards.

Special Case: Source Builds

If you compiled Vorssaint from source, attach the output of the self-test command to your report:

./build/Vorssaint --selftest

This provides a health snapshot of your specific build environment, which is particularly valuable when debugging startup behavior in Sources/Vorssaint/main.swift or build-specific linking issues.

Example Bug Report

Below is a filled-in example that mirrors the template structure. Use this as a reference when completing the GitHub form:

<!-- Pre‑flight checks (auto‑filled by the template) -->
- [x] If the feature does nothing at all, I checked that Vorssaint is listed and switched on for the permission it needs in System Settings, Privacy and Security, and toggled it off and back on.
- [x] It still happens on the latest version.

## 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 a short screen recording showing the shortcut being pressed 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

Summary

• Always consult docs/TROUBLESHOOTING.md for permission issues before filing a bug.
• Use the structured template at /.github/ISSUE_TEMPLATE/bug_report.yml to ensure consistent data capture.
• Complete the pre-flight checklist confirming permissions and version currency.
• Provide specific reproduction steps, exact version numbers from Settings → About, and installation method.
• For source builds, include ./build/Vorssaint --selftest output to aid debugging.

Frequently Asked Questions

What if I don't have a GitHub account?

You must create a free GitHub account to access the issue tracker in the vorssaint/vorssaint-utils repository. The maintainers centralize all technical discussion in GitHub Issues to ensure searchable history and proper integration with the /.github/ISSUE_TEMPLATE/bug_report.yml workflow.

Why does the template require toggling permissions off and on?

The docs/TROUBLESHOOTING.md documentation indicates that macOS sometimes fails to correctly register permission grants until the toggle is cycled. This step, described in the pre-flight checklist, eliminates the majority of false-positive bug reports related to Accessibility or Screen Recording access.

Can I report a bug for an older version of Vorssaint?

No. The pre-flight checklist explicitly requires confirming the bug exists on the latest version. The maintainers only investigate issues reproducible in current releases. Update to the latest version via Homebrew or the project's releases page before submitting.

Where do I find the version number for the bug report?

Open the Vorssaint application, navigate to Settings → About, and copy the version string displayed there. If you built from source, you can also run ./build/Vorssaint --selftest to output build metadata including the commit hash and version string.

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