Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
202 lines (141 loc) · 6.25 KB

CONTRIBUTING.md

File metadata and controls

202 lines (141 loc) · 6.25 KB
Raw

Contributing to SoundBrake

Thank you for your interest in improving SoundBrake! This document covers everything you need to know to make a contribution.

Table of Contents

Code of Conduct

Please be respectful and constructive in all interactions. We follow the Contributor Covenant Code of Conduct.

Getting Started

Prerequisites

Tool Version Notes
Go 1.21+ https://go.dev/dl/
Git any
Inno Setup 6.x Windows installer builds only
create-dmg latest macOS .dmg builds only — brew install create-dmg
fpm latest Linux packaging only — sudo gem install fpm

Fork and clone

git clone https://github.com/eneswritescode/soundbrake.git
cd soundbrake
go mod download

Run in development

go run .

The app starts immediately in the system tray. Logs go to:

  • Windows: %AppData%\SoundBrake\soundbrake.log
  • macOS / Linux: ~/.config/SoundBrake/soundbrake.log

Project Structure

soundbrake/
├── main.go                     Entry point
├── versioninfo.json            Windows EXE metadata (icon, version string)
├── resource.syso               Generated — do not edit manually
├── assets/                     Icons and installer images
├── internal/
│   ├── audio/                  Platform-specific volume read/write
│   │   ├── audio_windows.go    WASAPI via COM
│   │   ├── audio_darwin.go     osascript
│   │   └── audio_linux.go      pactl / PipeWire
│   ├── i18n/                   Locale detection and string loading
│   ├── icon/                   Runtime tray icon renderer
│   ├── monitor/                Core state machine (polling, levels, backoff)
│   ├── notification/           Platform-specific desktop notifications
│   ├── singleinstance/         Mutex/lock-file to prevent duplicate processes
│   ├── startup/                Launch-on-login registration per platform
│   ├── tray/                   System tray UI (getlantern/systray)
│   └── types/                  Shared type definitions (Level, Config, …)
└── setup/
    ├── windows/                build.bat + soundbrake.iss (Inno Setup)
    ├── macos/                  build.sh + entitlements.plist
    └── linux/                  package.sh

Key invariant: every internal/ package that has platform-specific behaviour uses Go build tags (//go:build windows, //go:build darwin, //go:build linux). If you add a new platform-specific file, follow this pattern.

Development Workflow

# 1. Create a focused branch
git checkout -b fix/notify-cooldown-reset

# 2. Make your changes

# 3. Vet — must be clean
go vet ./...

# 4. Build for your current platform
go build -o soundbrake .

# 5. Test manually

# 6. Commit with a clear message (see convention below)
git commit -m "fix(monitor): reset cooldown timer on device change"

# 7. Push and open a PR
git push origin fix/notify-cooldown-reset

Commit message convention

<type>(<scope>): <short summary>
Type When to use
feat New feature
fix Bug fix
docs Documentation only
refactor Code change that is neither a fix nor a feature
build Build scripts, CI, dependencies
chore Misc housekeeping

Scope examples: monitor, audio, tray, i18n, notification, startup, ci

Building for Each Platform

Windows

setup\windows\build.bat

Produces setup\windows\Output\SoundBrake-Setup-x.x.x.exe.

Requirements: Go, goversioninfo (go install github.com/josephspurrier/goversioninfo/cmd/goversioninfo@latest), Inno Setup 6.

macOS

./setup/macos/build.sh

Produces setup/macos/SoundBrake-x.x.x.dmg.

Requirements: Go, create-dmg (brew install create-dmg).
For a signed build: SIGNING_ID="Developer ID Application: ..." ./setup/macos/build.sh

Linux

./setup/linux/package.sh

Produces .deb and .rpm packages under setup/linux/.

Requirements: Go, fpm (sudo gem install fpm).

Code Conventions

  • Standard gofmt formatting — run gofmt -w . before committing, or configure your editor to format on save.
  • No external dependencies unless strictly necessary. The current dependency list is minimal by design.
  • Build tags over _<os> suffixes — prefer //go:build windows over filename-only _windows.go conventions, except when both are needed for clarity (current code uses both; keep them consistent).
  • Error handling — return errors up the call stack; do not silently swallow them. Log at the point where context is richest.
  • No global mutable state outside of Monitor — keep the core state machine self-contained.

Submitting a Pull Request

  1. Open a PR against the main branch.
  2. Fill in the pull request template.
  3. Make sure CI passes (build + vet on Windows, macOS, Linux).
  4. Keep the PR focused — one logical change per PR.
  5. If you're fixing a bug, reference the issue number: Fixes #123.

PRs that introduce breaking changes to the monitor behaviour (level thresholds, cooldown logic) should include an explanation of the reasoning.

Reporting Bugs

Use the Bug Report issue template. Include:

  • OS and version
  • SoundBrake version
  • Steps to reproduce
  • Relevant log lines

Requesting Features

Use the Feature Request issue template. Search existing issues first to avoid duplicates.