Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
109 lines (76 loc) · 3.75 KB

CONTRIBUTING.md

File metadata and controls

109 lines (76 loc) · 3.75 KB
Raw

Contributing to Clipbara

Thank you for your interest in contributing to Clipbara! This guide will help you get started.

Prerequisites

  • macOS 15.0 (Sequoia) or later
  • Xcode 16.0 or later
  • xcodegen (brew install xcodegen)

Development Setup

  1. Fork and clone the repository:

    git clone https://github.com/<your-username>/Clipbara.git
cd Clipbara

  2. Generate the Xcode project:

    xcodegen generate

  3. Open in Xcode:

    open Clipbara.xcodeproj

  4. Build and run with Cmd + R.

Note: The .xcodeproj is generated by xcodegen and is not tracked in git. Always run xcodegen generate after cloning or pulling changes to project.yml.

Architecture

The project follows a clean separation of concerns:

Clipbara/
├── Models/          # SwiftData models (ClipboardItem)
├── Services/        # Core logic (ClipboardMonitor, PasteService, etc.)
├── Panel/           # NSPanel + NSHostingView hosting layer
├── Views/           # SwiftUI views
├── Utilities/       # Helpers and extensions
└── Resources/       # Assets, Info.plist, entitlements

Key Patterns

Swift 6 Strict Concurrency

This project uses SWIFT_STRICT_CONCURRENCY: complete. All UI-related code must be annotated with @MainActor. Use @Observable for observable classes.

skipNextChange Pattern

When programmatically writing to the clipboard via PasteService, you must call ClipboardMonitor.skipNextChange() beforehand. This prevents the monitor from re-capturing the item that was just pasted.

NSPanel + NSHostingView

The clipboard panel uses a non-activating NSPanel to avoid stealing focus from the frontmost app. SwiftUI views are hosted via NSHostingView.

Code Style

  • Follow existing code conventions in the project
  • Use Swift 6 concurrency features (async/await, @Sendable)
  • Prefer value types (struct, enum) over reference types where appropriate
  • Use SwiftData macros (@Model, #Index, #Unique) for data modeling

Pull Request Process

  1. Create a feature branch from main:

    git checkout -b feature/your-feature-name

  2. Make your changes and test thoroughly.

  3. Ensure the project builds without warnings:

    xcodegen generate
xcodebuild -project Clipbara.xcodeproj -scheme Clipbara -configuration Debug build

  4. Push your branch and open a Pull Request.

  5. Fill out the PR template with a clear description of your changes.

Issue Guidelines

  • Bug reports: Use the bug report template. Include your macOS version, app version, and steps to reproduce.
  • Feature requests: Use the feature request template. Describe the problem you're trying to solve.
  • Questions: Open a discussion or issue with the question label.

Before opening a new issue, please search existing issues to avoid duplicates.

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Contributor License Agreement

Clipbara is dual-licensed: this repository is GPL-3.0, and the copyright holder also distributes a build on the Mac App Store under a separate proprietary license. To keep that possible, by submitting a pull request you agree that:

  1. You are the author of your contribution, or otherwise have the right to submit it.
  2. You license your contribution under the GPL-3.0.
  3. You grant the project maintainer (@mobrava) a perpetual, worldwide, royalty-free right to relicense your contribution as part of official Clipbara distributions, including the Mac App Store build.

If you cannot agree to these terms, please say so in your pull request and we will discuss alternatives.