How to Contribute to Vorssaint-Utils: A Complete Guide for macOS Developers

To contribute to vorssaint-utils, fork the repository, run ./build.sh to compile the Swift package, create a stable signing identity with Tools/setup-signing.sh, and submit PRs following the conventional commit format type(scope): description.

Vorssaint-utils is a native macOS utility suite built entirely in Swift 5.9, targeting Apple Silicon Macs running macOS 14+. Its architecture is deliberately modular, making it easy to contribute to specific features without touching unrelated systems. This guide covers the complete workflow from cloning the repository to submitting your first pull request, based on the actual source code structure in vorssaint/vorssaint-utils.

Prerequisites and Development Environment

Before you can contribute to vorssaint-utils, ensure your environment meets the following requirements:

• macOS 14 or later installed on an Apple Silicon Mac
• Swift 5.9 toolchain (bundled with Xcode Command Line Tools)
• Git for version control

The project uses a pure Swift Package Manager setup. Unlike traditional macOS apps, there is no .xcodeproj file. Instead, the build is orchestrated through Package.swift, which declares two system library dependencies (HIDEventSystem and VMStatisticsCompat) and an executable target.

Setting Up Code Signing

Stable code signing is essential because vorssaint-utils requires macOS permissions such as Accessibility and Screen Recording. The project uses a consistent self-signed identity to ensure these permissions persist across rebuilds.

Run the helper script to create this identity locally:

./Tools/setup-signing.sh

This generates a stable identity that build.sh uses automatically during compilation, preventing the repetitive permission prompts that normally occur with unsigned local builds.

Understanding the Project Architecture

The codebase in Sources/Vorssaint/ follows a strict five-layer separation that isolates concerns and simplifies contributions.

The Five-Layer Source Layout

1. App (Sources/Vorssaint/App/) – Contains main.swift (the entry point) and menu-bar status item handling. This layer manages application lifecycle and system integration.

2. Core (Sources/Vorssaint/Core/) – Houses central services, settings management, localization, and permission handling. The Localization.swift file in this directory defines all user-visible strings as static members of a Strings struct, while Permissions.swift manages macOS entitlement requests.

3. Services (Sources/Vorssaint/Services/) – Implements the actual features such as the volume mixer, window switcher, and fan control. These are pure logic classes that do not import UI frameworks.

4. UI (Sources/Vorssaint/UI/) – Contains SwiftUI view definitions only. Views observe service objects but never import service code directly, preserving a clean unidirectional data flow.

5. Support (Sources/Vorssaint/Support/) – Provides diagnostic helpers including the --selftest flag and sensor dump utilities.

This separation means you can add a new keyboard shortcut by editing only the relevant service and its corresponding UI view, leaving the Core layer untouched.

Localization System

All user-facing strings are centralized in Sources/Vorssaint/Core/Localization.swift. When adding features, you must define new strings there:

// Sources/Vorssaint/Core/Localization.swift
extension Strings {
    static let newFeatureDescription = "A short description of the new feature."
}

You then mirror this key in every locale file under Sources/Vorssaint/Core/Localizations/ (e.g., Strings+Spanish.swift). This compile-time verification ensures no translation keys are missing in supported languages.

Building and Testing Locally

Clone the repository and verify your setup with the built-in health check:

git clone https://github.com/vorssaint/vorssaint-utils.git
cd vorssaint-utils
./build.sh                     # Compile and bundle the app

./build/Vorssaint --selftest   # Execute the built-in health check

The --selftest flag runs diagnostic routines that verify sensor access, permission states, and service initialization. Always run this before submitting changes.

To install your local build into /Applications for extended testing:

./build.sh --install

Contribution Workflow

The project follows a lightweight GitHub workflow defined in CONTRIBUTING.md.

Making Changes

1. Fork and clone the repository.
2. Create a branch for a single-topic change (bug fix, feature, or translation).
3. Ensure localization coverage – If your change adds user-facing strings, update all locale files under Sources/Vorssaint/Core/Localizations/.
4. Run the health check – Execute ./build/Vorssaint --selftest to verify stability.
5. Commit following the conventional format: type(scope): lowercase imperative phrase.
6. Reference issues using Refs #<number> in your PR description so automation can close related tickets.

Pull Request Format

PR titles must follow the pattern:

type(scope): description

Examples include feat(volume): add mute toggle or fix(localization): correct Spanish translation. The scope should match the directory you modified (e.g., services, ui, core).

Adding New Features

When implementing new functionality, create both a service and a corresponding UI view.

First, define the service in the Services layer:

// Sources/Vorssaint/Services/NewFeatureService.swift
final class NewFeatureService {
    static let shared = NewFeatureService()
    @Published var isEnabled = false
    // Service logic goes here…
}

Then create the SwiftUI view in the UI layer:

// Sources/Vorssaint/UI/NewFeatureView.swift
import SwiftUI

struct NewFeatureView: View {
    @ObservedObject private var service = NewFeatureService.shared

    var body: some View {
        Toggle(Strings.newFeatureDescription, isOn: $service.isEnabled)
    }
}

Remember to add the corresponding string key to Localization.swift and all locale files before submitting.

Summary

• Environment: Requires macOS 14+, Apple Silicon, and Swift 5.9; no Xcode project file needed.
• Signing: Run Tools/setup-signing.sh once to create a persistent signing identity for permission stability.
• Architecture: Five-layer structure (App, Core, Services, UI, Support) keeps contributions isolated.
• Building: Use ./build.sh to compile and ./build/Vorssaint --selftest to verify health.
• Submitting: Follow conventional commit format type(scope): description and reference issues with Refs #<number>.

Frequently Asked Questions

Do I need Xcode to contribute to vorssaint-utils?

No. While you can use Xcode for editing, the project is a pure Swift Package. You can build entirely from the command line using ./build.sh, which invokes swiftc directly. The repository contains no .xcodeproj or .xcworkspace files.

Why does the build script require code signing?

Vorssaint-utils requires sensitive macOS permissions such as Accessibility and Screen Recording. Without a consistent signing identity, macOS treats every rebuild as a new application, forcing you to re-grant permissions constantly. The setup-signing.sh script creates a stable self-signed identity that persists across builds.

How are translations handled in the project?

All strings are defined in Sources/Vorssaint/Core/Localization.swift as static constants. When you add a new string there, the Swift compiler enforces that every file in Sources/Vorssaint/Core/Localizations/ contains the same key. This compile-time check prevents missing translations in any supported language.

What should I do if the self-test fails after my changes?

The --selftest flag validates hardware sensor access, permission states, and service initialization. If it fails, check Sources/Vorssaint/Support/ for the diagnostic implementations and ensure your changes did not break the service lifecycle in Sources/Vorssaint/App/main.swift or permission handling in Sources/Vorssaint/Core/Permissions.swift.

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