Contributing

Thank you for considering contributing to Irrlicht. Every contribution matters.

Welcome

Irrlicht is open source under the MIT license. Contributions of all kinds are welcome: bug reports, feature requests, documentation improvements, code contributions, and community support.

Whether this is your first open-source contribution or your thousandth, we appreciate you taking the time to make Irrlicht better.

Ways to Contribute

Report bugs via GitHub Issues -- help us find and fix problems
Suggest features via GitHub Discussions -- share your ideas for improvement
Improve documentation -- fix typos, clarify explanations, add examples
Submit pull requests -- fix bugs, add features, refactor code
Help others in Discussions -- answer questions, share your experience

First-time contributors Look for issues labeled good first issue -- these are specifically chosen to be approachable for newcomers to the codebase.

Development Setup

Prerequisites

macOS 13 (Ventura) or later
Go 1.21+
Swift 5.9+
Xcode Command Line Tools
git

Getting Started

Fork the repository on GitHub
Click the "Fork" button on the Irrlicht repository page to create your own copy.

Clone your fork

git clone https://github.com/YOUR_USERNAME/Irrlicht.git

Enter the project directory
```
cd Irrlicht
```
Build everything
```
./platforms/build-release.sh
```
This compiles the Go daemon (universal binary) and the Swift macOS app.
Run the test suite
```
./validate.sh
```
All tests must pass before you start making changes. If they don't, you've found a bug -- please report it.

Project Structure

Irrlicht is a two-process architecture: a Go daemon that monitors agent sessions, and a Swift macOS app that renders the menu bar UI.

Irrlicht/
  core/             # Go daemon -- session detection, state machine, IPC
  platforms/macos/  # Swift macOS app -- menu bar UI, popover, notifications
  validate.sh       # Single entry point for all validation

For a full breakdown of how the pieces fit together, see System Design.

Development Workflow

Branching

Create a feature branch from main:

git checkout -b feature/my-feature

Use descriptive branch names with a prefix that reflects the type of change:

feature/ -- new functionality
fix/ -- bug fix
docs/ -- documentation changes

Making Changes

Keep changes focused -- one feature or fix per PR
Follow existing code style and conventions
Add tests for new functionality
Update documentation if behavior changes

Testing

The single entry point for all validation is:

./validate.sh

This runs the full pipeline in order:

Go build
Swift build
Go tests
Swift tests
Integration tests

Important A change is only done when validate.sh exits 0. No exceptions.

To run tests for individual components during development:

# Go tests only
cd core && go test -v ./...

# Swift tests only
cd platforms/macos && swift test

Commit Messages

Use conventional commits:

feat: add WebSocket reconnection with backoff
fix: correct state transition on ESC cancellation
docs: clarify adapter configuration options
refactor: extract session parser into standalone module
test: add table-driven tests for state machine

Keep the first line under 72 characters
Explain why, not just what
Reference related issues when applicable: Fixes #42

Pull Requests

Ensure validation passes
```
./validate.sh
```
Push your branch
```
git push origin feature/my-feature
```
Open a PR against main
Go to the repository on GitHub and open a new pull request.
Fill in the PR template
Include:
- Summary of changes
- Test plan
- Screenshots (for UI changes)
Request review
Tag a maintainer and address feedback promptly.

Code Guidelines

Go (Daemon)

Follow standard Go conventions (gofmt, go vet)
Use interfaces for external dependencies (ports-and-adapters pattern)
Prefer table-driven tests
Handle errors explicitly -- no panic in library code
Keep functions focused and testable

Swift (macOS App)

Follow Swift API Design Guidelines
Use SwiftUI idioms (@State, @Binding, @EnvironmentObject)
Keep views small and composable
Test with SwiftUI previews where possible

General

No unnecessary abstractions -- three similar lines beat a premature abstraction
Delete unused code -- don't comment it out
Only add comments where the logic isn't self-evident
Prefer editing existing files over creating new ones

Reporting Bugs

Before Filing

Check existing issues for duplicates
Try the latest version
Check logs: ~/Library/Application Support/Irrlicht/logs/

Bug Report Should Include

macOS version
Irrlicht version (irrlichd --version)
Steps to reproduce
Expected vs actual behavior
Relevant log output

Logs location Irrlicht stores daemon logs at ~/Library/Application Support/Irrlicht/logs/. Including relevant excerpts in your bug report helps us diagnose the issue much faster.

Feature Requests

Open a Discussion first to gauge interest before writing code
Describe the problem you're solving, not just the solution
Consider how it fits the project philosophy: zero-config, deterministic, honest signals

AI Agent Contributors

Irrlicht is designed to be agent-verifiable. If you're an AI coding agent contributing to this project:

Run ./validate.sh after every change
A task is only complete when exit code is 0
Never mark a task done based only on compilation
If validation fails, inspect the failing test and fix the root cause
Do not skip or comment out failing assertions

Non-negotiable ./validate.sh is the single source of truth. If it fails, the work is not done -- regardless of whether the code compiles or individual tests pass in isolation.

Code Review

All PRs require at least one review
Be kind and constructive
Explain the why behind requested changes
Small PRs are reviewed faster

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Recognition

All contributors are recognized in the project. Thank you for helping make Irrlicht better.