Contributing#

Patches go to kdevops@lists.linux.dev. The rules a change follows and is reviewed against are in designs: designs/principles.md, designs/tasks.md for a task, and designs/writing.md for a commit, a page and a comment.

Requirements#

The checks are Bash and Python 3.11 or later, linted by shellcheck, shfmt, black, ruff and pyright. The pages are built by Sphinx and held to 80 columns by doc8 (Requirements):

host#
$ sudo apt install python3 shellcheck shfmt black ruff
$ sudo apt install python3-sphinx python3-pydata-sphinx-theme \
    python3-sphinx-copybutton python3-sphinx-design \
    python3-sphinx-autobuild python3-doc8
host#
$ sudo dnf install python3 ShellCheck black ruff
$ sudo dnf install python3-sphinx python3-pydata-sphinx-theme \
    python3-sphinx-copybutton python3-sphinx-design \
    python3-sphinx-autobuild

Most of these are in universe:

host#
$ sudo add-apt-repository universe
$ sudo apt install python3 shellcheck shfmt black
$ sudo apt install python3-sphinx python3-pydata-sphinx-theme \
    python3-sphinx-copybutton python3-sphinx-design \
    python3-sphinx-autobuild python3-doc8

None of the three packages pyright. Fedora has no shfmt and no doc8, and Ubuntu no ruff. The Nix shell has them all.

Checks#

Three scripts hold a change to those rules:

$ scripts/check-style.sh       # the tree and the last commit
$ scripts/check.py             # each commit of a range
$ python3 -m unittest discover --start-directory tests

With Nix, one command runs the linters, the tests and the build of these pages, each with the flake’s pinned tools:

$ nix flake check

scripts/commit-msg runs the checks of a message as the commit-msg hook. Link it once:

$ ln --symbolic --verbose --relative scripts/commit-msg \
    "$(git rev-parse --git-path hooks)/commit-msg"

Documentation#

These pages are reStructuredText, built with sphinx-build:

$ scripts/docs                 # render to docs/_build/html
$ scripts/serve                # serve on 127.0.0.1:8001, and render on save
$ scripts/serve --port 8002

scripts/docs fails on a warning, and doc8 holds the pages to 80 columns:

$ doc8 docs