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

> Contribute to makeplane/plane easily. Fork the repo, set up locally with setup.sh, and submit pull requests following conventional commits and passing tests. Start contributing today.

- Repository: [Plane/plane](https://github.com/makeplane/plane)
- Tags: how-to-guide
- Published: 2026-08-25

---

**You can contribute to makeplane/plane by forking the repository, running the automated [`setup.sh`](https://github.com/makeplane/plane/blob/main/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`](https://github.com/makeplane/plane/blob/main/setup.sh)** – Automated bootstrap script for local development

The project enforces strict code quality through **OxLint** and **Oxfmt** configurations defined in [`.oxlintrc.json`](https://github.com/makeplane/plane/blob/main/.oxlintrc.json) and [`.oxfmtrc.json`](https://github.com/makeplane/plane/blob/main/.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:

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

```

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

```bash
chmod +x setup.sh
./setup.sh

```

Start the backend infrastructure using the local Docker composition:

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

```

In a separate terminal, launch the frontend development servers:

```bash
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`](https://github.com/makeplane/plane/blob/main/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`](https://github.com/makeplane/plane/blob/main/CONTRIBUTING.md)**:
- 🐛 for bugs
- 🚀 for features  
- 🛠️ for improvements
- 📘 for documentation

### Branch Naming Conventions

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

```bash
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:

```bash
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:

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

```

Refer to **[`apps/api/tests/TESTING_GUIDE.md`](https://github.com/makeplane/plane/blob/main/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`](https://github.com/makeplane/plane/blob/main/.test.tsx) files alongside components using Jest and React Testing Library
3. Run frontend-specific tests:

```bash
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:

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

```

Then add the French counterpart:

```json
// 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`](https://github.com/makeplane/plane/blob/main/packages/i18n/src/types/language.ts):

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

```

Validate your changes by running:

```bash
pnpm test packages/i18n

```

Translation guidelines are detailed in the "Contributing to language support" section of **[`CONTRIBUTING.md`](https://github.com/makeplane/plane/blob/main/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`](https://github.com/makeplane/plane/blob/main/./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`](https://github.com/makeplane/plane/blob/main/.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`](https://github.com/makeplane/plane/blob/main/docker-compose-local.yml). The [`setup.sh`](https://github.com/makeplane/plane/blob/main/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`](https://github.com/makeplane/plane/blob/main/.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`](https://github.com/makeplane/plane/blob/main/CONTRIBUTING.md)**.