Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

docs: shorten the contributing guide (#11559)

Shahmir Varqha23fe0808a6c5
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index a3ace1b66b..c86b3ad75c 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -12,7 +12,7 @@ Closes #
- [ ] For large changes, or changes that affect the public API: this change was discussed or approved through an issue, on [Discord](https://marimo.io/discord?ref=pr), or the community [discussions](https://github.com/marimo-team/marimo/discussions) (Please provide a link if applicable).
- [ ] Any AI generated code has been reviewed line-by-line by the human PR author, who stands by it.
-- [ ] Video or media evidence is provided for any visual changes (optional). <!-- PR is more likely to be merged if evidence is provided for changes made -->
+- [ ] Video or media evidence is provided for any visual changes. <!-- PR is more likely to be merged if functionality is tested thoroughly -->
## ✅ Merge Checklist
diff --git a/AGENTS.md b/AGENTS.md
index dbbf58430b..19a0ec2fac 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,24 +27,6 @@ make dev
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed setup options.
-## Development Commands
-
-```bash
-# Python
-make py-check # Typecheck and lint Python
-uv run --group test pytest tests/path/to/test.py
-uv run --group test-optional pytest tests/path/to/test.py # with optional deps
-uv run --group test --python 3.11 pytest tests/path/to/test.py # specific python version
-
-# Frontend
-make fe-check # Typecheck and lint frontend
-cd frontend && pnpm test src/path/to/file.test.ts
-```
-
-## Commits
-
-- Run `make check` before committing
-
## Pull Requests
- DO NOT open a pull request autonomously, without explicit instructions from a human
@@ -55,6 +37,10 @@ cd frontend && pnpm test src/path/to/file.test.ts
## Conventions
+- Typesafety is important, leverage it. Avoid being lazy with types.
+- Tests are good! Endless smoke tests, and "regression" tests are not so good. Tests are becoming cheaper to run, so you can always write more, run them, and discard any non-useful ones before committing to production.
+- Comments should be very minimal. They should be used to explain the why, not the what. Code should be written to be self-documenting, if you find the comment starts becoming verbose, consider refactoring the code.
+
### Python
Most style rules are enforced by ruff (`pyproject.toml`) and pre-commit; run
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3d64c7e5ef..51e1f2f9fa 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -10,10 +10,10 @@ Contributions are made through
Before sending a pull request, make sure to do the following:
- [Obtain maintainer approval](#maintainer-approval)
-- [Lint, typecheck, and format](#lint-typecheck-format) your code
-- [Write tests](#tests)
-- [Run tests](#tests) and check that they pass
-- Read the [CLA](https://marimo.io/cla)
+- Lint, typecheck, and format your code (`make check`)
+- [Write and run tests](#tests)
+- [Provide visual evidence for changes made](#visual-evidence)
+- Read and sign the [CLA](https://marimo.io/cla) by commenting on the PR: `I have read the CLA Document and I hereby sign the CLA`
## Maintainer approval
@@ -95,8 +95,9 @@ 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).
-> [!TIP]
-> On the marimo team we use `uv` + `node`/`pnpm` directly. Alternatively, [pixi](https://github.com/prefix-dev/pixi) can manage the Python and Node toolchains for you (`pixi shell` then proceed as above), and [Gitpod](https://gitpod.io/#https://github.com/marimo-team/marimo) provides a cloud-based dev environment — but we don't officially support either of these and recommend the setup above.
+`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](Makefile).
### `pre-commit` hooks
@@ -106,74 +107,6 @@ You can optionally install [pre-commit](https://pre-commit.com/) hooks to automa
uvx pre-commit install
```
-To build the frontend unminified, run:
-
-```bash
-NODE_ENV=development make fe -B
-```
-
-## `make` commands
-
-> [!NOTE]
-> Refer to the [Makefile](Makefile) for the implementation details
-
-| Command | Category | Description |
-| -------------- | --------- | -------------------------------------------------------------- |
-| `help` | General | 📖 Show available commands |
-| `install-all` | Setup | 🚀 First-time setup: Install all dependencies (frontend & Python) |
-| `check-prereqs`| Setup | ✓ Check if all required tools are installed |
-| `py` | Setup | 🐍 Install Python dependencies in editable mode |
-| `fe` | Build | 🔧 Build frontend assets |
-| `test` | Test | 🧪 Run all tests (frontend, Python, end-to-end) |
-| `check` | Test | 🧹 Run all checks |
-| `fe-check` | Lint/Test | 🧹 Check frontend (lint, typecheck) |
-| `fe-test` | Test | 🧪 Test frontend |
-| `e2e` | Test | 🧪 Test end-to-end |
-| `fe-lint` | Lint | 🧹 Lint frontend |
-| `fe-typecheck` | Lint | 🔍 Typecheck frontend |
-| `fe-codegen` | Build | 🔄 Generate frontend API |
-| `py-check` | Lint | 🔍 Typecheck, lint, format python |
-| `typos` | Lint | 🔍 Check for typos |
-| `py-test` | Test | 🧪 Test python |
-| `py-snapshots` | Test | 📸 Update snapshots |
-| `wheel` | Build | 📦 Build wheel |
-| `docs` | Docs | 📚 Build docs |
-| `docs-serve` | Docs | 📚 Serve docs |
-| `storybook` | Docs | 🧩 Start Storybook for UI development |
-
-## Lint, Typecheck, Format
-
-**All checks.**
-
-```bash
-make check
-```
-
-**Frontend.**
-
-```bash
-make fe-check
-```
-
-**Python.**
-
-<table>
- <tr>
- <th>Using <code>make</code></th>
- <th>Using <code>uv</code></th>
- </tr>
- <tr>
- <td>
- <pre><code>make py-check </code></pre>
- </td>
- <td>
- <pre><code>uv run ruff check --fix
-uv run ruff format
-uv run --only-group typecheck mypy marimo --exclude=marimo/_tutorials/</code></pre>
- </td>
- </tr>
-</table>
-
## Tests
We have frontend unit tests, Python unit tests, and end-to-end tests.
@@ -191,22 +124,18 @@ end-to-end tests, read below.
### Frontend
-In the root directory, run:
-
```bash
make fe-test
```
### Python
-We use [pytest syntax](https://docs.pytest.org/en/stable/how-to/usage.html) for Python tests.
-
-#### Using Make
-
```bash
make py-test
```
+We use [pytest syntax](https://docs.pytest.org/en/stable/how-to/usage.html) for Python tests.
+
#### Using uv
Run a specific test
@@ -229,125 +158,19 @@ uv run --python 3.13 --group test-optional pytest tests/_ast/
### End-to-end
-We use playwright to write and run end-to-end tests, which exercise both the
-marimo library and the frontend.
-
-(The first time you run, you may be prompted by playwright to install some
-dependencies; follow those instructions.)
-
-For best practices on writing end-to-end tests, check out the [Best Practices
-doc](https://playwright.dev/docs/best-practices).
-
-For frontend tests, you want to build the frontend first with `make fe` so that Playwright works on your latest changes.
-
-**Run end-to-end tests.**
-
-In the root directory, run:
+Build the frontend first with `make fe` so Playwright runs against your latest changes.
```bash
make e2e
```
-**Run tests interactively.**
-
-In `frontend/`:
-
-```bash
-pnpm playwright test --ui
-```
+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](https://playwright.dev/docs/best-practices).
-**Run a specific test.**
+## Visual evidence
-In `frontend/`:
-
-<table>
- <tr>
- <th>Without debugger</th>
- <th>With debugger</th>
- </tr>
- <tr>
- <td>
- <pre><code>pnpm playwright test $FILENAME </code></pre>
- </td>
- <td>
- <pre><code>pnpm playwright test --debug $FILENAME</code></pre>
- </td>
- </tr>
-</table>
-
-## Storybook
-
-To open Storybook, run the following:
-
-```bash
-cd frontend && pnpm storybook
-```
-
-## Hot reloading / development mode
-
-You can develop on marimo with hot reloading on the frontend and/or development
-mode on the server (which automatically restarts the server on code changes).
-These modes are especially helpful when you're making many small changes and
-want to see changes end-to-end very quickly.
-
-For the frontend, you can choose to run slower hot reloading for an environment closer to production.
-
-<table>
- <tr>
- <th>Production-esque</th>
- <th>Development</th>
- </tr>
- <tr>
- <td>
- <pre><code>pnpm build:watch </code></pre>
- </td>
- <td>
- <pre><code>pnpm dev </code></pre>
- </td>
- </tr>
-</table>
-
-For the backend, we recommend running without auth (`--no-token`):
-
-<table>
- <tr>
- <th>Production</th>
- <th>Debug</th>
- </tr>
- <tr>
- <td>
- <pre><code>marimo edit --no-token </code></pre>
- </td>
- <td>
- <pre><code>marimo -d edit --no-token</code></pre>
- </td>
- </tr>
-</table>
-
-### FAQ
-
-- **When to run with hot-reloading?**: When you are developing on the frontend
- and want to see changes immediately. This is useful for styling, layout, new
- plugins, etc. Developing through the Vite server may have inconsistent
- behavior due to proxied api/websocket request and since the marimo Python
- server is not serving the HTML.
-- **When to develop with the frontend in watch mode?**: When you are making few
- frontend changes, or when you want to test the frontend in a way that is
- closer to production.
-- **When to run marimo CLI with development mode?**: When you are making
- changes to the backend and want to see debug logs.
- When developing on marimo plugins, you can run with "On module change" as "autorun" to see changes immediately.
-
-**Caveats for running `pnpm dev`**
-
-Running `pnpm dev` will serve the frontend from a Vite dev server, not from the
-marimo server. This means that:
-
-1. You will want to run your marimo server with `--headless` and `--no-token` so it does not open a new browser tab, as it will interfere with the frontend dev server.
-1. The tradeoff of using the frontend dev server is that it is faster to
- develop on the frontend, but you will not be able to test the frontend in
- the same way that it will be used in production.
+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
@@ -356,7 +179,3 @@ 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.
-
-## Your first PR
-
-Marimo has a variety of CI jobs that run on pull requests. All new PRs will fail until you have signed the [CLA](https://marimo.io/cla). Don't fret. You can sign the CLA by leaving a comment in the PR with text of `I have read the CLA Document and I hereby sign the CLA`