Skip to content

Latest commit

 

History

History
187 lines (126 loc) · 6.57 KB

CONTRIBUTING.md

File metadata and controls

187 lines (126 loc) · 6.57 KB

Contributing Guide

We welcome contributions. You don't need to be an expert in frontend or Python development to help out.

Checklist

Contributions are made through pull requests. Before sending a pull request, make sure to do the following:

Maintainer approval

Contributors must obtain maintainer approval before making pull requests with substantial changes. Substance is not measured only in lines of code. Here is a non-exhaustive list of changes we consider substantial:

  1. changes to the public API;
  2. changes to required or optional dependencies;
  3. changes to CI workflows;
  4. changes with large internal refactors;
  5. changes to our documentation architecture;
  6. changes to default configuration;
  7. opinionated changes to the user interface or user experience;
  8. changes to the semantics of marimo's runtime;
  9. changes to marimo's file format;
  10. changes with many lines of code.

To obtain approval, open a GitHub issue describing the change you would like to make and discuss it with a maintainer. If you would like to make a PR for an issue that already exists, join the conversation in that issue.

Labels. We use GitHub labels to categorize issues into two states:

  • needs discussion — not ready for a PR
  • ready — ready for a PR

If an issue does not have one of these two labels, assume it is not ready for a PR and requires discussion.

Why is maintainer approval required?

Deliberate design. marimo is an intentionally designed project. We put just as much thought into the features we exclude as the ones we include, in order to provide our users with a simple, consistent, delightful, and powerful experience.

For examples of the thought we put in, see our MEPs repo and read our founding essays.

Consistency. Each feature affects the whole product. A change that seems locally helpful can make the system less consistent and therefore harder to learn, explain, or evolve.

Small changes can have large consequences. Unlike traditional software, in open source, some changes are irreversible. Even seemingly minor changes — like adjusting a function signature or adding “just one more option” — can have long-lasting consequences.

Maintenance burden. New features create new work. What may seem like a small change in lines of code can have a disproportionately large maintenance cost when integrated over time.

Review burden. Though the cost of writing code has decreased, the cost of reviewing code has not (in fact, it has increased). Asking a maintainer or community member to review your changes imposes a cost on their time. Building consensus before making the pull request shows respect.

Early consensus prevents wasted effort. Seeking approval before implementing a substantial change increases the chance that your work will be merged.

Setup

Note: We recommend that Windows developers use WSL and clone the marimo repository into the WSL environment and not the Windows mount.

Prerequisites

Getting started

make fe && make py
make dev

This will build the frontend, install Python dependencies in editable mode, and launch the dev server (backend on port 2718, frontend on port 3000).

make dev will suit most development needs: it serves the frontend from Vite, which is faster to iterate on but not identical to production. Use pnpm --dir frontend build:watch when you want a production-like frontend, and marimo -d edit --no-token when you want backend debug logs.

make help lists every development command. The targets are defined in the Makefile.

Host protocol and clients

For changes to host contracts, generated bindings, or client libraries, start with the host protocol contributor guide. It links the Effect definitions, generation commands, and conformance checks.

pre-commit hooks

You can optionally install pre-commit hooks to automatically run the validation checks when making a commit:

uvx pre-commit install

Tests

We have frontend unit tests, Python unit tests, and end-to-end tests. Code changes should be accompanied by unit tests. Some changes should also be accompanied by end-to-end tests.

To run all tests:

make test

This can take some time. To run just frontend tests, just Python tests, or just end-to-end tests, read below.

Frontend

make fe-test

Python

make py-test

We use pytest syntax for Python tests.

Using uv

Run a specific test

uv run --python 3.13 --group test pytest tests/_ast/

Run all changed tests

uv run --python 3.13 --group test pytest --picked

Run tests with optional dependencies

uv run --python 3.13 --group test-optional pytest tests/_ast/

End-to-end

Build the frontend first with make fe so Playwright runs against your latest changes.

make e2e

From frontend/, run pnpm playwright test --ui to run interactively, pnpm playwright test $FILENAME for one file, or add --debug to step through it. See the Playwright best practices.

Visual evidence

All PRs require visual evidence for user-facing changes. For broad changes, check that other features and components do not regress, including different user flows and edge cases.

For example, if you are adding a new API plugin, ensure the UI shows how different parameters combine together to produce the expected output.

PRs

When submitting a pull request, marimo will run: lint, typecheck, and test jobs.

We have some labels which can influence which tests are run:

  • test-all: Run all tests across unchanged files as well.