Configuration for linting and formatting with ruff

Linting and formatting with ruff for Ska3

1. Maintenance for ruff updates
2. Initial setup for a repo

Maintenance for ruff updates

If you have already set up a repo but find CI or pre-commit are failing now, it may mean that ruff has been updated to include new/changed rules. There are four distinct versions of ruff in use:

• GitHub workflows CI: latest stable release.
• VS code: latest stable release (assuming you keep your extensions up to date)
• pre-commit: version specified in .pre-commit-config.yaml
• Ska3 installed (used in command-line checks): version installed in Ska3 (old by default)

You can update for these changes as follows.

First, install the latest ruff in your Ska3 environment. It is safe to do this in a non-production flight environment because ruff has no other dependencies and is not a dependency of any Ska3 packages for operations:

pip install --upgrade ruff

Second, update your pre-commit:

pre-commit autoupdate

Third, run the format and lint checks and then fix things:

ruff format [--check] .
ruff check .
# Update code and/or ruff.toml as needed

Initial setup for a repo

This includes the steps to add or modify configuration files to use ruff for code formatting and linting.

skare3 repo

In these instructions it is assumed that the skare3 repo is located at ~/git/skare3 and checked out at master.

ruff branch

As usual start by making a branch from the latest master:

git switch master
git pull
git switch -c ruff

pyproject.toml

If this file exists then examine the file. Any tool setups for black, isort, pyright or ruff should be removed. Most commonly that means deleting the entire file.

# If ONLY black, isort, ruff, pyright configs exist, otherwise edit it.
git rm pyproject.toml

ruff.toml and ruff-base.toml

These files define the ruff configuration for the repo. In general you should only modify ruff.toml; the ruff-base.toml file is intended as a configuration base that applies for all of Ska3.

cd ~/git/skare3
git switch master
git pull
cd -

cp ~/git/skare3/templates/ruff.toml ./
cp ~/git/skare3/templates/ruff-base.toml ./
git add ruff-base.toml ruff.toml

Python formatting and linting CI actions

mkdir -p .github/workflows
cp ~/git/skare3/templates/.github/workflows/python-*.yml .github/workflows
git add .github/workflows/python-*.yml
git rm .github/workflows/black.yml
git rm .github/workflows/flake8.yml

Pre-commit

cp ~/git/skare3/templates/.pre-commit-config.yaml ./
git add .pre-commit-config.yaml
pre-commit install
pre-commit autoupdate
git add .pre-commit-config.yaml

If the pre-commit executable is not available and you are using a non-production Ska3 environment, you can install pre-commit with:

pip install pre-commit

Commit all the configuration file updates

git commit --no-verify -m "Update for linting and formatting with ruff"

Update the code format

Now format with ruff, first making changes except for converting single quotes to double quotes:

ruff format --config 'format.quote-style = "preserve"'

Now check that the changes are OK. For the most part these automated changes will always preserve the code logic exactly but it is a good idea to review before committing:

git commit --no-verify -am "Format with ruff (no quote changes)"

Now run ruff again to change any single quotes to double, and commit:

ruff format
git commit --no-verify -am "Format with ruff (only quote changes)"

Check code linting

This step requires a little thinking and experience. The starting point is:

ruff check .

You will typically see lots of warnings. Some of them need to be fixed, some should be fixed and some should be ignored.

Any global changes to the default rules should be captured in the ruff.toml file.