How to Contribute to Plane Project Development: A Complete Guide for Open-Source Contributors

To contribute to Plane, clone the monorepo, run the automated setup.sh script, start Docker services with docker compose -f docker-compose-local.yml up, and launch the dev server with pnpm dev.

Plane is a popular open-source project management platform built as a monorepo combining a Django REST API with a modern TypeScript/React frontend. If you're looking to contribute to Plane project development, this guide walks you through the exact setup, architecture, and workflow used by the core team — based directly on the source code and official contribution guidelines.

Understanding the Plane Repository Architecture

Before writing code, you need to understand how Plane's codebase is organized. The repository uses a monorepo structure managed by pnpm and Turbo.

Backend: Django REST API

All server-side code lives in apps/api/, a Django project that exposes the REST API consumed by the frontend. Key characteristics:

• Python 3.8+ required
• Postgres 14 and Redis 6.2.7 for data and caching
• Configuration and environment files generated by setup.sh

Frontend: React and TypeScript

The UI is built with React, TypeScript, and a collection of shared internal packages. The main entry point is apps/web/, which consumes packages from the packages/ directory.

Shared Packages

Reusable logic lives in packages/ and is imported across the frontend:

Package	Purpose	Key File
@plane/ui	UI component library	packages/ui/
@plane/i18n	Internationalization	packages/i18n/src/provider/index.tsx
@plane/utils	Helper utilities	packages/utils/src/workspace.ts
@plane/constants	Shared constants	packages/constants/src/workspace.ts
@plane/services	API service layer	packages/services/src/workspace/member.service.ts

The packages/i18n/src/provider/index.tsx file implements language loading and is a common entry point for translation contributions. Similarly, packages/utils/src/workspace.ts contains workspace-related helpers used throughout the UI.

Setting Up Your Local Development Environment

Proper local setup is critical before you can contribute to Plane project development. The maintainers provide an automated script to reduce manual configuration.

Prerequisites

According to CONTRIBUTING.md (Lines 37-44), you need:

• Docker
• Node 20+
• Python 3.8+
• Postgres 14
• Redis 6.2.7
• 12 GB RAM recommended

Step-by-Step Setup

# Clone the repository

git clone https://github.com/makeplane/plane.git plane-repo
cd plane-repo

# Make setup script executable and run it to generate .env files

chmod +x setup.sh
./setup.sh

The setup.sh script automates environment creation and installs dependencies. After it completes, start the infrastructure services:

# Start Postgres, Redis, and other services

docker compose -f docker-compose-local.yml up

Finally, launch the development servers (Lines 73-81):

pnpm dev

Once running, access:

• Admin UI: http://localhost:3001/god-mode/
• Main UI: http://localhost:3000

Finding Your First Contribution Opportunity

Plane follows an issue-first workflow to prevent duplicate work and ensure alignment with project goals.

Using the Issue Tracker

Search existing issues before starting new work. The project uses consistent naming conventions (Lines 18-33):

• 🐛 Bug: ... — Defects and unexpected behavior
• 🚀 Feature: ... — New functionality
• ♻️ Refactor: ... — Code improvements without behavior changes
• 📝 Docs: ... — Documentation updates

If you find a relevant issue, comment to express interest. If no issue exists, create one following these conventions.

Common Contribution Areas (Lines 96-107)

• New integrations — Connect Plane to external tools
• Translations — Add or improve i18n support
• Bug fixes — Resolve reported issues
• Documentation — Improve guides and API references
• UI components — Extend the design system in @plane/ui

Writing Code That Meets Plane's Standards

All contributions must follow the project's coding guidelines (Lines 91-95):

• Unit tests required for all changes
• OxLint configuration enforced via .oxlintrc.json
• oxfmt formatting applied via .oxfmtrc.json

Running Quality Checks

Use the monorepo tooling to validate your changes:

# Type-checking across packages

pnpm check

# Lint all packages

pnpm check:lint

# Run tests for a specific package

pnpm turbo run test --filter=@plane/i18n

Code Examples for Common Contributions

Adding a new translation language:

// packages/i18n/src/constants/language.ts
export const SUPPORTED_LANGUAGES: ILanguageOption[] = [
  { label: "English", value: "en" },
  { label: "Spanish", value: "es" },   // newly added language
];

// packages/i18n/src/locales/es/translations.json
{
  "greeting": "¡Hola, {name}!"
}

Creating a new service in the frontend:

// packages/services/src/workspace/member.service.ts
import { apiClient } from '@plane/utils';

export async function addWorkspaceMember(workspaceId: string, email: string) {
  return apiClient.post(`/workspaces/${workspaceId}/members/`, { email });
}

Submitting Your Pull Request

Once your code is ready and all checks pass locally, push your branch and open a PR. The CI pipeline will automatically run lint, type-checking, and tests.

PR requirements:

• Reference the related issue in the description
• Follow the repository's PR template
• Ensure all CI checks pass

The maintainers review PRs regularly and provide feedback through GitHub's review system.

Summary

• Plane is a monorepo with Django backend (apps/api) and React/TypeScript frontend (apps/web, packages/)
• Setup is automated via setup.sh — run it after cloning, then docker compose and pnpm dev
• Follow the issue-first workflow using the project's naming conventions (🐛 Bug:, 🚀 Feature:, etc.)
• All code requires tests, must pass OxLint, and be formatted with oxfmt
• Use pnpm and Turbo for task running: pnpm check, pnpm check:lint, pnpm turbo run test

Frequently Asked Questions

What programming languages do I need to know to contribute to Plane?

You need Python for the Django backend in apps/api/ and TypeScript/React for the frontend. The frontend uses modern React patterns with a custom component library. Some contributions like translations may require minimal coding, while feature work requires proficiency in both stacks.

How long does local setup typically take?

With the automated setup.sh script, initial setup takes 10-20 minutes depending on your internet connection and whether Docker images need downloading. The script generates .env files and installs dependencies. After initial setup, pnpm dev and docker compose commands start services in under a minute.

Can I contribute without setting up the full backend?

Yes, for purely frontend contributions you can mock the API or use the hosted development environment. However, the full local setup is recommended for any backend changes, integration work, or when modifying API contracts between frontend and backend. The CONTRIBUTING.md guide assumes full local setup for comprehensive testing.

What happens if my PR fails CI checks?

Fix the reported issues and push updates to your branch — the CI will re-run automatically. Common failures include lint errors (run pnpm check:lint locally), type errors (run pnpm check), or missing tests. The pnpm-workspace.yaml defines all packages and their dependencies, so ensure your changes don't break downstream packages.

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