# How to Contribute to the Palmier Pro Project: A Complete Developer Guide

> Contribute to the Palmier Pro project by forking the repository, building the Swift package on Apple Silicon, and submitting focused pull requests linked to GitHub Issues. Your guide to developer contributions.

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

---

**To contribute to the Palmier Pro project, fork the `palmier-io/palmier-pro` repository, build the Swift 6.2 package on macOS 26 Apple Silicon, and submit focused pull requests linked to GitHub Issues after running `swift test`.**

Palmier Pro is an AI-native, Swift-only video editor designed exclusively for macOS 26. If you are looking to contribute to the Palmier Pro project, this guide covers the complete workflow from cloning the repository to submitting your first pull request, based on the actual source code structure and development practices used by the maintainers.

## Prerequisites and Development Environment

### System Requirements

The codebase requires **macOS 26** running on **Apple Silicon**. The [`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift) explicitly declares `.macOS(.v26)` as the minimum platform target, and the project utilizes **Swift 6.2** language features. You cannot build or run this project on Intel-based Macs or earlier macOS versions.

### Clone and Build

Start by cloning the repository and verifying your build environment compiles correctly.

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

```

Compile the executable and launch the application:

```bash
swift build          # compile the executable

swift run            # launches the app in a console window

```

For debug builds with streaming `OSLog` output, use the development script:

```bash
./scripts/dev.sh

```

Run the comprehensive test suite to ensure all systems function correctly:

```bash
swift test

```

All unit tests reside under `Tests/PalmierProTests` and exercise timeline mathematics, transcription search algorithms, and application startup smoke tests.

## Understanding the Codebase Architecture

Palmier Pro organizes functionality into seven distinct modules within the `Sources/PalmierPro/` directory. Each module serves a specific purpose in the video editing pipeline:

- **App**: Entry point, update handling, and global state management located in [`Sources/PalmierPro/App/main.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/App/main.swift)
- **Editor**: 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**: Real-time video rendering pipeline in [`Sources/PalmierPro/Preview/VideoEngine.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Preview/VideoEngine.swift)
- **Generation**: AI-generated media backend in [`Sources/PalmierPro/Generation/GenerationService.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Generation/GenerationService.swift)
- **Agent**: 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**: Shared helpers including logging and caching in [`Sources/PalmierPro/Utilities/Log.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Utilities/Log.swift)
- **Settings**: Preference panes in [`Sources/PalmierPro/Settings/SettingsView.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Settings/SettingsView.swift)

The project bundles external dependencies including **DSWaveformImage**, **MCP SDK**, **Sparkle**, **Sentry**, and **Lottie** through the [`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift)宣言, while internal resources like fonts and images are copied via the `resources` array.

## Step-by-Step Contribution Workflow

Follow this seven-step process to ensure your contribution meets the project's standards and review criteria:

1. **Open an Issue**: Propose bug fixes or features via GitHub Issues before writing code. Maintainers prioritize work that has public discussion and design alignment.

2. **Fork the Repository**: Create your own copy on GitHub to keep the main line clean and allow unrestricted pushing.

3. **Create a Feature Branch**: Isolate changes with descriptive branch names:
   ```bash
   git checkout -b my-feature-name
   ```

4. **Implement and Test**: Edit source files in the appropriate module, add unit tests if modifying logic, and verify with `swift test` to prevent regressions.

5. **Commit Changes**: Follow conventional commit style (e.g., `feat: add speed adjustment tool`) to support automated changelog generation.

6. **Open a Pull Request**: Target the `main` branch of the upstream repository. Continuous integration runs automatically on submission.

7. **Respond to Review**: Address feedback regarding code style, architecture patterns, and test coverage standards.

> **Note**: The maintainers have limited bandwidth for large unsolicited PRs. Start with an issue and keep changes focused and atomic.

## Practical Example: Adding a New Editor Tool

This example demonstrates adding a "SpeedUp" tool to the editor toolbar, illustrating how to extend the `Editor` module while following the centralized `AppTheme` system.

First, create the tool view in [`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")
    }
}

```

Next, register the tool in the existing toolbar implementation:

```swift
// In Sources/PalmierPro/Editor/ToolbarView.swift
import SwiftUI

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

```

Finally, implement the business logic in the central editor model:

```swift
// In Sources/PalmierPro/Editor/EditorState.swift
extension EditorState {
    func increasePlaybackSpeed() {
        playbackRate = min(playbackRate * 1.25, 4.0)   // caps at 4×
    }
}

```

Verify the implementation compiles and passes existing tests:

```bash
swift test

```

If adding unit tests for the new method, create [`SpeedUpToolTests.swift`](https://github.com/palmier-io/palmier-pro/blob/main/SpeedUpToolTests.swift) under `Tests/PalmierProTests` and assert that the playback rate caps correctly at 4×.

## Essential Files for Contributors

Understanding these key files accelerates the contribution process and prevents architectural mismatches:

- **[`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift)**: Declares platforms, dependencies (DSWaveformImage, MCP SDK), and bundled resources like fonts and MCP configuration files
- **[`CONTRIBUTING.md`](https://github.com/palmier-io/palmier-pro/blob/main/CONTRIBUTING.md)**: Official workflow guide, licensing information, and community standards
- **[`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)**: Orchestrates AI-generated media including video trimming and image-to-video conversion
- **[`Sources/PalmierPro/Agent/AgentService.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Agent/AgentService.swift)**: Implements the MCP server and client adapters for Claude, Cursor, and other AI assistants
- **[`Tests/PalmierProTests/SmokeTests.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Tests/PalmierProTests/SmokeTests.swift)**: Sanity checks for application launch and service initialization

## Summary

- **Palmier Pro** requires macOS 26 on Apple Silicon and Swift 6.2 to build and run
- The modular architecture separates concerns across `App`, `Editor`, `Generation`, `Agent`, and `Utilities` modules
- Always open a GitHub Issue before starting work to align with maintainer priorities and design direction
- Run `swift test` before submitting PRs to prevent regressions in timeline math and transcription features
- Follow conventional commit styles and target the `main` branch for all pull requests
- New UI components must integrate with the centralized `AppTheme` system for consistent styling

## Frequently Asked Questions

### What macOS version do I need to build Palmier Pro?

You need **macOS 26** running on **Apple Silicon**. The [`Package.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Package.swift) explicitly sets `.macOS(.v26)` as the minimum platform target, and the codebase utilizes Swift 6.2 features unavailable on earlier operating systems or Intel architectures.

### Where should I implement new AI generation features?

Place AI-generated media logic in [`Sources/PalmierPro/Generation/GenerationService.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Generation/GenerationService.swift). This module handles video trimming, image-to-video conversion, and other AI operations. Ensure new features integrate with the existing service architecture and include corresponding tests in `Tests/PalmierProTests`.

### Do I need to open an issue before submitting a pull request?

Yes. The maintainers prioritize contributions that begin with a GitHub Issue discussion. Opening an issue allows the team to provide design guidance, prevents duplicate work, and ensures your approach aligns with the project's roadmap. Large unsolicited PRs without prior discussion face limited review bandwidth.

### How do I run the development build with full logging?

Use the provided development script [`./scripts/dev.sh`](https://github.com/palmier-io/palmier-pro/blob/main/./scripts/dev.sh) from the repository root. This script builds the application and streams `OSLog` output to your console, providing real-time debugging information beyond what standard `swift run` execution offers.