diff --git a/docs/adr/adr-0008-cpp-csharp-quality-check-contract.md b/docs/adr/adr-0008-cpp-csharp-quality-check-contract.md new file mode 100644 index 0000000..177d928 --- /dev/null +++ b/docs/adr/adr-0008-cpp-csharp-quality-check-contract.md @@ -0,0 +1,136 @@ +# ADR-0008: Quality-check contract for C++ and C# + +## Metadata +| Key | Value | +| --- | --- | +| ID | ADR-0008 | +| CrossReference | [MIL-007], [UC-005], [US-001], [ADR-0005], [ADR-0006] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-11 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`. + +--- + +## Context + +ADR-0005 defines the contract of the shared quality-check workflow for Python +and shell: inputs with working defaults, a pinned version per tool, every tool +runs, a failure names tool, file and line, and a language without files +passes with a notice. MIL-007 adds C++ and C#. Two requirements came from S01 +on 2026-10-11 and bound the decision: + +- C++ and C# are separate workflows, not an extension of `quality-checks.yml`. +- Old tools are not run: the .NET SDK is version 10 or later, and a tool that + is only available as an old version is not used. + +Facts (MIL-007 task 2, runs 692 and 699 on `ubuntu-latest`, Ubuntu 24.04, +root, `gcc`/`g++` 13.3 present): + +- `clang-format` 23.1.3 and `clang-tidy` 22.1.8 install from PyPI in a few + seconds with an exact version. +- `cppcheck` is only available as an old version (apt 2.13.0; the latest + release is 2.22.0; the PyPI package of that name is another project). +- The .NET SDK 10.0.401 installs with the official `dotnet-install.sh` in about + 20 s with an exact `--version`; apt gives an older band (10.0.112). +- A `clang-tidy` run needs flags or a compile database, and a C# format check + and build need the project's package restore, which needs the network. + +Options: + +1. **One combined workflow for C++ and C#.** One page and one place to call, + but two unrelated toolchains in one job, and an input set that mixes both. +2. **One workflow per language** (`quality-checks-cpp.yml`, + `quality-checks-csharp.yml`), each with its own inputs and tools. +3. **Extend `quality-checks.yml`** with two more values of `languages`. + Rejected by S01 (separate workflows) and it would make the contract of + ADR-0005 grow with every language. + +For `cppcheck`: (a) keep the apt version, (b) build a current release from +source in every run, (c) drop it. For the SDK: (a) a channel such as `10.0`, +(b) an exact version. + +## Decision + +C++ and C# are checked by two separate reusable workflows, +`quality-checks-cpp.yml` and `quality-checks-csharp.yml`, each running a script +file of this repository (`tools/quality-checks-cpp.sh`, +`tools/quality-checks-csharp.sh`) that it fetches at its input `tools-ref` +(default `v1`), with the contract of ADR-0005 for pass, fail, logs and +skipped languages; `cppcheck` is not used, and the .NET SDK is installed at an +exact version of 10 or later. + +The rules that follow from it: + +- **C++ (and C):** `clang-format --dry-run -Werror` and `clang-tidy` on the + tracked `*.c`, `*.cc`, `*.cpp`, `*.cxx`, `*.h`, `*.hh`, `*.hpp` files under + `working-directory`, both from PyPI at the exact versions of the inputs + `clang-format-version` (default `23.1.3`) and `clang-tidy-version` (default + `22.1.8`). Inputs: `working-directory` (default `.`), `std` (default + `c++20`), `compile-commands-dir` (default empty: the flags `-std=` are + used; set it to the directory of a `compile_commands.json` the caller built + before the call), `tools-ref`. A `.clang-format` and a `.clang-tidy` of the + project configure the tools; a missing `.clang-format` is a + `[configuration]` failure. +- **C#:** `dotnet format --verify-no-changes` and `dotnet build + -warnaserror` with the analyzers the project enables in `.editorconfig`, + on the solution or project found under `working-directory`. Inputs: + `working-directory` (default `.`), `project` (default empty: the single + `*.sln`, `*.slnx` or `*.csproj` found; none or several is a + `[configuration]` failure that names them), `dotnet-sdk-version` (default + an exact `10.0.x`, installed with `dotnet-install.sh --version`), + `tools-ref`. +- **No `cppcheck`:** `clang-tidy` does the static analysis with a current + release; a future version of the contract may add a static analyzer when a + current release is a package. +- **Exact pins:** every tool input is an exact version, never a channel or a + range; raising a default is a breaking change under ADR-0006. +- **Names:** the wiki pages are `QualityChecksCpp` and `QualityChecksCSharp` + with the usual `.da` and `.ms` translations; the guides are + `guides/quality-checks-cpp.md` and `guides/quality-checks-csharp.md`. +- **C is included with C++:** the same tools check both and the files are + told apart by extension; `QC-CL-001` and `QC-CPP-001` stay the review + checklists of the code itself. + +## Consequences + +**Positive:** + +- Each workflow has inputs that fit its language, and a consumer of one never + sees the inputs of the other. +- Only current tools run; a run is reproducible because every version is exact. +- The scripts are files that are linted and tested with stub tools, as for + `quality-checks.yml`. + +**Negative:** + +- Two workflows, two guides and two wiki pages to keep; a repository with both + languages calls both. +- Without `cppcheck` the C++ checks are `clang-tidy` and the compiler only; a + defect class that `cppcheck` finds may go unchecked. +- A C# check needs the network for the package restore, and a C++ check needs + the caller to build a compile database for precise results; both are the + caller's responsibility and are said in the guides. +- Raising the exact default of a tool, including the SDK, is a breaking + change and costs a major version (ADR-0006). +- A caller pinned to an exact tag is pinned completely only when `tools-ref` + names the same tag (as for `quality-checks.yml`). + +## Affected Artifacts + +- [MIL-007] — decides its criterion 2 and unlocks tasks 4 and 5. +- [UC-005] — the use case these workflows serve. +- [US-001] — US-001.16 and US-001.17 state their acceptance criteria. +- [ADR-0005] — the contract that this decision extends, unchanged. +- [ADR-0006] — raising a default tool version is breaking. + +--- + +[MIL-007]: ../milestones/mil-007-cpp-csharp-quality-checks.md +[UC-005]: ../uc-005/uc.md +[US-001]: ../user-stories.md +[ADR-0005]: ./adr-0005-quality-check-contract.md +[ADR-0006]: ./adr-0006-release-process-and-version-pinning.md diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index 1043afa..77ece4c 100644 --- a/docs/artifact-registry.md +++ b/docs/artifact-registry.md @@ -13,7 +13,7 @@ each document lives in *this* project and the next version to use. | MIL | Milestone / Gateway | docs/milestones/*.md | 008 | | RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 054 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | -| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0008 | +| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0009 | | UCD | Use Case Diagram | docs/use-case-diagram.md | 002 | | US | User Story | docs/user-stories.md | 002 | | UC | Use Case | docs/uc-NNN/uc.md | 008 | diff --git a/framework b/framework index 14d221e..4fd69c4 160000 --- a/framework +++ b/framework @@ -1 +1 @@ -Subproject commit 14d221ec1cfd3966611a3eff6a607ef1964526c2 +Subproject commit 4fd69c49703a08022ac6ddd1ff9d05e058a8af98