Add the guides and wiki pages for the C and C++ and C# quality checks

Task: MIL-007#6

guides/quality-checks-cpp.md

@@ -0,0 +1,98 @@
+# Reading C and C++ quality-check results
+
+How a software engineer calls the shared C and C++ quality checks, reads a
+failed run and makes it pass. The workflow format-checks and statically checks
+the C and C++ files of a repository with clang tools at exact versions, changes
+no file and needs no secret. Its contract is ADR-0008 in this repository.
+
+## Calling the workflow
+
+```yaml
+name: Quality C++
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  quality:
+    permissions:
+      contents: read
+    uses: TirSystem/github-action/.gitea/workflows/quality-checks-cpp.yml@v1
+    with:
+      std: c++20
+```
+
+| Input | Default | Meaning |
+| --- | --- | --- |
+| `working-directory` | `.` | Directory, relative to the repository root, whose files are checked |
+| `std` | `c++20` | C++ standard given to clang-tidy when there is no compile database, such as `c++17` or `gnu++20` |
+| `compile-commands-dir` | empty | Directory, relative to the repository root, with a `compile_commands.json` that your pipeline built before the call; when set, clang-tidy uses it and ignores `std` |
+| `clang-format-version` | `23.1.3` | Exact version of the clang-format package |
+| `clang-tidy-version` | `22.1.8` | Exact version of the clang-tidy package |
+| `tools-ref` | `v1` | Tag or branch of `TirSystem/github-action` from which the script `tools/quality-checks-cpp.sh` is fetched |
+
+Reference the workflow at the major tag (`@v1`) or at an exact tag, never at
+`main`. A call at an exact tag is pinned completely only when `tools-ref` names
+the same tag. See the upgrade guide. The tool versions are exact: a newer
+version of a tool is a new release of this repository, not a silent change.
+
+## What the repository needs
+
+- A `.clang-format` in the working directory or in a directory above it, up to
+  the top of the repository. Without one the run fails with `[configuration]`
+  and no tool runs.
+- Optionally a `.clang-tidy` with the checks of the project (for example the
+  C++ Core Guidelines). Without one clang-tidy runs its default checks.
+- For precise static checks, a compile database: build it first (for example
+  `cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON`) and pass
+  `compile-commands-dir: build`. The workflow does not build your project.
+
+## What is checked
+
+| Files | Tool | What it reports |
+| --- | --- | --- |
+| tracked `*.c`, `*.cc`, `*.cpp`, `*.cxx`, `*.h`, `*.hh`, `*.hpp`, `*.hxx` | `clang-format --dry-run -Werror` | formatting that differs from `.clang-format` |
+| the same files | `clang-tidy` | findings of the checks of `.clang-tidy`; `*.c` files are checked as C17, the other files as the C++ standard of `std` |
+
+Untracked files are not checked. A repository without these files passes with a
+notice. There is no `cppcheck`: only an old version of it is available as a
+package, and old tools are not run (ADR-0008).
+
+## Reading a run
+
+1. Open the status check on the pull request, then the job `quality-checks-cpp`.
+2. Each tool has its own log group. Every tool runs even when an earlier one
+   failed, so one run shows all findings.
+3. A tool ends with `PASS <tool>` or `FAIL <tool>`; the last line of a failed
+   run names them: `Quality checks failed: clang-format`.
+4. A finding is written by the tool itself as `path:line:column: message`.
+   Paths are relative to `working-directory`.
+
+## Typical failures and fixes
+
+| Tool | What the log shows | Fix |
+| --- | --- | --- |
+| `clang-format` | `code should be clang-formatted [-Wclang-format-violations]` | Run `clang-format -i <file>` with the same version and commit |
+| `clang-tidy` | `warning: ... [modernize-use-nullptr]` | Fix the code, or switch the check off in `.clang-tidy` with a reason |
+| `clang-tidy` | `error: 'x.h' file not found` | Build the compile database and set `compile-commands-dir`, or add the include path to it |
+
+To reproduce a run on your machine, install the same versions:
+
+```bash
+python3 -m venv .qc
+.qc/bin/pip install clang-format==23.1.3 clang-tidy==22.1.8
+git ls-files '*.cpp' '*.hpp' | xargs .qc/bin/clang-format --dry-run -Werror
+```
+
+## When the workflow itself fails
+
+| Message | Cause | Fix |
+| --- | --- | --- |
+| `[configuration] std '<x>' is not a C++ standard` | `std` is not like `c++20` or `gnu++20` | Correct the input |
+| `[configuration] ... is not an exact version` | A tool version is a range, a channel or empty | Give an exact version such as `23.1.3` |
+| `[configuration] working-directory must be a relative path inside the repository.` | An absolute path or `..` | Use a path inside the repository |
+| `[configuration] No .clang-format found` | The project has no style file | Add a `.clang-format` |
+| `[configuration] compile-commands-dir '<x>' has no compile_commands.json` | The database was not built before the call | Build it in an earlier step of the job or in a job it depends on |
+| The install step fails | PyPI or the runner network is unreachable | Re-run the job; see [troubleshooting.md](troubleshooting.md) |

guides/quality-checks-csharp.md

@@ -0,0 +1,95 @@
+# Reading C# quality-check results
+
+How a software engineer calls the shared C# quality checks, reads a failed run
+and makes it pass. The workflow checks the formatting and builds a solution or
+project with warnings as errors, on an exact .NET SDK of version 10 or later,
+changes no file and needs no secret. Its contract is ADR-0008 in this
+repository.
+
+## Calling the workflow
+
+```yaml
+name: Quality C#
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  quality:
+    permissions:
+      contents: read
+    uses: TirSystem/github-action/.gitea/workflows/quality-checks-csharp.yml@v1
+    with:
+      project: src/App.sln
+```
+
+| Input | Default | Meaning |
+| --- | --- | --- |
+| `working-directory` | `.` | Directory, relative to the repository root, whose files are checked |
+| `project` | empty | Solution or project file, relative to `working-directory`; empty uses the single `*.sln` or `*.slnx`, else the single `*.csproj`, that is tracked there |
+| `dotnet-sdk-version` | `10.0.401` | Exact version of the .NET SDK, 10 or later; a channel such as `10.0`, a range and a version below 10 are refused |
+| `tools-ref` | `v1` | Tag or branch of `TirSystem/github-action` from which the script `tools/quality-checks-csharp.sh` is fetched |
+
+Reference the workflow at the major tag (`@v1`) or at an exact tag, never at
+`main`. A call at an exact tag is pinned completely only when `tools-ref` names
+the same tag. See the upgrade guide. The SDK version is exact: raising the
+default is a new release of this repository, not a silent change.
+
+## What the repository needs
+
+- A solution or project that builds with the SDK. Several candidates need the
+  `project` input; C# files with no solution or project fail with
+  `[configuration]`.
+- The network: `dotnet format` and `dotnet build` restore the NuGet packages of
+  the project in the run.
+- Rules in `.editorconfig` (and the analyzers the project enables, for example
+  with `AnalysisLevel` and `EnforceCodeStyleInBuild`) decide what a finding is.
+
+## What is checked
+
+| Files | Tool | What it reports |
+| --- | --- | --- |
+| the solution or project | `dotnet format --verify-no-changes` | formatting and style that differ from `.editorconfig` |
+| the same | `dotnet build -warnaserror` | compiler and analyzer warnings, which fail the build |
+
+Untracked files are not checked. A repository without `*.cs` files passes with
+a notice. Project tests are not run.
+
+## Reading a run
+
+1. Open the status check on the pull request, then the job
+   `quality-checks-csharp`.
+2. Each tool has its own log group. Both run even when the first failed, so one
+   run shows all findings.
+3. A tool ends with `PASS <tool>` or `FAIL <tool>`; the last line of a failed
+   run names them:
+   `Quality checks failed: dotnet format --verify-no-changes`.
+4. A finding is written by the tool itself as `path(line,column): CODE message`.
+
+## Typical failures and fixes
+
+| Tool | What the log shows | Fix |
+| --- | --- | --- |
+| `dotnet format --verify-no-changes` | `Program.cs(12,5): error WHITESPACE: Fix whitespace formatting` | Run `dotnet format <project>` and commit |
+| `dotnet build -warnaserror` | `CS8602: Dereference of a possibly null reference` | Fix the code (null check), do not suppress the warning without a reason |
+| `dotnet build -warnaserror` | `IDE0005: Using directive is unnecessary` | Remove the directive |
+
+To reproduce a run on your machine, use the same SDK:
+
+```bash
+dotnet --version        # 10.0.401
+dotnet format src/App.sln --verify-no-changes
+dotnet build src/App.sln -warnaserror
+```
+
+## When the workflow itself fails
+
+| Message | Cause | Fix |
+| --- | --- | --- |
+| `[configuration] dotnet-sdk-version '<x>' is not an exact stable version 10 or later` | A channel, a range, a preview or a version below 10 | Give an exact version such as `10.0.401` |
+| `[configuration] working-directory must be a relative path inside the repository.` | An absolute path or `..` | Use a path inside the repository |
+| `[configuration] C# files exist but no solution or project was found` | The repository has `*.cs` files and no `*.sln`, `*.slnx` or `*.csproj` in the working directory | Add one, or set `working-directory` |
+| `[configuration] Several solutions or projects were found` | More than one candidate | Set the input `project` |
+| The install step fails | `dot.net` or the runner network is unreachable | Re-run the job; see [troubleshooting.md](troubleshooting.md) |

guides/upgrading.md

@@ -16,8 +16,9 @@ repository, tags `vMAJOR.MINOR.PATCH` and a moving major tag `vMAJOR`.
 A breaking release gets a new major version (`v2`), so a pipeline on `@v1`
 never receives it until you change the line yourself.
 
-The quality-checks workflow fetches its script at its input `tools-ref`, which
-defaults to `v1`. To pin it completely, call it at an exact tag and set
+The quality-checks workflows (`quality-checks.yml`, `quality-checks-cpp.yml` and
+`quality-checks-csharp.yml`) fetch their script at their input `tools-ref`, which
+defaults to `v1`. To pin one completely, call it at an exact tag and set
 `tools-ref` to the same tag; otherwise the script follows the major tag.
 
 The two scoped workflows (**Sync GitHub mirror metadata** and **Publish