# Contributing to OpenSuperWhisper: Guidelines and Workflow

> Learn how to contribute to OpenSuperWhisper. Follow our guidelines for submitting issues, feature branches, and pull requests to the Starmel/OpenSuperWhisper repository.

- Repository: [Starmel/OpenSuperWhisper](https://github.com/Starmel/OpenSuperWhisper)
- Tags: how-to-guide
- Published: 2026-07-07

---

**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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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:

```bash
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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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:

```bash
./run.sh build

```

Detailed build instructions are available in [`docs/build_whisper.md`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/.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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/.github/workflows/build.yml)
- **Review** the Contribution TODO list in [`Readme.md`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/.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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/ShortcutManager.swift) and update the Xcode project configuration in `OpenSuperWhisper.xcodeproj/project.pbxproj` when adding new source files.