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

> Learn how to contribute to vorssaint-utils on macOS. Follow our guide to fork, build, set up signing, and submit PRs using conventional commits for the vorssaint/vorssaint-utils repository.

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

---

**To contribute to vorssaint-utils, fork the repository, run [`./build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/./build.sh) to compile the Swift package, create a stable signing identity with [`Tools/setup-signing.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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:

```bash
./Tools/setup-signing.sh

```

This generates a stable identity that [`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/Localization.swift) file in this directory defines all user-visible strings as static members of a `Strings` struct, while [`Permissions.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/Localization.swift). When adding features, you must define new strings there:

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

```bash
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:

```bash
./build.sh --install

```

## Contribution Workflow

The project follows a lightweight GitHub workflow defined in [`CONTRIBUTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/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:

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

```swift
// 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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/./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`](https://github.com/vorssaint/vorssaint-utils/blob/main/./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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/App/main.swift) or permission handling in [`Sources/Vorssaint/Core/Permissions.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/Permissions.swift).