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

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 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.

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

Compile the executable and launch the application:

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:

./scripts/dev.sh

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

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
• Editor: Window controller and timeline UI logic in Sources/PalmierPro/Editor/EditorWindowController.swift
• Preview: Real-time video rendering pipeline in Sources/PalmierPro/Preview/VideoEngine.swift
• Generation: AI-generated media backend in Sources/PalmierPro/Generation/GenerationService.swift
• Agent: MCP server and client adapters for Claude and Cursor in Sources/PalmierPro/Agent/AgentService.swift
• Utilities: Shared helpers including logging and caching in Sources/PalmierPro/Utilities/Log.swift
• Settings: Preference panes in Sources/PalmierPro/Settings/SettingsView.swift

The project bundles external dependencies including DSWaveformImage, MCP SDK, Sparkle, Sentry, and Lottie through the 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:

   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:

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:

// 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:

// 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:

swift test

If adding unit tests for the new method, create 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: Declares platforms, dependencies (DSWaveformImage, MCP SDK), and bundled resources like fonts and MCP configuration files
• CONTRIBUTING.md: Official workflow guide, licensing information, and community standards
• Sources/PalmierPro/App/main.swift: Application entry point that registers the main window and MCP server
• Sources/PalmierPro/Editor/EditorWindowController.swift: Core UI controller hosting the timeline, video preview, and toolbars
• Sources/PalmierPro/Generation/GenerationService.swift: Orchestrates AI-generated media including video trimming and image-to-video conversion
• Sources/PalmierPro/Agent/AgentService.swift: Implements the MCP server and client adapters for Claude, Cursor, and other AI assistants
• 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 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}