How to Contribute to Vorssaint-Utils Development: A Complete Guide for macOS Swift Contributors

To contribute to vorssaint-utils, clone the repository, build with ./build.sh, run ./build/Vorssaint --selftest to verify, follow the UI/service separation architecture, and submit single-topic PRs using conventional commit format.

Vorssaint-utils is a native macOS utility written in Swift and packaged as a SwiftPM executable. This guide walks through the complete contribution workflow based on the actual source code in vorssaint/vorssaint-utils, from initial setup to submitting a polished pull request.

Project Architecture and Code Organization

Understanding the codebase structure is essential before making changes. The repository follows strict separation of concerns across six distinct layers:

Layer	Purpose	Key Location
App Core	Entry point, menu-bar status item, command-line helpers	Sources/Vorssaint/main.swift
Core	Localization, permission constants, UserDefaults keys, shared utilities	Sources/Vorssaint/Core/
Services	All functional behavior (audio, system monitor, window management)	Sources/Vorssaint/Services/
UI	Pure SwiftUI views—no business logic, only observes services	Sources/Vorssaint/UI/
Support	Diagnostic commands (--selftest, --sensors) and helper scripts	Sources/Vorssaint/Support/
External Modules	Lightweight C-style system wrappers for HID events and VM statistics	Sources/HIDEventSystem/ and Sources/VMStatisticsCompat/

The architectural rule governing all contributions: UI observes services, and services never import SwiftUI. Services expose singletons as Type.shared and publish state via ObservableObject.

Setting Up Your Development Environment

Clone and Build

Start with a clean build to verify your environment:

git clone https://github.com/vorssaint/vorssaint-utils.git
cd vorssaint-utils
./build.sh                # compiles the app with swiftc

./build/Vorssaint --selftest   # verifies the build

The build.sh script is a plain shell script invoking swiftc with no external dependencies. For code signing during development, run Tools/setup-signing.sh to create a stable, self-signed identity.

Understanding Key Configuration Files

• Package.swift — Declares the Swift package, system-library targets for HIDEventSystem and VMStatisticsCompat, and the main executable target
• Sources/Vorssaint/main.swift — Application entry point that parses command-line flags and launches the menu-bar app

Contribution Workflow: Step by Step

1. Plan Your Change

Pick a single-topic PR. The maintainer rejects bundled changes. Reference any related issue with Refs #123 in your PR description—this exact syntax triggers the project's automation.

2. Follow Layout Conventions

Before writing code, review CONTRIBUTING.md for the complete project layout specification. Key constraints:

• Services live in Sources/Vorssaint/Services/ and must not import SwiftUI
• UI views live in Sources/Vorssaint/UI/ and consume services via @ObservedObject or @EnvironmentObject

3. Implement Your Feature or Fix

Adding Localized Strings

All user-facing text must be centralized in Core/Localization.swift. This design forces compile-time verification that all supported languages contain new keys.

// Sources/Vorssaint/Core/Localization.swift
extension Strings {
    static let newFeatureDescription = LocalizedStringKey(
        "newFeatureDescription",
        comment: "Description shown in the Settings panel for the new feature"
    )
}

Then create the same key in each locale file, such as Resources/en.lproj/InfoPlist.strings and corresponding files in Core/Localizations/.

Creating a SwiftUI View

Place new views under Sources/Vorssaint/UI/ and ensure they only observe services:

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

struct NewFeatureView: View {
    @ObservedObject var audioService = AudioService.shared   // service lives in Services/

    var body: some View {
        VStack {
            Text(Strings.newFeatureDescription)
            Slider(value: $audioService.volume, in: 0...1)
        }
        .padding()
    }
}

This pattern mirrors existing views like Sources/Vorssaint/UI/WindowGestureControls.swift.

4. Run the Test Suite

After changes, your build must:

• Complete without warnings
• Pass ./build/Vorssaint --selftest

The self-test is defined in Sources/Vorssaint/Support/SelfTest.swift. Fix any failures before submitting.

5. Document and Localize

• Add new user-facing text to every language folder (Resources/<locale>.lproj/)
• Update documentation links in README.md if you modify public behavior

6. Submit Your Pull Request

Follow these formatting rules:

• PR title format: type(scope): lowercase imperative phrase
• Issue reference: Include Refs #123 (exact syntax required)
• Do not edit CHANGELOG.md — the maintainer handles this
• Include testing details: Model, macOS version, and relevant UI settings in the PR description

The maintainer runs PRs on actual Mac hardware, so comprehensive environment details speed up review.

Key Files Every Contributor Should Know

File	Role
Package.swift	Swift package declaration and system-library targets
Sources/Vorssaint/main.swift	Application entry point and CLI flag parsing
Sources/Vorssaint/Core/Localization.swift	Centralized string catalog with compile-time translation enforcement
Sources/Vorssaint/UI/WindowGestureControls.swift	Reference implementation of UI-service separation
Sources/Vorssaint/Services/AudioService.swift	Example service exposing shared singleton and ObservableObject
CONTRIBUTING.md	Complete contribution guide and project conventions
README.md	Feature overview and installation instructions
Tools/setup-signing.sh	Local code-signing setup for development builds

Summary

Contributing to vorssaint-utils requires understanding its strict architectural boundaries:

• Build with ./build.sh and verify with --selftest
• Respect the UI/service separation: UI observes services via ObservableObject, services never import SwiftUI
• Centralize all strings in Localization.swift to enforce translation coverage
• Submit single-topic PRs with conventional commit formatting and Refs #123 syntax
• Include hardware and macOS version details for maintainer testing

Frequently Asked Questions

What programming language is vorssaint-utils written in?

Vorssaint-utils is written in Swift and packaged as a SwiftPM executable. The project uses SwiftUI for interface elements and lightweight C-style wrappers for system-level functionality like HID events and VM statistics.

Can I build vorssaint-utils without installing Xcode?

Yes. The ./build.sh script invokes swiftc directly and has no external dependencies beyond a standard Swift toolchain. While Xcode provides IDE conveniences, you can compile, test, and develop entirely from the command line.

Why does the project require adding strings to Localization.swift?

The centralized localization design in Sources/Vorssaint/Core/Localization.swift forces compile-time verification that every supported language has a translation for new user-facing text. When you add a LocalizedStringKey property, the compiler checks for corresponding entries across all locale directories, preventing runtime crashes from missing translations.

How do I test my changes before submitting a PR?

Run ./build.sh to compile, then execute ./build/Vorssaint --selftest to run the built-in health checks defined in Sources/Vorssaint/Support/SelfTest.swift. Ensure zero warnings and passing self-tests. Include your Mac model, macOS version, and any relevant UI settings in your PR description so the maintainer can reproduce your testing environment.

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