Contributing to PasteClip

February 28, 2026 · View on GitHub

Thank you for your interest in contributing to PasteClip! 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>/PasteClip.git
cd PasteClip

  2. Generate the Xcode project:

    xcodegen generate

  3. Open in Xcode:

    open PasteClip.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:

PasteClip/
├── 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 PasteClip.xcodeproj -scheme PasteClip -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.