astral-sh/ruff

Never edit snapshot files or inline snapshot bodies manually. Regenerate them by running the relevant tests with the snapshot-update environment variables documented above, then review the generated diff.

Unlike noqa suppressions, range suppressions do not support "blanket" suppression of all violations. At least one violation code must be listed.

Even still, given the dynamic nature of Python, it's difficult to have complete certainty when making changes to code, even for seemingly trivial fixes. If a "safe" fix breaks your code, please file an Issue.

Please do not open pull requests for new features without prior discussion. While we appreciate exploration of new features, we will often close these pull requests immediately. Adding a new feature to ruff creates a long-term maintenance burden and requires strong consensus from the ruff team before it is appropriate to begin work on an implementation.

Outside of issues with the labels above, issues labeled as bug are the best candidates for contribution. In contrast, issues labeled with needs-decision or needs-design are not good candidates for contribution. Please do not open pull requests for issues with these labels.

Place each mdtest in a file for the behavior it actually tests, and assert that behavior directly. Prefer an existing file when one already covers that behavior; create a new file when no existing file is a good fit. Do not choose a file solely because its directive or helper can express the assertion.

Prefer a minimal, purpose-built custom type over a standard-library type when a regression depends on particular attributes, methods, bounds, or constraints. Define the relevant behavior in the test so readers do not need to look up the standard-library type to understand the scenario. For commonly used standard-library types, consider adding a separate regression using the real type to protect against changes in typeshed.

Order mdtests from basic, common behavior to more specialized cases. Place narrow regression tests alongside closely related examples when they fit naturally; otherwise, put them near the end of the relevant section or file. Do not put an obscure special case at the beginning simply because it is the newest regression.

Code blocks for the same file within a section are concatenated into one file. For inline snapshots, keep each example's code block close to its # snapshot block. Ideally, any given code block only has one snapshot in it, but one codeblock containing several snapshots is also acceptable. Repeating a short, independent function definition, including one with the same name, is fine if it keeps the code triggering a snapshot close to the snapshot demonstrating the expected diagnostic on that code. Reuse shared setup when clearer, and check that repeated names do not affect other examples.

Write mdtests as readable, literate specifications, and minimize the context a reader must hold in mind. Prefer short, focused code blocks, and define types, fixtures, and helpers close to the assertions that use them. Sections and subsections can be long when they develop a coherent topic through many short examples interspersed with prose. Do not split a subsection, or flag it in review, solely because of its length. Give independent scenarios separate sibling Markdown test headings at the same level; only introduce child headings if any existing code beneath their parent is first moved into

File-watcher tests do not work inside the sandbox. It is usually unnecessary to run them locally before filing a change unless you are certain that the change affects file-watching behavior.

Do not mention discarded alternatives, intermediate edits, private instructions, tool usage, branch or draft status, local test commands, or session history unless the reader needs that information to understand the final result. Do not describe reverted changes as part of the final change.

Write every mdtest paragraph, code comment, piece of documentation, PR description, and GitHub issue for its eventual reader, not for the current Codex conversation. Determine the reader's knowledge, purpose, and likely questions privately; do not add an audience-analysis section to the artifact.

During code review, check the proposed changes against all applicable code, test, documentation, and architectural conventions in this AGENTS.md. Report meaningful violations introduced by the changes; do not apply agent-only workflow instructions to PR authors or flag unrelated pre-existing issues.

Before starting work on an issue and again before opening a pull request, follow the guidance on avoiding duplicate work. If an open pull request already addresses the issue, do not submit a competing one without maintainer agreement.