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