Linting
=======

This page defines the canonical linting rules for FRIDOM.

General rules
-------------

Linting should improve code quality without introducing unnecessary behavioral
changes.

Prefer fixing code over adding ignores.

Keep changes minimal, reviewable, and consistent with existing project
conventions.

Scope
-----

The standard Ruff linting scope for this repository is:

- ``src/``
- ``tests/``
- ``examples/``
- ``benchmark/``

Files outside this scope should not be treated as part of the normal Ruff
workflow unless explicitly requested.

Configuration
-------------

Ruff configuration lives in ``pyproject.toml``.

When lint policy changes, update both:

- ``pyproject.toml``
- this page

Code fixes and ignores
----------------------

Prefer code fixes over ignores.

Add ignores only when:

- a Ruff rule conflicts with formatting behavior
- the project intentionally uses a pattern that should remain in place
- a code change would reduce clarity or harm the intended API

When adding an ignore, prefer the narrowest reasonable scope.

Workflow
--------

The standard linting workflow is:

1. run Ruff on the configured scope
2. apply safe automatic fixes when appropriate
3. fix remaining issues manually
4. run formatting if needed
5. re-run Ruff until the scope is clean

Expected behavior
-----------------

Linting changes should:

- preserve behavior unless a real bug is being fixed
- avoid broad refactors unless they are necessary
- follow the documented docstring and coding standards
- remain consistent with the Ruff configuration in ``pyproject.toml``

Do not
------

- do not broaden Ruff scope without updating the documented rules
- do not add broad ignores when a local code fix is clearer
- do not change behavior just to satisfy a lint rule unless the original code is
  actually wrong
- do not treat undocumented agent behavior as policy; use this page and
  ``pyproject.toml`` as the source of truth