Contributing

Thanks for contributing to CommandNotch.

Before You Start

Use macOS 14+.
Install Xcode 16+.
Install xcodegen with Homebrew.

Local Setup

cd CommandNotch
xcodegen generate --spec project.yml
open CommandNotch.xcodeproj

Useful Commands

Generate the project:

cd CommandNotch
xcodegen generate --spec project.yml

Build:

cd CommandNotch
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer \
  xcodebuild build -project CommandNotch.xcodeproj -scheme CommandNotch -destination 'platform=macOS'

Run tests:

cd CommandNotch
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer \
  xcodebuild test -project CommandNotch.xcodeproj -scheme CommandNotch -destination 'platform=macOS'

What Helps Most

Bug fixes with a clear reproduction path.
UI polish that keeps the app feeling intentional instead of generic.
Accessibility improvements.
Tests around workspace, screen, settings, and hotkey behavior.
Docs and onboarding improvements.

Code Guidelines

Keep changes targeted.
Preserve the existing SwiftUI + AppKit split.
Prefer typed settings and explicit state ownership over hidden side effects.
Add or update tests when you change behavior.
Regenerate the Xcode project with XcodeGen if you add or remove files.

Pull Requests

Keep PRs small enough to review comfortably.
Explain the user-facing impact.
Note any follow-up work or tradeoffs.
Include screenshots for visible UI changes when possible.
Mention the exact build/test command you used.

Issues

When filing a bug, include:

macOS version
what you expected
what actually happened
reproduction steps
screenshots or recordings if they help

Media Updates

README screenshots live in .github/assets/.

If you update the UI significantly, refresh:

.github/assets/CommandNotch-Open.png
.github/assets/CommandNotch-Settings.png

License

By contributing, you agree that your contributions will be released under the MIT License in this repository.

2.0 KiB Raw Permalink Blame History