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

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. 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.
• Editor – Contains the window controller and timeline UI logic in Sources/PalmierPro/Editor/EditorWindowController.swift.
• Preview – Manages real-time video rendering via Sources/PalmierPro/Preview/VideoEngine.swift.
• Generation – Orchestrates AI-generated media operations in Sources/PalmierPro/Generation/GenerationService.swift.
• Agent – Implements the MCP server and client adapters for Claude and Cursor in Sources/PalmierPro/Agent/AgentService.swift.
• Utilities – Provides shared helpers for logging, caching, and keychain access in Sources/PalmierPro/Utilities/Log.swift.
• Settings – Renders preference panes in 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:

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

Launch the application directly from the terminal:

swift run

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

./scripts/dev.sh

Run the Test Suite

Execute the unit test suite to ensure baseline functionality:

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:

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.

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:

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 to include the new tool:

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:

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

Step 4: Verify

Run the test suite to check for regressions:

swift test

If you added logic that requires validation, create 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 – Declares external dependencies (DSWaveformImage, MCP SDK), platform targets, and bundled resources like fonts and images.
• CONTRIBUTING.md – Official guide covering issue templates, licensing, and the full development workflow.
• 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 – Backend service for AI-generated media operations.
• Sources/PalmierPro/Agent/AgentService.swift – Manages Model Context Protocol server connections and AI agent adapters.
• 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 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 to include the new package URL and version, then add the corresponding product to the PalmierPro target's dependency list. After modifying 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) 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 or 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.

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