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

> Learn how to contribute to vorssaint-utils development on macOS. Clone the repo, build, run selftest, follow architecture, and submit single-topic PRs using conventional commits.

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

---

**To contribute to vorssaint-utils, clone the repository, build with [`./build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/./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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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:

```bash
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`](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh) script is a plain shell script invoking `swiftc` with no external dependencies. For code signing during development, run [`Tools/setup-signing.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/setup-signing.sh) to create a stable, self-signed identity.

### Understanding Key Configuration Files

- **[`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift)** — Declares the Swift package, system-library targets for `HIDEventSystem` and `VMStatisticsCompat`, and the main executable target
- **[`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/Core/Localization.swift). This design forces compile-time verification that all supported languages contain new keys.

```swift
// 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:

```swift
// 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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift) | Swift package declaration and system-library targets |
| [`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift) | Application entry point and CLI flag parsing |
| [`Sources/Vorssaint/Core/Localization.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/Localization.swift) | Centralized string catalog with compile-time translation enforcement |
| [`Sources/Vorssaint/UI/WindowGestureControls.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/WindowGestureControls.swift) | Reference implementation of UI-service separation |
| [`Sources/Vorssaint/Services/AudioService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/AudioService.swift) | Example service exposing `shared` singleton and `ObservableObject` |
| [`CONTRIBUTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/CONTRIBUTING.md) | Complete contribution guide and project conventions |
| [`README.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/README.md) | Feature overview and installation instructions |
| [`Tools/setup-signing.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/./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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/./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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/./build.sh) to compile, then execute `./build/Vorssaint --selftest` to run the built-in health checks defined in [`Sources/Vorssaint/Support/SelfTest.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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.