From 9169702671ca9b7fabe4fa5d6dc7ede3494aa93d Mon Sep 17 00:00:00 2001 From: Tirsvad Date: Sun, 11 Oct 2026 04:35:06 +0200 Subject: [PATCH] Publish wiki from the repository --- QualityChecksPythonShell.md | 112 ++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 QualityChecksPythonShell.md diff --git a/QualityChecksPythonShell.md b/QualityChecksPythonShell.md new file mode 100644 index 0000000..d7bb238 --- /dev/null +++ b/QualityChecksPythonShell.md @@ -0,0 +1,112 @@ + + +> This page is generated from [`guides/quality-checks.md`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/quality-checks.md). Changes made here are overwritten the next time the wiki is published. + +English | [Dansk](QualityChecksPythonShell.da) | [Bahasa Melayu](QualityChecksPythonShell.ms) + +# Reading quality-check results + +How a software engineer calls the shared quality checks, reads a failed run and +makes it pass. The workflow lints and format-checks the Python and shell files +of a repository with pinned tools, changes no file and needs no secret. Its +contract is ADR-0005 in this repository. + +## Calling the workflow + +```yaml +name: Quality + +on: + pull_request: + push: + branches: [ main ] + +jobs: + quality: + permissions: + contents: read + uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1 + with: + languages: python,shell +``` + +| Input | Default | Meaning | +| --- | --- | --- | +| `languages` | `python,shell` | Comma list of the languages to check | +| `working-directory` | `.` | Directory, relative to the repository root, whose files are checked | +| `ruff-version` | `0.6.9` | Version of ruff | +| `mypy-version` | `1.11.2` | Version of mypy | +| `shellcheck-py-version` | `0.10.0.1` | Version of the shellcheck-py package (ShellCheck 0.10.0) | +| `shfmt-py-version` | `3.11.0.2` | Version of the shfmt-py package (shfmt 3.11.0) | + +Reference the workflow at the major tag (`@v1`) or at an exact tag +(`@v1.0.0`), never at `main` and never at the branch of a pull request: that +branch is deleted when the pull request is merged and the reference stops +working. See the upgrade guide for what each choice receives. + +## What is checked + +| Language | Files | Tools | +| --- | --- | --- | +| Python | tracked `*.py` under the working directory | `ruff check`, `ruff format --check`, `mypy --strict` | +| Shell | tracked `*.sh` under the working directory | `shellcheck`, `shfmt -d` | + +Untracked files are not checked. A language without files is skipped with a +notice and counts as a pass. Project tests are not run. + +## Reading a run + +1. Open the status check on the pull request, then the job `quality-checks`. +2. Each tool has its own log group named after it. Every tool runs even when an + earlier one failed, so one run shows all findings. +3. A tool ends with `PASS ` or `FAIL `. The last line of a failed + run names the tools that failed: + `Quality checks failed: ruff check shellcheck`. +4. A finding is written by the tool itself as `path:line:column: CODE message`. + Paths are relative to `working-directory`. + +## Typical failures and fixes + +| Tool | What the log shows | Fix | +| --- | --- | --- | +| `ruff check` | `F401 ... imported but unused` | Remove the import, or use it | +| `ruff format --check` | `Would reformat: ` | Run `ruff format ` and commit | +| `mypy --strict` | `Function is missing a type annotation` | Add parameter and return types | +| `shellcheck` | `SC2086 ... Double quote to prevent globbing` | Quote the expansion: `"$1"` | +| `shfmt -d` | a diff of `.orig` and `` | Run `shfmt -w ` with the project's options and commit | + +To reproduce a run on your machine, install the same versions and run the +commands of the table: + +```bash +python3 -m venv .qc +.qc/bin/pip install ruff==0.6.9 mypy==1.11.2 shellcheck-py==0.10.0.1 shfmt-py==3.11.0.2 +.qc/bin/ruff check . && .qc/bin/ruff format --check . +``` + +## Configuring the tools + +The workflow adds no configuration; it runs from the repository root, so the +files of the project apply: + +| Tool | File | Example | +| --- | --- | --- | +| ruff | `pyproject.toml` | `[tool.ruff]` with `line-length = 100` | +| mypy | `pyproject.toml` | `[tool.mypy]` with per-module `ignore_missing_imports` | +| shellcheck | `.shellcheckrc` | `external-sources=true` and `source-path=SCRIPTDIR` | +| shfmt | `.editorconfig` | `[*.sh]` with `indent_size = 2` and `switch_case_indent = true` | + +shfmt follows a project's style only through `.editorconfig`. A shell project +that formats with its own flags (for example `shfmt -i 2 -ci`) should expect a +first formatting failure and express the flags there; in the first adoption +(RepoFoundry) one line, `switch_case_indent = true`, was enough and no script +changed. + +## When the workflow itself fails + +| Message | Cause | Fix | +| --- | --- | --- | +| `[configuration] Unknown language ''` | `languages` has a value other than `python` or `shell` | Correct the input | +| `[configuration] working-directory must be a relative path inside the repository.` | An absolute path or `..` | Use a path inside the repository | +| `[configuration] working-directory '' does not exist.` | The directory is not in the repository | Correct the input | +| The install step fails | PyPI or the runner network is unreachable | Re-run the job; see [troubleshooting.md](Troubleshooting) |