Contributing¶

Thank you for your interest in contributing to ruff-sync!

This page covers the essentials. For the full contributor's guide, see CONTRIBUTING.md on GitHub.

Getting Started¶

Fork & clone the repository.
Install uv, then sync dependencies:
```
uv run invoke deps
```
Install pre-commit hooks:
```
uv run pre-commit install
```

Documentation Preview¶

You can preview the documentation locally using Invoke:

# Build and serve locally (localhost:8000)
uv run invoke docs

# Build only
uv run invoke docs --build

Quality Checks¶

Run these before every commit, in order:

uv run ruff check . --fix   # Lint & auto-fix
uv run ruff format .         # Format
uv run mypy .                # Type-check
uv run pytest -vv            # Tests

[!IMPORTANT] Fix lint errors at the source — do not add # noqa or suppress rules in config.

Writing Tests¶

Use pyfakefs for filesystem, respx for HTTP mocking.
Async tests need @pytest.mark.asyncio.
TOML merge tests need both a structural (whitespace/comments preserved) and a semantic (values are correct) assertion.

Scaffold new lifecycle TOML test cases with:

uv run invoke new-case --name <case> --description "..."

See .agents/TESTING.md for detailed testing standards.

Contributing a Curated Config¶

We welcome new configurations in configs/!

👉 Join the discussion on Issue #83 before submitting.

Create configs/<my-domain>/ruff.toml with inline comments on each rule.
Optionally add a README.md explaining the config's goals.
Open a PR referencing Issue #83.

See Pre-defined Configs for the existing examples.

Reporting Bugs¶

Open an issue with: - ruff-sync --version output. - ruff --version output. - Your operating system and Python version. - The command you ran and its full output. - Relevant pyproject.toml excerpts.

Pull Request Tips¶

Branch off main; keep commits focused.
For significant changes, open an issue first.
Ensure all CI checks pass before requesting review.