# How to Contribute to the Palmier Pro Project: A Complete Guide for New Contributors

> Learn how to contribute to the Palmier Pro project. Follow our guide to fork the repo, branch, code in Swift, test, and submit your pull request easily.

- Repository: [Palmier/palmier-pro](https://github.com/palmier-io/palmier-pro)
- Tags: how-to-guide
- Published: 2026-06-23

---

**To contribute to Palmier Pro, fork the repository, create a feature branch, implement your changes in the appropriate Swift module, run `swift test`, and submit a pull request linked to a GitHub Issue.**

Palmier Pro is an **AI-native, Swift-only video editor** built exclusively for macOS 26 on Apple Silicon. The project is structured as a single Swift package that integrates third-party libraries like DSWaveformImage and the Model Context Protocol SDK. Whether you are fixing a bug in the timeline or adding a new AI generation feature, understanding the modular architecture and contribution workflow ensures your changes merge smoothly.

## Understanding the Palmier Pro Architecture

The codebase follows a clean modular layout defined in [`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift). Each module serves a distinct purpose in the video editing pipeline.

### Core Modules

- **App** – Handles the entry point, update handling, and global state in [`Sources/PalmierPro/App/main.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/App/main.swift).
- **Editor** – Contains the window controller and timeline UI logic in [`Sources/PalmierPro/Editor/EditorWindowController.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Editor/EditorWindowController.swift).
- **Preview** – Manages real-time video rendering via [`Sources/PalmierPro/Preview/VideoEngine.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Preview/VideoEngine.swift).
- **Generation** – Orchestrates AI-generated media operations in [`Sources/PalmierPro/Generation/GenerationService.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Generation/GenerationService.swift).
- **Agent** – Implements the MCP server and client adapters for Claude and Cursor in [`Sources/PalmierPro/Agent/AgentService.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Agent/AgentService.swift).
- **Utilities** – Provides shared helpers for logging, caching, and keychain access in [`Sources/PalmierPro/Utilities/Log.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Utilities/Log.swift).
- **Settings** – Renders preference panes in [`Sources/PalmierPro/Settings/SettingsView.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Settings/SettingsView.swift).

All UI styling follows the centralized `AppTheme` system, and the project targets **Swift 6.2** with a minimum platform requirement of macOS 26 (`.macOS(.v26)`).

## Setting Up Your Development Environment

Before contributing to Palmier Pro, verify your system runs macOS 26 and has Swift 6.2 installed.

### Clone and Build

Run the following commands to clone the repository and compile the executable:

```bash
git clone https://github.com/palmier-io/palmier-pro.git
cd palmier-pro
swift build

```

Launch the application directly from the terminal:

```bash
swift run

```

For a full-featured debug build that streams `OSLog` output, use the provided helper script:

```bash
./scripts/dev.sh

```

### Run the Test Suite

Execute the unit test suite to ensure baseline functionality:

```bash
swift test

```

All tests reside under `Tests/PalmierProTests` and cover timeline math, transcription search, and app startup smoke tests.

## Contribution Workflow

The Palmier Pro project follows a structured seven-step workflow to maintain code quality and architectural consistency.

### 1. Open an Issue

Use GitHub Issues to propose bug fixes, features, or design questions. Maintainers prioritize work that has a public discussion thread, reducing the risk of rejected pull requests.

### 2. Fork and Branch

Fork the repository on GitHub, then create an isolated feature branch:

```bash
git checkout -b my-feature-name

```

### 3. Implement and Test

Edit source files within the appropriate module (e.g., `Editor` for UI changes or `Generation` for AI features). Add unit tests if your change affects business logic, then verify with `swift test`.

### 4. Commit and Push

Follow conventional commit style (e.g., `feat: add playback speed control`). Clear messages help automated changelogs and code review.

```bash
git push origin my-feature-name

```

### 5. Open a Pull Request

Target the `main` branch of the upstream repository. CI runs automatically, and reviewers will comment on style, architecture, and test coverage.

### 6. Respond to Review

Address feedback by pushing additional commits to your branch. Iteration ensures your contribution meets the project's standards.

> **Note:** The maintainers have limited bandwidth for large unsolicited PRs. Starting with an issue and keeping changes focused significantly increases merge probability.

## Example: Adding a New Editor Tool

The following example demonstrates how to add a "SpeedUp" tool button to the editor toolbar, illustrating where new UI code lives and how to wire it into existing architecture.

### Step 1: Create the Tool View

Create [`Sources/PalmierPro/Editor/ToolSpeedUp.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Editor/ToolSpeedUp.swift):

```swift
import SwiftUI
import AppTheme

struct SpeedUpTool: View {
    @EnvironmentObject var editor: EditorState

    var body: some View {
        Button(action: { editor.increasePlaybackSpeed() }) {
            Image(systemName: "tortoise.fill")
                .foregroundColor(AppTheme.Text.primary)
        }
        .help("Speed up playback")
    }
}

```

### Step 2: Register in the Toolbar

Modify [`ToolbarView.swift`](https://github.com/palmier-io/palmier-pro/blob/main/ToolbarView.swift) to include the new tool:

```swift
import SwiftUI

struct ToolbarView: View {
    var body: some View {
        HStack(spacing: AppTheme.Spacing.m) {
            // Existing tools ...
            SpeedUpTool()
        }
        .padding(AppTheme.Spacing.s)
    }
}

```

### Step 3: Implement Business Logic

Extend the central editor model in [`Sources/PalmierPro/Editor/EditorState.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Editor/EditorState.swift):

```swift
extension EditorState {
    func increasePlaybackSpeed() {
        playbackRate = min(playbackRate * 1.25, 4.0)
    }
}

```

### Step 4: Verify

Run the test suite to check for regressions:

```bash
swift test

```

If you added logic that requires validation, create [`SpeedUpToolTests.swift`](https://github.com/palmier-io/palmier-pro/blob/main/SpeedUpToolTests.swift) under `Tests/PalmierProTests` to assert the rate caps correctly at 4×.

## Key Source Files Every Contributor Should Know

Understanding these files accelerates onboarding and helps you locate relevant code quickly.

- **[`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift)** – Declares external dependencies (DSWaveformImage, MCP SDK), platform targets, and bundled resources like fonts and images.
- **[`CONTRIBUTING.md`](https://github.com/palmier-io/palmier-pro/blob/main/CONTRIBUTING.md)** – Official guide covering issue templates, licensing, and the full development workflow.
- **[`Sources/PalmierPro/App/main.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/App/main.swift)** – Application entry point that registers the main window and MCP server.
- **[`Sources/PalmierPro/Editor/EditorWindowController.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Editor/EditorWindowController.swift)** – Core UI controller hosting the timeline, video preview, and toolbars.
- **[`Sources/PalmierPro/Generation/GenerationService.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Generation/GenerationService.swift)** – Backend service for AI-generated media operations.
- **[`Sources/PalmierPro/Agent/AgentService.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Agent/AgentService.swift)** – Manages Model Context Protocol server connections and AI agent adapters.
- **[`Tests/PalmierProTests/SmokeTests.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Tests/PalmierProTests/SmokeTests.swift)** – Sanity checks verifying the app launches and basic services initialize correctly.

## Summary

- Palmier Pro is a Swift 6.2 package targeting macOS 26, organized into modular components like `Editor`, `Generation`, and `Agent`.
- Always start contributions by opening a GitHub Issue to align with maintainers before writing code.
- Use `swift build` and `swift test` locally to verify changes, and follow conventional commit messages for clarity.
- New UI components belong in `Sources/PalmierPro/Editor/` and should integrate with the `AppTheme` system and `EditorState` environment object.
- Unit tests live in `Tests/PalmierProTests` and must pass before submitting a pull request to `main`.

## Frequently Asked Questions

### What are the system requirements for building Palmier Pro?

You need macOS 26 (Apple Silicon) and Swift 6.2. The [`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift) explicitly declares `.macOS(.v26)` as the minimum platform, and the codebase uses Swift 6.2 language features incompatible with earlier versions.

### How do I add a new dependency to the project?

Edit the `dependencies` array in [`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift) to include the new package URL and version, then add the corresponding product to the `PalmierPro` target's dependency list. After modifying [`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift), run `swift build` to resolve and fetch the new dependency.

### Where should I place unit tests for new features?

Create test files under `Tests/PalmierProTests` using the Swift Testing framework or XCTest. Name the file descriptively (e.g., [`SpeedUpToolTests.swift`](https://github.com/palmier-io/palmier-pro/blob/main/SpeedUpToolTests.swift)) and ensure it imports the `@testable import PalmierPro` module to access internal symbols for verification.

### Can I contribute without writing Swift code?

Yes. You can contribute documentation improvements to [`CONTRIBUTING.md`](https://github.com/palmier-io/palmier-pro/blob/main/CONTRIBUTING.md) or [`README.md`](https://github.com/palmier-io/palmier-pro/blob/main/README.md), report bugs via GitHub Issues with detailed reproduction steps, or help with localization assets in the `Resources` directory. All contributions follow the same pull request workflow regardless of file type.