How to Contribute to makeplane/plane: A Complete Guide for Open Source Developers

You can contribute to makeplane/plane by forking the repository, running the automated setup.sh script to configure the Django backend and React frontend locally, then following the conventional commit workflow to submit pull requests that pass OxLint checks and pytest suites.

Plane is an open-source project management platform built as a monorepo combining a Django REST API backend with a React/TypeScript frontend. Whether you want to fix bugs, add features, or improve documentation, understanding the repository structure and contribution workflow is essential before you open your first pull request.

Repository Architecture Overview

The makeplane/plane repository uses pnpm workspaces to manage a complex monorepo structure. Before contributing, familiarize yourself with these key directories:

• apps/api/ – Django 5.x backend with PostgreSQL and Redis dependencies
• packages/ui/ – Core React component library (@plane/ui)
• packages/i18n/ – Internationalization utilities and locale files
• packages/editor/ – Rich text editor components
• setup.sh – Automated bootstrap script for local development

The project enforces strict code quality through OxLint and Oxfmt configurations defined in .oxlintrc.json and .oxfmtrc.json at the repository root.

Local Development Environment Setup

Getting the development stack running requires Docker for the backend services and pnpm for the frontend tooling.

First, fork and clone the repository:

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

Execute the setup script to create environment files and build Docker images:

chmod +x setup.sh
./setup.sh

Start the backend infrastructure using the local Docker composition:

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

In a separate terminal, launch the frontend development servers:

pnpm dev

Access the applications at:

• Admin UI: http://localhost:3001/god-mode/ (create an instance admin account here)
• Main Application: http://localhost:3000 (log in with admin credentials)

All local development procedures are documented in the repository's CONTRIBUTING.md file.

Contribution Workflow

The makeplane/plane project follows a structured seven-step contribution process enforced by GitHub Actions CI.

Opening Issues

Before writing code, search existing issues to avoid duplicates. If creating a new issue, use the proper emoji prefix format defined in CONTRIBUTING.md:

• 🐛 for bugs
• 🚀 for features
• 🛠️ for improvements
• 📘 for documentation

Branch Naming Conventions

Create feature branches using the format type/short-description:

git checkout -b bug/api-token-expiry

Valid types include bug, feature, improvement, or docs.

Coding Standards

All code must pass OxLint analysis and Oxfmt formatting. Run these commands before committing:

pnpm check   # Runs linting and type-checking

pnpm fix     # Auto-formats code according to .oxfmtrc.json rules

The project follows conventional commit style messages (e.g., fix(api): resolve token expiry issue).

Backend Contributions

Backend development targets the Django application in apps/api/. When modifying models, serializers, or views:

1. Edit files under apps/api/
2. Add corresponding pytest files under apps/api/tests/
3. Run the backend test suite via Docker:

docker compose -f docker-compose-test.yml up --build

Refer to apps/api/tests/TESTING_GUIDE.md for fixture usage and testing conventions specific to the Django backend.

Frontend Contributions

Frontend changes involve the React/TypeScript packages under packages/. When modifying UI components:

1. Edit TypeScript components in the appropriate package (e.g., packages/ui/)
2. Add .test.tsx files alongside components using Jest and React Testing Library
3. Run frontend-specific tests:

pnpm test packages/ui

The frontend enforces strict TypeScript configuration shared across all workspaces.

Contributing Translations

Plane supports internationalization through the @plane/i18n package. To add a new translation key:

First, update the English locale file:

// packages/i18n/src/locales/en/translations.json
{
  "cycle": {
    "create": "Add new cycle"
  }
}

Then add the French counterpart:

// packages/i18n/src/locales/fr/translations.json
{
  "cycle": {
    "create": "Ajouter un nouveau cycle"
  }
}

If adding a new top-level language, update the type definition in packages/i18n/src/types/language.ts:

export type TLanguage = "en" | "fr" | "your-lang";

Validate your changes by running:

pnpm test packages/i18n

Translation guidelines are detailed in the "Contributing to language support" section of CONTRIBUTING.md.

Testing and Validation

Every contribution must pass the full CI pipeline locally before submitting a pull request:

1. Lint and type-check: pnpm check
2. Unit tests: pnpm test (frontend) and docker compose -f docker-compose-test.yml up (backend)
3. Format verification: Ensure pnpm fix makes no further changes

The GitHub Actions CI runs these same checks on every pull request targeting the main branch.

Summary

• Fork and clone the repository, then run ./setup.sh to bootstrap the Docker and pnpm environment
• Follow the monorepo structure: Backend code lives in apps/api/, frontend packages in packages/
• Use conventional tooling: OxLint for linting, conventional commits for messages, and emoji prefixes for issues
• Test thoroughly: Run pnpm check, pnpm test, and Docker-based pytest suites before submitting
• Reference issues in pull requests using Closes #123 syntax and follow the template in .github/PULL_REQUEST_TEMPLATE.md

Frequently Asked Questions

Do I need Docker to contribute to makeplane/plane?

Yes, Docker is required for local development. The backend depends on PostgreSQL and Redis services defined in docker-compose-local.yml. The setup.sh script automatically configures these containers, but you must have Docker installed and running before executing the setup commands.

What programming languages should I know to contribute?

You should know Python for backend contributions (Django REST framework) and TypeScript/React for frontend work. The project also uses pnpm for package management and OxLint for JavaScript/TypeScript linting. For translation work, you only need to edit JSON files, but understanding TypeScript types in packages/i18n/src/types/ is helpful.

How do I format my code before submitting a pull request?

Run pnpm fix from the repository root before committing. This command executes Oxfmt according to the rules in .oxfmtrc.json and automatically fixes formatting issues. For Python backend code, ensure your changes follow PEP 8 standards as verified by the CI pipeline.

Can I contribute without writing code?

Yes, non-code contributions are welcome. You can improve documentation by editing markdown files in the repository or the separate docs site at docs.plane.so, report bugs using the 🐛 emoji prefix in issues, or help with translations by adding locale files to packages/i18n/src/locales/. All contribution types follow the same workflow outlined in CONTRIBUTING.md.

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