From 32b5ab62ab5a82638b71b8fcfb43a819e92ab346 Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Sun, 11 Oct 2026 12:26:58 +0800 Subject: [PATCH 1/2] Extend UC-005 and US-001 to C++ and C#, and record the runner tools of MIL-007 --- .../mil-007-cpp-csharp-quality-checks.md | 31 +++++++++++++-- docs/uc-005/uc.md | 12 +++--- docs/user-stories.md | 38 ++++++++++++++++--- 3 files changed, 68 insertions(+), 13 deletions(-) diff --git a/docs/milestones/mil-007-cpp-csharp-quality-checks.md b/docs/milestones/mil-007-cpp-csharp-quality-checks.md index a7e30bc..1a9649d 100644 --- a/docs/milestones/mil-007-cpp-csharp-quality-checks.md +++ b/docs/milestones/mil-007-cpp-csharp-quality-checks.md @@ -9,8 +9,8 @@ ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-11 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | [b74ee0e] | -| 2026-10-11 | Accepted | Jens Tirsvad Nielsen | S01 | Reviewed (RC-052) and accepted; target date 2027-01-16 confirmed by S01 (stand-in for S05) | [e3ad1fa] | +| 2026-10-11 | Deprecated | Jens Tirsvad Nielsen | S01 | Reviewed (RC-052) and accepted; target date 2027-01-16 confirmed by S01 (stand-in for S05) | [e3ad1fa] | +| 2026-10-11 | Proposed | Jens Tirsvad Nielsen | S01 | Added the verification results of task 2 (runner tools) | pending | --- @@ -78,6 +78,32 @@ name and contract. | 7 | Adopt each workflow in one other repository | Onboard a real C++ project and a real C# project, or a throwaway repository when none exists, and fix the gaps in the guides that appear. Verify a seeded failure. | No | | | 8 | Release | Add the changelog entry (a new workflow is a minor change, ADR-0006) and run the Release workflow; record the results in this milestone and review it. | No | | +## Verification results + +Task 2 was run on 2026-10-11 with a throwaway branch, `verify-runner-tools`, +in `TirSystem/github-action` (run 692, deleted afterwards). One job on +`ubuntu-latest` printed what the image has and tried each way of installing a +tool. + +| Fact | Result | +| --- | --- | +| Image | Ubuntu 24.04, `x86_64`, the job runs as root, `sudo`, `curl`, `python3` 3.12 and `pip` present | +| Present in the image | `gcc` and `g++` 13.3, `make`; missing: `clang-format`, `clang-tidy`, `cppcheck`, `cmake`, `dotnet` | +| `clang-format` | from PyPI in 2 s (23.1.3); from apt in 9 s | +| `clang-tidy` | from PyPI in 5 s; from apt in 25 s | +| `cppcheck` | from apt in 6 s (2.13.0); no PyPI package found under `cppcheck-wheel` | +| .NET SDK | from apt `dotnet-sdk-8.0` in 24 s (8.0.131); from the official script `dot.net/v1/dotnet-install.sh` with `--channel 8.0` in 25 s (8.0.425) | + +So every tool can be had in the run in under 30 seconds each with no change to +the runner, either from PyPI (the clang tools, as `quality-checks.yml` already +does for its tools, with an exact version) or from apt and the official script. +Not covered by this task: running a tool against a real C++ project (a +`clang-tidy` run needs a compile database or flags) or a real C# solution +(`dotnet format` and a build need the project's restore of packages from the +network), a private runner with no internet, and an image that differs from +`ubuntu-latest`. Those belong to the contract (task 3) and to the adoption +(task 7). + --- [BC-001]: ../business-case.md @@ -87,5 +113,4 @@ name and contract. [MIL-004]: ./mil-004-versioned-release.md [ADR-0005]: ../adr/adr-0005-quality-check-contract.md [ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.md -[b74ee0e]: https://git.tirsystem.com/TirSystem/github-action/commit/b74ee0e5cfd04f25ba5f2c1addc80699147c479a [e3ad1fa]: https://git.tirsystem.com/TirSystem/github-action/commit/e3ad1fa7e7eef57a6793a479edb41ac6fd2db688 diff --git a/docs/uc-005/uc.md b/docs/uc-005/uc.md index 71539c6..05961ad 100644 --- a/docs/uc-005/uc.md +++ b/docs/uc-005/uc.md @@ -4,12 +4,13 @@ | Key | Value | | --- | --- | | ID | UC-005 | -| CrossReference | [UCD-001], [US-001], [SA-001], [ADR-0005] | +| CrossReference | [UCD-001], [US-001], [SA-001], [ADR-0005], [MIL-007] | ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | [385d2fb] | +| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | [385d2fb] | +| 2026-10-11 | Proposed | Jens Tirsvad Nielsen | S01 | Brief extended to C++ and C# (MIL-007 task 1) | pending | --- @@ -20,18 +21,18 @@ **Level:** user-goal **Primary Actor:** Software Engineer **Stakeholders:** S02, S05 (interests below) -**Stories:** US-001.09, US-001.10 +**Stories:** US-001.09, US-001.10, US-001.16, US-001.17 ## Brief -A Software Engineer opens a pull request in a repository that calls the shared quality-check workflow. The workflow installs the pinned tools, runs the checks for each selected language on the files of the repository (lint, format and types for Python; lint and format for shell), and reports one status for the pull request. When every selected tool passes, the status is green. +A Software Engineer opens a pull request in a repository that calls the shared quality-check workflow. The workflow installs the pinned tools, runs the checks for each selected language on the files of the repository (lint, format and types for Python; lint and format for shell; format and static checks for C++; format and analyzer checks for C#), and reports one status for the pull request. A language that needs a build or a project file says what is missing instead of passing. When every selected tool passes, the status is green. **Stakeholder interests** - S02 — checks run the same way in every project without writing a pipeline, and a failure says what to fix - S05 — the checks and their tool versions are defined once and change through a reviewed release -**Preconditions:** The repository is onboarded, the shared workflow is available through reusable workflow delivery, and the repository has files of at least one supported language. +**Preconditions:** The repository is onboarded, the shared workflow is available through reusable workflow delivery, and the repository has files of at least one supported language (Python, shell, C++ or C#). **Postconditions (success guarantee):** The pull request has a pass or fail status that comes from every selected tool, and no file of the repository was changed. @@ -41,4 +42,5 @@ A Software Engineer opens a pull request in a repository that calls the shared q [US-001]: ../user-stories.md [SA-001]: ../stakeholder-analysis.md [ADR-0005]: ../adr/adr-0005-quality-check-contract.md +[MIL-007]: ../milestones/mil-007-cpp-csharp-quality-checks.md [385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7 diff --git a/docs/user-stories.md b/docs/user-stories.md index 633245f..ac210f1 100644 --- a/docs/user-stories.md +++ b/docs/user-stories.md @@ -4,13 +4,13 @@ | Key | Value | | --- | --- | | ID | US-001 | -| CrossReference | [UCD-001], [BC-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007] | +| CrossReference | [UCD-001], [BC-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007], [MIL-007] | ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added US-001.11 to US-001.13 (releases, UC-006); US-001.13 traced to the epic (RC-041) | [044d8ba] | -| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added US-001.14 and US-001.15 (UC-007); US-001.13 traced to UC-007 (RC-046) | [4cf52af] | +| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added US-001.14 and US-001.15 (UC-007); US-001.13 traced to UC-007 (RC-046) | [4cf52af] | +| 2026-10-11 | Proposed | Jens Tirsvad Nielsen | S01 | Added US-001.16 and US-001.17 (C++ and C# checks, MIL-007 task 1) | pending | --- @@ -218,9 +218,37 @@ actors of [UCD-001]. Stories for quality checks and releases (MIL-004) and for t | --- | --- | --- | | [UC-007], [MIL-004] | fits one iteration | none | +### US-001.16 — A C++ project gets the same checks + +**As a** Software Engineer, **I want** a pull request in a C++ repository to run format and static checks, **so that** a defect is found before review without me writing a pipeline. + +**Acceptance Criteria** + +- Given a repository that calls the shared C++ quality-check workflow and has C++ files, when a pull request is opened, then the format and static checks run and the status is pass or fail. +- Given a file with a finding, when the check runs, then the job fails and the log shows the tool name with `path:line` and the tool's message. +- Given a repository that lacks what a check needs, when the check runs, then it fails with a `[configuration]` message that names what is missing instead of passing. + +| Traces to | Size | INVEST exceptions | +| --- | --- | --- | +| [UC-005], [MIL-007] | fits one iteration | none | + +### US-001.17 — A C# project gets the same checks + +**As a** Software Engineer, **I want** a pull request in a C# repository to run format and analyzer checks, **so that** a defect is found before review without me writing a pipeline. + +**Acceptance Criteria** + +- Given a repository that calls the shared C# quality-check workflow and has a project or solution, when a pull request is opened, then the format and analyzer checks run and the status is pass or fail. +- Given a file with a finding, when the check runs, then the job fails and the log shows the tool name with `path:line` and the tool's message. +- Given a repository without a project or solution, when the check runs, then it fails with a `[configuration]` message that names what is missing instead of passing. + +| Traces to | Size | INVEST exceptions | +| --- | --- | --- | +| [UC-005], [MIL-007] | fits one iteration | none | + ## INVEST Check -All fifteen stories are independent of each other except that US-001.05 and +All seventeen stories are independent of each other except that US-001.05 and US-001.06 build on US-001.04 (the secrets must exist before a repository can run the workflow). Each states one goal and can be negotiated, delivers value to the named role, is small enough for one iteration, and has acceptance @@ -236,12 +264,12 @@ behaviour is tested rather than built. [MIL-002]: ./milestones/mil-002-onboarding-and-operations.md [MIL-003]: ./milestones/mil-003-quality-checks.md [MIL-004]: ./milestones/mil-004-versioned-release.md +[MIL-007]: ./milestones/mil-007-cpp-csharp-quality-checks.md [UC-001]: ./uc-001/uc.md [UC-002]: ./uc-002/uc.md [UC-003]: ./uc-003/uc.md [UC-004]: ./uc-004/uc.md [UC-005]: ./uc-005/uc.md [UC-006]: ./uc-006/uc.md -[044d8ba]: https://git.tirsystem.com/TirSystem/github-action/commit/044d8ba21f96f4aceb807d62addc35cdcbb56051 [UC-007]: ./uc-007/uc.md [4cf52af]: https://git.tirsystem.com/TirSystem/github-action/commit/4cf52afe00f546c6b20424fb8dfc12796ffd9296 -- 2.54.0 From 92c1795379d8e28d902cb2a8e284244a1fba094e Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Sun, 11 Oct 2026 12:26:59 +0800 Subject: [PATCH 2/2] Resolve pending commit links in the MIL-007 use case documents --- docs/milestones/mil-007-cpp-csharp-quality-checks.md | 3 ++- docs/uc-005/uc.md | 3 ++- docs/user-stories.md | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/milestones/mil-007-cpp-csharp-quality-checks.md b/docs/milestones/mil-007-cpp-csharp-quality-checks.md index 1a9649d..505c504 100644 --- a/docs/milestones/mil-007-cpp-csharp-quality-checks.md +++ b/docs/milestones/mil-007-cpp-csharp-quality-checks.md @@ -10,7 +10,7 @@ | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | | 2026-10-11 | Deprecated | Jens Tirsvad Nielsen | S01 | Reviewed (RC-052) and accepted; target date 2027-01-16 confirmed by S01 (stand-in for S05) | [e3ad1fa] | -| 2026-10-11 | Proposed | Jens Tirsvad Nielsen | S01 | Added the verification results of task 2 (runner tools) | pending | +| 2026-10-11 | Proposed | Jens Tirsvad Nielsen | S01 | Added the verification results of task 2 (runner tools) | [32b5ab6] | --- @@ -114,3 +114,4 @@ network), a private runner with no internet, and an image that differs from [ADR-0005]: ../adr/adr-0005-quality-check-contract.md [ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.md [e3ad1fa]: https://git.tirsystem.com/TirSystem/github-action/commit/e3ad1fa7e7eef57a6793a479edb41ac6fd2db688 +[32b5ab6]: https://git.tirsystem.com/TirSystem/github-action/commit/32b5ab62ab5a82638b71b8fcfb43a819e92ab346 diff --git a/docs/uc-005/uc.md b/docs/uc-005/uc.md index 05961ad..6172b09 100644 --- a/docs/uc-005/uc.md +++ b/docs/uc-005/uc.md @@ -10,7 +10,7 @@ | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | | 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | [385d2fb] | -| 2026-10-11 | Proposed | Jens Tirsvad Nielsen | S01 | Brief extended to C++ and C# (MIL-007 task 1) | pending | +| 2026-10-11 | Proposed | Jens Tirsvad Nielsen | S01 | Brief extended to C++ and C# (MIL-007 task 1) | [32b5ab6] | --- @@ -44,3 +44,4 @@ A Software Engineer opens a pull request in a repository that calls the shared q [ADR-0005]: ../adr/adr-0005-quality-check-contract.md [MIL-007]: ../milestones/mil-007-cpp-csharp-quality-checks.md [385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7 +[32b5ab6]: https://git.tirsystem.com/TirSystem/github-action/commit/32b5ab62ab5a82638b71b8fcfb43a819e92ab346 diff --git a/docs/user-stories.md b/docs/user-stories.md index ac210f1..8afaa2a 100644 --- a/docs/user-stories.md +++ b/docs/user-stories.md @@ -10,7 +10,7 @@ | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | | 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added US-001.14 and US-001.15 (UC-007); US-001.13 traced to UC-007 (RC-046) | [4cf52af] | -| 2026-10-11 | Proposed | Jens Tirsvad Nielsen | S01 | Added US-001.16 and US-001.17 (C++ and C# checks, MIL-007 task 1) | pending | +| 2026-10-11 | Proposed | Jens Tirsvad Nielsen | S01 | Added US-001.16 and US-001.17 (C++ and C# checks, MIL-007 task 1) | [32b5ab6] | --- @@ -273,3 +273,4 @@ behaviour is tested rather than built. [UC-006]: ./uc-006/uc.md [UC-007]: ./uc-007/uc.md [4cf52af]: https://git.tirsystem.com/TirSystem/github-action/commit/4cf52afe00f546c6b20424fb8dfc12796ffd9296 +[32b5ab6]: https://git.tirsystem.com/TirSystem/github-action/commit/32b5ab62ab5a82638b71b8fcfb43a819e92ab346 -- 2.54.0