Heuristic:Dagster io Dagster Mandatory Ruff Formatting

Knowledge Sources	CLAUDE.md ruff.toml Dagster Core Team
Domains	Code_Quality, Developer_Workflow
Last Updated	2026-02-10 12:00 GMT

Overview

Mandatory rule to run make ruff after every Python code change, with no exceptions.

Description

The Dagster codebase enforces a strict code quality gate: every Python code change must be followed by running make ruff. This single command runs Ruff for formatting, linting, and auto-fixing. If make ruff makes any changes, tests must be re-run to ensure nothing broke. This is documented in CLAUDE.md, the developer workflow guide, and the pre-commit configuration as an absolute requirement.

Usage

Use this heuristic after every single Python code edit in the Dagster repository. It applies to all contributors, whether making small fixes or large feature additions. The rule is enforced by pre-commit hooks and CI checks.

The Insight (Rule of Thumb)

Action: Run make ruff from the repository root after ANY Python code change.
Value: Consistent formatting across the entire codebase (500+ Python packages). Catches common errors (unused imports, type issues, style violations).
Trade-off: Adds a few seconds to each edit cycle. May auto-fix code in ways that require re-running tests.
Critical workflow:
1. Edit Python code
2. Run make ruff
3. If ruff made changes, re-run tests
4. Only then consider the task complete

Reasoning

The Dagster monorepo contains hundreds of Python packages across python_modules/ and examples/. Without consistent automated formatting and linting, code style diverges rapidly across contributors and packages. Ruff was chosen over Black + isort + flake8 because it provides all three functions in a single, fast tool (written in Rust).

The make ruff command is configured via config/ruff.toml which defines:

Line length: 100 characters
Import sorting: isort-compatible
Lint rules: A comprehensive set including pyflakes, pycodestyle, and Dagster-specific rules
Auto-fix enabled: Ruff automatically fixes fixable issues

The pre-commit configuration (.pre-commit-config.yaml) also runs Ruff as a hook, but running make ruff explicitly ensures all issues are caught before committing.

Code Evidence

From CLAUDE.md:

## Code Quality Requirements

- **MANDATORY**: After any code changes, ALWAYS run `make ruff`
  to format, lint, and autofix code
- **MANDATORY**: If `make ruff` makes any changes, re-run tests
  to ensure everything still works
- **MANDATORY**: Address any linting issues before considering
  a task complete
- Never skip this step - code quality checks are essential for
  all contributions

From .pre-commit-config.yaml:

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment