From 9ca9673b00351cf913966f347c4da09890ed3f1f Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Wed, 14 Oct 2026 13:41:14 +0800 Subject: [PATCH] MIL-010 task 1: use case UC-008, stories US-001.18 to US-001.20, RC-069 to RC-071 Refs #155 --- docs/artifact-registry.md | 4 +- docs/sqa/reviews/rc-069-uc-008.md | 55 ++++++++++++++++++++++ docs/sqa/reviews/rc-070-us-001-metrics.md | 50 ++++++++++++++++++++ docs/sqa/reviews/rc-071-ucd-001-metrics.md | 51 ++++++++++++++++++++ docs/sqa/traceability-matrix.md | 19 +++++--- docs/uc-008/uc.md | 43 +++++++++++++++++ docs/use-case-diagram.md | 13 +++-- docs/user-stories.md | 55 +++++++++++++++++++--- 8 files changed, 270 insertions(+), 20 deletions(-) create mode 100644 docs/sqa/reviews/rc-069-uc-008.md create mode 100644 docs/sqa/reviews/rc-070-us-001-metrics.md create mode 100644 docs/sqa/reviews/rc-071-ucd-001-metrics.md create mode 100644 docs/uc-008/uc.md diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index 50bd9a8..1d51d75 100644 --- a/docs/artifact-registry.md +++ b/docs/artifact-registry.md @@ -11,12 +11,12 @@ each document lives in *this* project and the next version to use. | SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 | | PP | Project Plan | docs/project-plan.md | 002 | | MIL | Milestone / Gateway | docs/milestones/*.md | 011 | -| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 069 | +| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 072 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | | ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0010 | | 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 | +| UC | Use Case | docs/uc-NNN/uc.md | 009 | ## Languages diff --git a/docs/sqa/reviews/rc-069-uc-008.md b/docs/sqa/reviews/rc-069-uc-008.md new file mode 100644 index 0000000..6798c0c --- /dev/null +++ b/docs/sqa/reviews/rc-069-uc-008.md @@ -0,0 +1,55 @@ +# Review Record: UC-008 (Show Code Metrics and Coverage Badges) + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-069 | +| CrossReference | [UC-008], [QC-UC-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; accepted | pending | + +--- + +## Artifact Under Review + +- Instance reviewed: [UC-008] +- Checklist used: [QC-UC-001] +- Scope: full review (Brief format; MIL-010 task 1) +- Language and domain: n/a (technical type) +- Language reviewer: none +- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan in chat on 2026-10-14) + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | Consists of a single, concise paragraph summarizing only the primary success scenario | Pass | One paragraph: push, count, read the report, publish three badges, README shows them. | +| 2 | Written as an informal multi-paragraph narrative; may mention some alternate flows without formal structure | N-A | Format is Brief. | +| 3 | All standard sections are present: actors, preconditions, postconditions, main success scenario, alternative/exception flows | N-A | Format is Brief; actor, stakeholders, pre- and postconditions and the paragraph are present. | +| 4 | Preconditions and postconditions are explicitly defined | Pass | Both are stated; the postcondition says that only the badges change. | +| 5 | Primary actor is explicitly stated | Pass | Software Engineer. | +| 6 | Stakeholders and their interests are stated | Pass | S02 and S05 with an interest each. | +| 7 | Main success scenario is written as clear, numbered steps | N-A | Format is Brief. | +| 8 | Alternative/exception flows correctly reference `<>`/`<>` use cases where relevant, per UML 2.5.1 | N-A | None in a Brief. | +| 9 | Explicit business rules are captured per step where applicable, rather than embedded loosely in narrative text | N-A | No steps in a Brief. | +| 10 | Naming of actors and use case title is consistent with the corresponding Use Case Diagram and User Stories | Pass | Title and actor equal UCD-001 (RC-071); the Stories line lists US-001.18 to US-001.20, which exist (RC-070). | +| 11 | Scope/level (e.g. summary, user-goal, subfunction) is explicitly stated | Pass | Scope Reusable Workflow Collection, user-goal level. | +| 12 | Use case is written from the actor's goal perspective, free of UI or implementation detail | Pass | Goal wording; no tool, file name or format of a report is named. | + +## Overall Verdict + +Go - all applicable criteria pass. The AI records the decision as stand-in for S01; there is no independent reader and the decision stays open to challenge in the run summary. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| None | - | - | + +--- + +[UC-008]: ../../uc-008/uc.md +[QC-UC-001]: ../../../framework/qc/artifacts/qc-use-case.md diff --git a/docs/sqa/reviews/rc-070-us-001-metrics.md b/docs/sqa/reviews/rc-070-us-001-metrics.md new file mode 100644 index 0000000..25ae7ee --- /dev/null +++ b/docs/sqa/reviews/rc-070-us-001-metrics.md @@ -0,0 +1,50 @@ +# Review Record: US-001 (stories US-001.18 to US-001.20) + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-070 | +| CrossReference | [US-001], [QC-US-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; accepted | pending | + +--- + +## Artifact Under Review + +- Instance reviewed: [US-001] +- Checklist used: [QC-US-001] +- Scope: delta re-review of the added stories US-001.18 to US-001.20 and the Purpose and Scope and INVEST sections; earlier record RC-057 (US-001.01 to US-001.17 unchanged) +- Language and domain: n/a (technical type) +- Language reviewer: none +- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan in chat on 2026-10-14) + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | Follows INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable) | Pass | US-001.18 to US-001.20 are independent of each other, each states one value and has checkable criteria; the INVEST section of US-001 now counts twenty stories. | +| 2 | Written in "As a / I want / So that" form | Pass | All three stories. | +| 3 | Clear, testable acceptance criteria are included | Pass | Each has Given/When/Then criteria with a pass and a fail case (a missing report, no files, unchanged numbers). | +| 4 | Traceable to a use case or epic | Pass | Each traces to [UC-008] and [MIL-010]. | +| 5 | Story is sized to fit within a single iteration | Pass | Each says: fits one iteration. | +| 6 | Story statement avoids technical implementation detail | Pass | The statements name badges, files, lines and coverage; format and branch names are left to the contract. | +| 7 | Role named in the story matches an actor defined in the Use Case Diagram | Pass | Software Engineer, an actor of UCD-001. | + +## Overall Verdict + +Go - all criteria pass. The AI records the decision as stand-in for S01; there is no independent reader and the decision stays open to challenge in the run summary. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| None | - | - | + +--- + +[US-001]: ../../user-stories.md +[QC-US-001]: ../../../framework/qc/artifacts/qc-user-story.md diff --git a/docs/sqa/reviews/rc-071-ucd-001-metrics.md b/docs/sqa/reviews/rc-071-ucd-001-metrics.md new file mode 100644 index 0000000..dc50bdf --- /dev/null +++ b/docs/sqa/reviews/rc-071-ucd-001-metrics.md @@ -0,0 +1,51 @@ +# Review Record: UCD-001 (Show Code Metrics and Coverage Badges) + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-071 | +| CrossReference | [UCD-001], [QC-UCD-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; accepted | pending | + +--- + +## Artifact Under Review + +- Instance reviewed: [UCD-001] +- Checklist used: [QC-UCD-001] +- Scope: delta re-review of the added use case UC8, the actor and use case tables; earlier record RC-045 +- Language and domain: n/a (technical type) +- Language reviewer: none +- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan in chat on 2026-10-14) + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | Actors are defined with correct UML stereotypes (e.g. `<>`, `<>`) | Pass | Unchanged; no new actor. | +| 2 | System boundary is clearly drawn and labeled | Pass | The new use case is inside the Reusable Workflow Collection rectangle. | +| 3 | Include/extend relationships are used correctly per UML 2.5.1, not as generic "uses" arrows | Pass | The new use case has no include or extend; the existing two are unchanged. | +| 4 | Every actor participates in at least one use case (no orphan actors) | Pass | Software Engineer is linked to UC5, UC7 and UC8. | +| 5 | Diagram is traceable to a documented stakeholder need | Pass | S02 and S05 interests are in UC-008; the actor table lists S02. | +| 6 | Use case names are verb phrases describing actor goals, not internal system operations | Pass | Show Code Metrics and Coverage Badges. | +| 7 | Diagram is free of implementation detail (e.g. UI widgets, database tables) | Pass | None added. | +| 8 | Actor and use case naming is consistent with corresponding Use Case and User Story documents | Pass | Equals the title of UC-008 and the role of US-001.18 to US-001.20. | + +## Overall Verdict + +Go - all criteria pass. The AI records the decision as stand-in for S01; there is no independent reader and the decision stays open to challenge in the run summary. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| None | - | - | + +--- + +[UCD-001]: ../../use-case-diagram.md +[QC-UCD-001]: ../../../framework/qc/artifacts/qc-use-case-diagram.md diff --git a/docs/sqa/traceability-matrix.md b/docs/sqa/traceability-matrix.md index 4bfdcdb..20cbbbf 100644 --- a/docs/sqa/traceability-matrix.md +++ b/docs/sqa/traceability-matrix.md @@ -4,13 +4,13 @@ | Key | Value | | --- | --- | | ID | TM-001 | -| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010], [RC-001], [RC-002], [RC-003], [RC-004], [RC-005], [RC-006], [RC-007], [RC-008], [RC-009], [RC-010], [RC-011], [RC-012], [RC-013], [RC-014], [RC-015], [RC-016], [RC-017], [RC-018], [RC-019], [RC-020], [RC-021], [RC-022], [RC-023], [RC-024], [RC-025], [RC-026], [RC-027], [RC-028], [RC-029], [RC-030], [RC-031], [RC-032], [RC-033], [RC-034], [RC-035], [RC-036], [RC-037], [RC-038], [RC-039], [RC-040], [RC-041], [RC-042], [RC-043], [RC-044], [RC-045], [RC-046], [RC-047], [RC-048], [RC-049], [RC-050], [RC-051], [RC-052], [RC-053], [RC-054], [RC-055], [RC-056], [RC-057], [RC-058], [RC-059], [RC-060], [RC-061], [RC-062], [RC-063], [RC-064], [RC-065], [RC-066], [RC-067], [RC-068], [ADR-0007], [ADR-0008], [ADR-0009], [UC-007], [UC-006], [ADR-0006], [UC-005], [ADR-0005], [UCD-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [ADR-0001], [ADR-0002], [ADR-0003], [ADR-0004] | +| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010], [UC-008], [RC-001], [RC-002], [RC-003], [RC-004], [RC-005], [RC-006], [RC-007], [RC-008], [RC-009], [RC-010], [RC-011], [RC-012], [RC-013], [RC-014], [RC-015], [RC-016], [RC-017], [RC-018], [RC-019], [RC-020], [RC-021], [RC-022], [RC-023], [RC-024], [RC-025], [RC-026], [RC-027], [RC-028], [RC-029], [RC-030], [RC-031], [RC-032], [RC-033], [RC-034], [RC-035], [RC-036], [RC-037], [RC-038], [RC-039], [RC-040], [RC-041], [RC-042], [RC-043], [RC-044], [RC-045], [RC-046], [RC-047], [RC-048], [RC-049], [RC-050], [RC-051], [RC-052], [RC-053], [RC-054], [RC-055], [RC-056], [RC-057], [RC-058], [RC-059], [RC-060], [RC-061], [RC-062], [RC-063], [RC-064], [RC-065], [RC-066], [RC-067], [RC-068], [RC-069], [RC-070], [RC-071], [ADR-0007], [ADR-0008], [ADR-0009], [UC-007], [UC-006], [ADR-0006], [UC-005], [ADR-0005], [UCD-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [ADR-0001], [ADR-0002], [ADR-0003], [ADR-0004] | ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | Added RC-066 (MIL-009 outcome) | [95abc18] | | 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | Added MIL-010, RC-067 and RC-068 (code metrics and coverage badges) | [5002450] | +| 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | Added UC-008, RC-069 to RC-071 (code metrics badges, MIL-010 task 1) | pending | --- @@ -59,8 +59,8 @@ updated whenever an artifact instance is created or reviewed. | [RC-016] | RC | [MIL-006] | - | - | | [RC-017] | RC | [PP-001] | - | - | | [RC-018] | RC | [ADR-0004] | - | - | -| [UCD-001] | UCD | [SA-001], [BC-001] | [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007] | [RC-019], [RC-035], [RC-040], [RC-045] | -| [US-001] | US | [UCD-001], [BC-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-007] | [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007] | [RC-020], [RC-036], [RC-041], [RC-046], [RC-057] | +| [UCD-001] | UCD | [SA-001], [BC-001] | [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007], [UC-008] | [RC-019], [RC-035], [RC-040], [RC-045], [RC-071] | +| [US-001] | US | [UCD-001], [BC-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-007] | [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007], [UC-008] | [RC-020], [RC-036], [RC-041], [RC-046], [RC-057], [RC-070] | | [UC-001] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-021] | | [UC-002] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-022] | | [UC-003] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-023] | @@ -73,6 +73,7 @@ updated whenever an artifact instance is created or reviewed. | [ADR-0008] | ADR | [MIL-007], [UC-005], [US-001], [ADR-0005], [ADR-0006] | - | [RC-054] | | [ADR-0009] | ADR | [MIL-008], [ADR-0003], [ADR-0004], [ADR-0005], [ADR-0006] | - | [RC-063] | | [UC-007] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-044] | +| [UC-008] | UC | [UCD-001], [US-001], [SA-001], [MIL-010] | - | [RC-069] | | [RC-019] | RC | [UCD-001] | - | - | | [RC-020] | RC | [US-001] | - | - | | [RC-021] | RC | [UC-001] | - | - | @@ -123,6 +124,9 @@ updated whenever an artifact instance is created or reviewed. | [RC-066] | RC | [MIL-009] | - | - | | [RC-067] | RC | [BC-001] | - | - | | [RC-068] | RC | [MIL-010], [PP-001] | - | - | +| [RC-069] | RC | [UC-008] | - | - | +| [RC-070] | RC | [US-001] | - | - | +| [RC-071] | RC | [UCD-001] | - | - | ## Coverage Notes @@ -224,15 +228,16 @@ updated whenever an artifact instance is created or reviewed. [RC-066]: ./reviews/rc-066-mil-009-outcome.md [RC-067]: ./reviews/rc-067-bc-001-o5.md [RC-068]: ./reviews/rc-068-mil-010-plan.md +[RC-069]: ./reviews/rc-069-uc-008.md +[RC-070]: ./reviews/rc-070-us-001-metrics.md +[RC-071]: ./reviews/rc-071-ucd-001-metrics.md [ADR-0008]: ../adr/adr-0008-cpp-csharp-quality-check-contract.md [ADR-0009]: ../adr/adr-0009-wiki-publishing-reusable-workflow.md [ADR-0007]: ../adr/adr-0007-release-publish-destination.md [UC-007]: ../uc-007/uc.md +[UC-008]: ../uc-008/uc.md [UC-006]: ../uc-006/uc.md [ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.md [UC-005]: ../uc-005/uc.md [ADR-0005]: ../adr/adr-0005-quality-check-contract.md -[faf13b2]: https://git.tirsystem.com/TirSystem/github-action/commit/faf13b2c2a4901c0171977de1ffc2841023f537a -[1bc56f8]: https://git.tirsystem.com/TirSystem/github-action/commit/1bc56f8b771531f221f218fc00b147ecc73c051e -[95abc18]: https://git.tirsystem.com/TirSystem/github-action/commit/95abc18a95d70c065b979123b8f8de22173af90c [5002450]: https://git.tirsystem.com/TirSystem/github-action/commit/50024505fe788b1c5e3021c0d1fc3d079590070e diff --git a/docs/uc-008/uc.md b/docs/uc-008/uc.md new file mode 100644 index 0000000..442d4a1 --- /dev/null +++ b/docs/uc-008/uc.md @@ -0,0 +1,43 @@ +# UC-008: Show Code Metrics and Coverage Badges + +## Metadata +| Key | Value | +| --- | --- | +| ID | UC-008 | +| CrossReference | [UCD-001], [US-001], [SA-001], [MIL-010] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; reviewed (RC-069) | pending | + +--- + +**Format:** Brief + +**Title:** Show Code Metrics and Coverage Badges +**Scope:** Reusable Workflow Collection +**Level:** user-goal +**Primary Actor:** Software Engineer +**Stakeholders:** S02, S05 (interests below) +**Stories:** US-001.18, US-001.19, US-001.20 + +## Brief + +A Software Engineer pushes a change to a repository that calls the shared code-metrics workflow. The workflow counts the code files and the lines of code (without comment and blank lines), reads the coverage report the repository supplies, and publishes three badges: the number of code files, the number of lines of code and the coverage. The repository's README shows the badges, and they show the numbers of the latest push. + +**Stakeholder interests** + +- S02 — the size and the coverage of the code are visible at a glance, without a service outside the instance, and a wrong or missing report is reported instead of shown as a number +- S05 — the counting rules and the badge contract are defined once and change through a reviewed release + +**Preconditions:** The repository is onboarded and the shared workflow is available through reusable workflow delivery; a coverage badge needs a coverage report that the repository's own tests have produced. + +**Postconditions (success guarantee):** The three badges show the numbers of the pushed revision, nothing but the badges is changed in the repository, and a run whose numbers are unchanged changes nothing. + +--- + +[UCD-001]: ../use-case-diagram.md +[US-001]: ../user-stories.md +[SA-001]: ../stakeholder-analysis.md +[MIL-010]: ../milestones/mil-010-code-metrics-badges.md diff --git a/docs/use-case-diagram.md b/docs/use-case-diagram.md index c63d73d..7a7ae5f 100644 --- a/docs/use-case-diagram.md +++ b/docs/use-case-diagram.md @@ -4,13 +4,13 @@ | Key | Value | | --- | --- | | ID | UCD-001 | -| CrossReference | [SA-001], [BC-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007] | +| CrossReference | [SA-001], [BC-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007], [UC-008] | ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added the use case Release a Reusable Workflow (UC-006) | [044d8ba] | -| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added the use case Consume a Workflow Update (UC-007) (RC-045) | [4cf52af] | +| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added the use case Consume a Workflow Update (UC-007) (RC-045) | [4cf52af] | +| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added the use case Show Code Metrics and Coverage Badges (UC-008); reviewed (RC-071) | pending | --- @@ -46,6 +46,7 @@ rectangle "Reusable Workflow Collection" <> { usecase "Run Project Quality Checks" as UC5 usecase "Release a Reusable Workflow" as UC6 usecase "Consume a Workflow Update" as UC7 + usecase "Show Code Metrics and Coverage Badges" as UC8 } DevOps --> UC1 @@ -57,6 +58,7 @@ Operator --> UC2 Operator --> UC4 Engineer --> UC5 Engineer --> UC7 +Engineer --> UC8 UC1 --> Gitea UC1 --> GitHub UC3 ..> UC2 : <> @@ -70,7 +72,7 @@ UC4 ..> UC1 : <> | --- | --- | --- | --- | | DevOps Professional | `<>` | S05 | Synchronize Repository Metadata, Configure Workflow Credentials, Onboard a Repository, Diagnose a Failed Workflow, Release a Reusable Workflow | | Platform Operator | `<>` | S03 | Configure Workflow Credentials, Diagnose a Failed Workflow | -| Software Engineer | `<>` | S02 | Run Project Quality Checks, Consume a Workflow Update | +| Software Engineer | `<>` | S02 | Run Project Quality Checks, Consume a Workflow Update, Show Code Metrics and Coverage Badges | | Gitea Instance | `<>` | - | Synchronize Repository Metadata (source of description and topics) | | GitHub | `<>` | S04 (audience of the mirror) | Synchronize Repository Metadata (target) | @@ -85,6 +87,7 @@ UC4 ..> UC1 : <> | Run Project Quality Checks | Software Engineer | Lint, format and type checks run on every change and report a pass or a fail | | Release a Reusable Workflow | DevOps Professional | A validated, versioned update that consumers can pin | | Consume a Workflow Update | Software Engineer | A new version is adopted safely, one repository first | +| Show Code Metrics and Coverage Badges | Software Engineer | The size and the coverage of the code are visible as badges that follow every push | ## Relationships @@ -104,6 +107,6 @@ UC4 ..> UC1 : <> [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 +[UC-008]: ./uc-008/uc.md [4cf52af]: https://git.tirsystem.com/TirSystem/github-action/commit/4cf52afe00f546c6b20424fb8dfc12796ffd9296 diff --git a/docs/user-stories.md b/docs/user-stories.md index 810f17f..9f09556 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], [MIL-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], [UC-008], [MIL-010] | ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-11 | Deprecated | Jens Tirsvad Nielsen | S01 | Added US-001.16 and US-001.17 (C++ and C# checks, MIL-007 task 1) | [32b5ab6] | -| 2026-10-11 | Accepted | Jens Tirsvad Nielsen | S01 | US-001.16 and US-001.17 reviewed (RC-057) and accepted; the Purpose and Scope names the later stories | [1bc56f8] | +| 2026-10-11 | Deprecated | Jens Tirsvad Nielsen | S01 | US-001.16 and US-001.17 reviewed (RC-057) and accepted; the Purpose and Scope names the later stories | [1bc56f8] | +| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added US-001.18 to US-001.20 (code metrics and coverage badges, MIL-010 task 1); reviewed (RC-070) | pending | --- @@ -21,7 +21,8 @@ These stories cover the P1 use cases of the Project Plan that MIL-002 delivers credentials, onboarding a repository and diagnosing a failed run. Roles are the actors of [UCD-001]. Later stories cover quality checks (US-001.09, US-001.10 and, for C++ and C#, US-001.16 and US-001.17), releases and updates (US-001.11 to -US-001.15). Stories for the wiki (MIL-005, MIL-006) are not written yet. +US-001.15) and the code metrics and coverage badges (US-001.18 to +US-001.20). Stories for the wiki (MIL-005, MIL-006) are not written yet. ## Story List @@ -248,9 +249,50 @@ US-001.15). Stories for the wiki (MIL-005, MIL-006) are not written yet. | --- | --- | --- | | [UC-005], [MIL-007] | fits one iteration | none | +### US-001.18 — The size of the code is visible as badges + +**As a** Software Engineer, **I want** badges that show the number of code files and the number of lines of code without comment and blank lines, **so that** the size of the project is visible in its README without a service outside the instance. + +**Acceptance Criteria** + +- Given a repository that calls the shared code-metrics workflow, when a change is pushed, then a badge for the code files and a badge for the lines of code show the numbers of that revision. +- Given a file with a comment line, a blank line and a code line, when the lines are counted, then only the code line is counted as a line of code. +- Given a repository without a file of a supported language, when the workflow runs, then it passes with a notice and the badges show zero. + +| Traces to | Size | INVEST exceptions | +| --- | --- | --- | +| [UC-008], [MIL-010] | fits one iteration | none | + +### US-001.19 — The coverage is visible as a badge + +**As a** Software Engineer, **I want** a badge that shows how much of the code my tests cover, **so that** a drop in coverage is seen as soon as it is pushed. + +**Acceptance Criteria** + +- Given a repository that supplies a coverage report, when a change is pushed, then a coverage badge shows the percentage of the report, and its colour follows the thresholds of the contract. +- Given a coverage report that is missing or that cannot be read, when the workflow runs, then it fails with a `[configuration]` message that names the report file and no coverage badge is changed. +- Given a repository that supplies no coverage report, when the workflow runs, then it passes with a notice and publishes no coverage badge. + +| Traces to | Size | INVEST exceptions | +| --- | --- | --- | +| [UC-008], [MIL-010] | fits one iteration | none | + +### US-001.20 — A run with unchanged numbers changes nothing + +**As a** Software Engineer, **I want** the workflow to commit nothing when the numbers did not change, **so that** the history of the repository is not filled with badge commits. + +**Acceptance Criteria** + +- Given a push after which none of the three badges would differ, when the workflow runs, then no commit is made. +- Given a push after which a number changed, when the workflow runs, then one commit changes only the badge files, and the workflow does not start again from that commit. + +| Traces to | Size | INVEST exceptions | +| --- | --- | --- | +| [UC-008], [MIL-010] | fits one iteration | none | + ## INVEST Check -All seventeen stories are independent of each other except that US-001.05 and +All twenty 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 @@ -274,5 +316,6 @@ behaviour is tested rather than built. [UC-005]: ./uc-005/uc.md [UC-006]: ./uc-006/uc.md [UC-007]: ./uc-007/uc.md -[32b5ab6]: https://git.tirsystem.com/TirSystem/github-action/commit/32b5ab62ab5a82638b71b8fcfb43a819e92ab346 +[UC-008]: ./uc-008/uc.md +[MIL-010]: ./milestones/mil-010-code-metrics-badges.md [1bc56f8]: https://git.tirsystem.com/TirSystem/github-action/commit/1bc56f8b771531f221f218fc00b147ecc73c051e