John Lancaster
121 lines
4.7 KiB
Markdown
121 lines
4.7 KiB
Markdown
---
|
|
name: ruff-linting-formating
|
|
description: "Reference-first Ruff skill for repository preferences, baseline defaults, and source links. Use to pick consistent Ruff conventions and integration references, not to run migration playbooks."
|
|
argument-hint: "Which Ruff preferences or integrations are you deciding (rules, formatting, pre-commit, GitHub Actions)?"
|
|
x-personal-mcp:
|
|
id: ruff-linting-formating
|
|
version: 1.0.0
|
|
tags:
|
|
- ruff
|
|
- linting
|
|
- formatting
|
|
- python
|
|
- ci
|
|
capabilities:
|
|
- resource://skills/ruff-linting-formating/document
|
|
depends_on: []
|
|
---
|
|
|
|
# Ruff Preferences and References
|
|
|
|
Use this skill as a reference index for Ruff preferences, conventions, and source documentation.
|
|
|
|
This document is intentionally not a migration or transition playbook.
|
|
|
|
Load references only when needed:
|
|
- Ruff core documentation: [Ruff docs](./references/ruff-docs.md)
|
|
- Tooling integrations (pre-commit and GitHub Actions): [Ruff integrations](./references/ruff-integrations.md)
|
|
|
|
## When To Use
|
|
|
|
- You want canonical Ruff preferences for this repository context.
|
|
- You need source links for rule selection, formatter behavior, and integrations.
|
|
- You are deciding configuration defaults, not planning a migration sequence.
|
|
|
|
## Preference Baseline
|
|
|
|
Use these as default preferences unless the target repository states otherwise:
|
|
|
|
1. Keep linting and formatting both enabled.
|
|
2. Keep imports sorted via Ruff (`I` rules) rather than a separate import tool.
|
|
3. Prefer explicit, small rule-family selection first (`E`, `F`, `I`, `UP`) and expand deliberately.
|
|
4. Keep line length, target Python, and formatter settings aligned to repository policy.
|
|
5. Keep local and CI execution behavior equivalent.
|
|
|
|
### Rule Link Requirement
|
|
|
|
When adding a specific rule or ruleset to `ruff.toml`, search for the authoritative Ruff documentation page for that rule or ruleset and include a link to it. You may add the URL as a nearby comment in `ruff.toml` or record it in the repository docs (for example in a CONTRIBUTING or linting section). Prefer links to the official [Ruff rules reference](https://docs.astral.sh/ruff/rules/).
|
|
|
|
### Version Discovery Requirement
|
|
|
|
When integrating Ruff or any third-party Action for the first time, always search for the latest stable release of:
|
|
|
|
- the `ruff` package ([releases](https://github.com/astral-sh/ruff/releases))
|
|
- the `astral-sh/ruff-pre-commit` hook ([releases](https://github.com/astral-sh/ruff-pre-commit/releases))
|
|
- the `astral-sh/ruff-action` ([releases](https://github.com/astral-sh/ruff-action/releases))
|
|
- the `astral-sh/setup-uv` action ([releases](https://github.com/astral-sh/setup-uv/releases))
|
|
|
|
Document the version you chose in the example snippet or in a nearby docs file and prefer pinning to a released tag in CI examples. If you intentionally use `latest`, note the reason and the associated risk in repo docs.
|
|
|
|
## Decision Inputs
|
|
|
|
Collect only the minimum context needed for preference decisions:
|
|
|
|
1. Supported Python versions.
|
|
2. Existing `pyproject.toml` constraints.
|
|
3. CI provider and required checks.
|
|
4. Whether pre-commit is in use.
|
|
|
|
## Template
|
|
|
|
[Full template ruff.toml](https://gitea.john-stream.com/john/python-template/src/branch/main/project/ruff.toml)
|
|
|
|
```toml title="Preferred Baseline"
|
|
line-length = 120
|
|
indent-width = 4
|
|
target-version = "py313"
|
|
|
|
exclude = [
|
|
".git",
|
|
".venv",
|
|
".devenv",
|
|
]
|
|
|
|
[lint]
|
|
extend-fixable = ["ALL"]
|
|
extend-select = [
|
|
"C4", # https://docs.astral.sh/ruff/rules/#flake8-comprehensions-c4
|
|
"E", "W", # https://docs.astral.sh/ruff/rules/#pycodestyle-e-w
|
|
"F", # https://docs.astral.sh/ruff/rules/#pyflakes-f
|
|
"FURB", # https://docs.astral.sh/ruff/rules/#refurb-furb
|
|
"I", # https://docs.astral.sh/ruff/rules/#isort-i
|
|
"N", # https://docs.astral.sh/ruff/rules/#pep8-naming-n
|
|
"PD", # https://docs.astral.sh/ruff/rules/#pandas-vet-pd
|
|
"PTH", # https://docs.astral.sh/ruff/rules/#flake8-use-pathlib-pth
|
|
"UP", # https://docs.astral.sh/ruff/rules/#pyupgrade-up
|
|
"SIM", # https://docs.astral.sh/ruff/rules/#flake8-simplify-sim
|
|
]
|
|
|
|
[lint.isort]
|
|
force-single-line = true
|
|
|
|
[format]
|
|
quote-style = "double"
|
|
indent-style = "space"
|
|
skip-magic-trailing-comma = false
|
|
line-ending = "auto"
|
|
```
|
|
|
|
## Reference Map
|
|
|
|
1. Rules and settings source of truth: [Ruff docs](./references/ruff-docs.md)
|
|
2. pre-commit and GitHub Actions examples: [Ruff integrations](./references/ruff-integrations.md)
|
|
3. Template to copy from or compare against: [python-template ruff.toml](https://gitea.john-stream.com/john/python-template/src/branch/main/project/ruff.toml)
|
|
|
|
## Non-Goals
|
|
|
|
This skill does not define:
|
|
|
|
1. Step-by-step migration phases.
|
|
2. Rollout modes or cutover timelines.
|
|
3. Mechanical rewrite plans for legacy tooling. |