Vorssaint-Utils Development Workflow: Complete Guide to Building, Testing, and Contributing

The vorssaint-utils development workflow uses a single build.sh script to handle cloning, code signing, development builds, self-testing, unit tests, and local installation, with CI validation on every push.

This article walks through the complete vorssaint-utils development workflow based on the actual source code in the vorssaint/vorssaint-utils repository. Whether you're fixing a bug or adding features, these steps will get you from zero to a working build on macOS.

Prerequisites and Initial Setup

Before building, ensure you have Apple Command-Line Tools and Swift 6.0.3 installed. The project uses SwiftPM for dependency resolution but relies on a custom shell script for the full build pipeline.

Clone the repository and enter the project directory:

git clone https://github.com/vorssaint/vorssaint-utils.git
cd vorssaint-utils

Code Signing Setup (Optional but Recommended)

macOS requires code-signed binaries for proper execution. If you lack an Apple Developer ID, run the helper script at [Tools/setup-signing.sh](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/setup-signing.sh):

./Tools/setup-signing.sh

This creates a local "Vorssaint Utils Signing" certificate. The build script invokes this automatically when needed, but running it upfront prevents interruptions.

Building a Development Version

The core of the vorssaint-utils development workflow is [build.sh](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh). Use the --dev flag (lines 29-38) to create a Developer variant that coexists with release builds:

./build.sh --dev

What --dev changes:

• Bundle identifier switches to com.vorssaint.utils.dev (prevents conflicts with /Applications/Vorssaint.app)
• Optimization disabled (-Onone) for faster compile times during iteration
• Output location is ./build/Vorssaint (Developer).app

This side-by-side installation lets you test changes without affecting your production instance.

Verifying Your Build with Self-Tests

After any successful build, validate the binary launches correctly:

./build/Vorssaint --selftest

A functioning build prints SELFTEST OK and exits. This check appears in [build.sh](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh#L35-L37) at lines 35-37 and runs automatically during CI.

Running Unit Tests

Execute the standalone test harness with:

./build.sh --test

The test path (lines 45-84) performs these operations:

1. Compiles metrics-tests via a direct swiftc invocation with all dependencies
2. Runs the executable
3. Cleans test-generated preference files via discard_test_preferences (around line 20)

The test source lives at [Tests/MetricsTests.swift](https://github.com/vorssaint/vorssaint-utils/blob/main/Tests/MetricsTests.swift).

Installing Locally for Real-World Testing

To replace or install the app in /Applications:

./build.sh --install

The install logic (lines 99-117) handles:

• Stopping any running Vorssaint instance
• Removing legacy bundle versions
• Copying via ditto to /Applications
• Re-signing so macOS permissions survive rebuilds

The install path assembly appears at lines 99-101, with copy operations following at lines 99-117.

Understanding the CI Validation Pipeline

Every push to main triggers the workflow defined in [.github/workflows/ci.yml](https://github.com/vorssaint/vorssaint-utils/blob/main/.github/workflows/ci.yml). The CI runner (macOS 15) performs:

- name: Verify Swift toolchain
- name: Build
  run: ./build.sh
- name: Selftest
  run: ./build/Vorssaint --selftest
- name: Unit tests
  run: ./build.sh --test

This ensures the vorssaint-utils development workflow produces working artifacts before any merge. The CI uses the same [build.sh](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh) you run locally, eliminating "works on my machine" discrepancies.

Release Process (Maintainers)

For official releases, tag a version:

git tag vX.Y.Z
git push origin vX.Y.Z

The release.yml workflow (referenced but not detailed in source) handles:

• Developer ID signing
• Notarization
• DMG publication

This remains separate from the daily vorssaint-utils development workflow.

Complete Developer Cycle Example

Here's the full sequence for typical contribution work:

# 1. Clone and enter directory

git clone https://github.com/vorssaint/vorssaint-utils.git
cd vorssaint-utils

# 2. (Optional) Set up local signing

./Tools/setup-signing.sh

# 3. Build development version

./build.sh --dev

# 4. Verify binary health

./build/Vorssaint --selftest

# 5. Install for manual testing

./build.sh --install

# 6. Run unit test suite

./build.sh --test

# 7. Commit and push — CI validates automatically

git add .
git commit -m "feat: your change description"
git push origin feature-branch

Key Files in the Development Workflow

File	Purpose
[build.sh](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh)	Central build orchestrator; handles --dev, --install, --test flags
[Tools/setup-signing.sh](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/setup-signing.sh)	Local certificate creation for unsigned builds
[Package.swift](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift)	SwiftPM manifest for editor indexing
[.github/workflows/ci.yml](https://github.com/vorssaint/vorssaint-utils/blob/main/.github/workflows/ci.yml)	Automated validation on every push/PR
[Tests/MetricsTests.swift](https://github.com/vorssaint/vorssaint-utils/blob/main/Tests/MetricsTests.swift)	Unit test implementation
[CONTRIBUTING.md](https://github.com/vorssaint/vorssaint-utils/blob/main/CONTRIBUTING.md)	Extended contributor guidelines

Summary

• Single-script workflow: All build, sign, and test operations flow through build.sh with no external dependencies
• Side-by-side development: The --dev flag creates isolated Developer variants that won't conflict with release installs
• Multiple validation layers: Self-tests verify launch capability; metrics-tests provide unit coverage; CI enforces both on every change
• Flexible signing: setup-signing.sh enables local development without Apple Developer ID; production releases use proper notarization
• Deterministic cleanup: Test runs automatically clear preference files to maintain reproducible environments

Frequently Asked Questions

Do I need an Apple Developer ID to build vorssaint-utils?

No. Run ./Tools/setup-signing.sh to create a local "Vorssaint Utils Signing" certificate. The build script detects and uses this automatically. Developer ID is only required for distribution releases.

What's the difference between ./build.sh and ./build.sh --dev?

Plain ./build.sh creates an optimized release build with the standard bundle identifier com.vorssaint.utils. The --dev flag (lines 29-38) switches to com.vorssaint.utils.dev, disables optimization, and outputs to ./build/Vorssaint (Developer).app so you can test alongside an installed release.

How do I run tests without installing anything?

Execute ./build.sh --test directly. This compiles and runs the standalone test executable without touching /Applications. The script cleans up test preferences automatically after completion.

What happens if CI fails on my pull request?

The CI pipeline in .github/workflows/ci.yml repeats your local build steps: toolchain verification, build, self-test, and unit tests. Failures typically indicate environment differences (Swift version) or test regressions. Fix locally by running the same commands, then push again.

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