Contributing to OpenSuperWhisper: Guidelines and Workflow

Contributors should open an issue to discuss changes before forking the repository, creating a feature branch, and submitting a PR to the master branch with proper references and passing CI checks.

OpenSuperWhisper is an open-source macOS transcription application built primarily in Swift. Understanding the contributing guidelines ensures your pull requests align with the project's standards and get merged efficiently.

Open an Issue First

Before writing any code, check existing issues in the repository and create a new one if necessary. The Readme.md (lines 55-58) emphasizes including detailed information such as system version, logs, and screenshots when reporting bugs or requesting features. This step prevents duplicate work and allows maintainers to approve the approach before development begins.

Fork and Branch Workflow

Once your issue is approved or you've identified a known enhancement to work on:

1. Fork the repository to your GitHub account
2. Clone locally and create a feature branch:

git clone https://github.com/Starmel/OpenSuperWhisper.git
cd OpenSuperWhisper
git checkout -b my-feature

Implement Changes and Local Testing

The codebase is primarily Swift with CMake and Objective-C bridging components. When modifying files like OpenSuperWhisper/ShortcutManager.swift (which handles global keyboard shortcuts) or adding new source files that require updates to OpenSuperWhisper.xcodeproj/project.pbxproj, maintain existing coding conventions and add appropriate unit tests.

Verify your build locally before pushing:

./run.sh build

Detailed build instructions are available in docs/build_whisper.md.

Submit a Pull Request

Push your feature branch and open a PR against the master branch. The PR description must reference the related issue using closing keywords (e.g., "Closes #15"). This linking ensures automatic issue closure upon merge and provides context for reviewers.

Continuous Integration Requirements

All submissions undergo automated validation via GitHub Actions configured in .github/workflows/build.yml (lines 52-53). This CI pipeline verifies that changes compile successfully on macOS. Ensure your branch passes these checks before requesting manual review.

Current Contribution Priorities

The Readme.md includes a "Contribution TODO list" (lines 59-67) highlighting high-priority areas where community help is especially welcome:

• Streaming transcription support
• Custom dictionary implementation
• Intel macOS support (currently Apple Silicon only)

Contributors are welcome to work on these specific items or propose entirely new enhancements through the standard issue process.

Summary

• Discuss changes via GitHub issues before coding
• Target the master branch for all pull requests
• Reference issues in PR descriptions using keywords like "Closes #15"
• Follow Swift coding conventions and include unit tests
• Verify builds locally with ./run.sh build and ensure CI passes via .github/workflows/build.yml
• Review the Contribution TODO list in Readme.md for priority features

Frequently Asked Questions

Do I need to open an issue before submitting a PR?

Yes. According to the repository guidelines in Readme.md, contributors must check existing issues and create new ones describing the problem or feature before starting work. This prevents duplicate efforts and ensures your contribution aligns with project goals.

Which branch should I target for pull requests?

Submit all pull requests against the master branch. The repository uses this as the main development branch, and PRs targeting other branches will not be accepted unless specifically requested by maintainers.

How do I verify my changes build correctly?

Run ./run.sh build from the repository root to execute a local build. Additionally, the GitHub Actions workflow defined in .github/workflows/build.yml automatically validates PRs on macOS, so ensure your changes pass CI checks before requesting review.

What programming languages does OpenSuperWhisper use?

The project is primarily written in Swift, with some CMake and Objective-C bridging components. When contributing, maintain the existing code style patterns found in files like OpenSuperWhisper/ShortcutManager.swift and update the Xcode project configuration in OpenSuperWhisper.xcodeproj/project.pbxproj when adding new source files.

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