Skip to main content
Thank you for your interest in contributing to Ora Browser! This guide covers everything you need to know about contributing code, reporting issues, and working with the community.

​
AI Assistance Disclosure

If you use any kind of AI assistance to contribute, you must disclose this in your pull request, commit, or issue.
When using AI assistance, please include:
  • Extent of use: Did AI help with documentation only, or did it generate code?
  • Response generation: Are PR comments or commit messages AI-generated?
  • Understanding: You must understand the code produced and be able to answer questions about it
Exception: Trivial tab-completion of single keywords or short phrases doesn’t need disclosure. Why we require this: Maintainers shouldn’t have to review PRs so broken that they require significant rework. If you use AI, we expect you to verify and understand what it produces.

​
Getting Started

​
Prerequisites

Before contributing, ensure you have:

​
Check for Existing Work

1

Search Existing Issues

Before starting work, search existing issues to ensure no one else is already working on the same feature or bug.
2

Comment on Issues

If you plan to work on an issue, comment to indicate you’re working on it. This prevents duplicate effort.
3

Open a Discussion (Optional)

For major changes or new features, consider opening an issue first to discuss the approach with maintainers.

​
Code Standards

​
Formatting and Linting

Code quality is automatically enforced via git hooks (installed by ./scripts/setup.sh): SwiftFormat: Handles code formatting 
swiftformat . --quiet
SwiftLint: Enforces coding standards 
swiftlint --quiet
These tools run automatically on every commit. You can also run them manually: 
# Format all Swift files
swiftformat . --quiet

# Check for linting issues
swiftlint --quiet

# Auto-fix linting issues
swiftlint --fix
Git hooks are configured in lefthook.yml and automatically format your code before each commit.

​
Coding Conventions

Follow existing patterns: Review similar code in the codebase to understand established patterns. Use modern Swift/SwiftUI APIs: Prefer newer APIs when possible, but maintain backward compatibility. File organization: Place files in the appropriate directory:
  • Models go in Models/
  • Services go in Services/
  • Reusable UI components go in UI/
  • Feature modules go in Modules/
Swift style:
  • Use clear, descriptive names
  • Prefer let over var when possible
  • Use type inference where it improves readability
  • Document complex logic with comments

​
Compatibility & OS Versions

Current minimum deployment target: macOS 15.0
Maintain backward compatibility. Don’t use APIs that raise the minimum OS version without discussion.
If a feature requires a newer OS version:
  1. Use @available or #if available checks to preserve compatibility
  2. Provide fallback behavior for older OS versions
  3. Open an issue to discuss trade-offs if raising the minimum version would significantly benefit the feature
Example: 
if #available(macOS 15.0, *) {
    // Use new API
} else {
    // Fallback for older versions
}

​
Project Configuration

This project uses XcodeGen. Never manually edit project settings in Xcode. To modify project settings:
1

Edit project.yml

Make changes to project.yml in the repository root.
2

Regenerate the project

Run xcodegen to regenerate Ora.xcodeproj:
xcodegen
3

Commit both files

Commit both project.yml and the regenerated Ora.xcodeproj.

​
Testing & Quality

​
Running Tests

In Xcode: Press ⌘U (Product → Test) Via CLI: 
xcodebuild test -scheme ora -destination "platform=macOS"

​
Requirements

All pull requests must meet these requirements:
  • All existing tests pass
  • New features include appropriate tests
  • Code builds without warnings
  • Code follows formatting standards (automatic via git hooks)

​
Security & Safety

Never commit private keys or sensitive data. See SECURITY.md for details.
Security best practices:
  • Be mindful of user privacy and data handling
  • Follow secure coding practices for web content handling
  • Never commit .env files or private keys
  • Use .gitignore to exclude sensitive files
  • Review what you’re committing with git status and git diff
If you discover a security issue, see SECURITY.md for responsible disclosure.

​
Pull Request Process

​
Before You Start

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/browser.git
cd browser
  3. Run setup: 
    ./scripts/setup.sh

​
Creating a Pull Request

1

Create a feature branch

Create a branch from main with a descriptive name:
git checkout -b feature/your-feature-name
Branch naming conventions:
  • feature/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation changes
  • refactor/ - Code refactoring
2

Make your changes

Write your code, following the coding standards above.Commit frequently with clear, descriptive messages:
git add .
git commit -m "Add tab grouping feature"
Git hooks will automatically:
  • Format your code with SwiftFormat
  • Lint your code with SwiftLint
  • Stage any auto-fixes
3

Test your changes

Run tests to ensure nothing breaks:
xcodebuild test -scheme ora -destination "platform=macOS"
Or press ⌘U in Xcode.
4

Push to your fork

Push your branch to your fork:
git push origin feature/your-feature-name
5

Open a pull request

  1. Go to the Ora Browser repository
  2. Click “Pull requests” → “New pull request”
  3. Click “compare across forks”
  4. Select your fork and branch
  5. Fill out the PR template

​
PR Requirements Checklist

Your pull request must:
  • Build successfully without errors or warnings
  • Tests pass (all existing tests + new tests if applicable)
  • Follow formatting standards (automatic via git hooks)
  • Have a descriptive title and description explaining what changed and why
  • Include screenshots if UI changes were made
  • Reference related issues (e.g., “Fixes #123” or “Closes #456”)
  • Disclose AI assistance if any was used
  • Check for duplicate functionality (ensure similar features don’t already exist)

​
PR Description Template

Use this template for your PR description: 
## Summary
Brief description of what this PR does.

## Changes
- Change 1
- Change 2
- Change 3

## Testing
How did you test these changes?

## Screenshots (if applicable)
[Add screenshots here]

## Related Issues
Fixes #123

## AI Assistance
[Disclose any AI assistance used]

​
Review Process

Once you submit a PR:
  1. Automated checks run: GitHub Actions runs tests and checks
  2. Maintainers review: Maintainers will review your code and provide feedback
  3. Address feedback: Make requested changes and push updates
  4. Approval: Once approved, a maintainer will merge your PR
Be patient and respectful during the review process. Maintainers are volunteers and review PRs as time permits.

​
Reporting Issues

​
Bug Reports

Be descriptive and thorough. A good bug report includes:
1

Environment details

  • macOS version (e.g., macOS 15.2)
  • Ora Browser version (e.g., 0.2.11)
  • Hardware (Intel or Apple Silicon)
2

Clear reproduction steps

Step-by-step instructions to reproduce the issue:
  1. Open Ora Browser
  2. Navigate to example.com
  3. Click the bookmark button
  4. Observe the error
3

Expected vs actual behavior

  • Expected: The page should be bookmarked
  • Actual: The app crashes
4

Screenshots or videos

Include screenshots or screen recordings if applicable.
5

Console logs or error messages

Include relevant console output or error messages.

​
Feature Requests

Provide detailed context. A good feature request includes:
  • Clear description: What feature do you want and why?
  • Use case: How would this feature be used?
  • Alignment with goals: How does it fit with Ora’s vision (fast, secure, beautiful)?
  • Implementation ideas: Suggestions for how it could work
  • Uniqueness: Check that similar functionality doesn’t already exist
Example: 
## Feature Request: Tab Groups

**Description**: Add the ability to group tabs into named collections.

**Use Case**: Power users with many tabs open would benefit from organizing 
tabs by project or topic (e.g., "Work", "Research", "Shopping").

**Alignment**: This fits Ora's goal of being fast and efficient by helping 
users manage tab overload.

**Implementation Ideas**: Could use a sidebar section with expandable groups.

​
Community Guidelines

Ora Browser is an open-source project that thrives on respectful collaboration.
Be respectful and constructive:
  • Treat all contributors with respect
  • Provide constructive feedback
  • Focus on the code and ideas, not individuals
  • Help maintain a welcoming environment
Code of Conduct: See CODE_OF_CONDUCT.md for detailed community standards.

​
Release Process

This section is for maintainers with release permissions. Contributors don’t need to worry about releases.

​
Creating a Release

Ora uses Sparkle for automatic updates.
1

Add Sparkle dependency

Sparkle is already configured in project.yml:
packages:
  Sparkle:
    url: https://github.com/sparkle-project/Sparkle
    from: 2.6.0
2

Setup Sparkle tools

Install Sparkle command-line tools:
brew install --cask sparkle
./scripts/setup-sparkle.sh
This generates DSA keys in the build/ directory.
3

Configure signing

Copy the public key from build/dsa_pub.pem to Info.plist as SUPublicEDKey.Keep build/dsa_priv.pem secure—it signs releases.
4

Create a release

Run the release script:
./scripts/create-release.sh 0.2.12 build/dsa_priv.pem
This builds, signs, and prepares release files in build/.
5

Upload release

  1. Upload build/appcast.xml to GitHub Pages or your hosting
  2. Upload build/Ora-Browser.dmg to GitHub releases
  3. Update SUFeedURL in Info.plist to point to your appcast.xml
For detailed hosting setup, see the wiki.

​
Resources

Development Setup

Complete environment setup guide

Architecture

Learn about Ora’s architecture

Hot Reloading

Set up live SwiftUI updates

Discord Community

Join the community on Discord

GitHub Repository

View source code and issues

Security Guide

Security practices and disclosure

​
Questions?

Join the community on Discord or open an issue for discussion.
By contributing to Ora Browser, you agree that your contributions will be licensed under the GPL-2.0 License.

Build docs developers (and LLMs) love

Get started for freeTalk to us