diff --git a/docs/adr/adr-0005-quality-check-contract.md b/docs/adr/adr-0005-quality-check-contract.md new file mode 100644 index 0000000..02944b7 --- /dev/null +++ b/docs/adr/adr-0005-quality-check-contract.md @@ -0,0 +1,124 @@ +# ADR-0005: Contract of the shared quality-check workflow + +## Metadata +| Key | Value | +| --- | --- | +| ID | ADR-0005 | +| CrossReference | [MIL-003], [UC-005], [US-001], [ADR-0004] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | [385d2fb] | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Reviewed (RC-038): the security impact of installing the tools from PyPI named | [385d2fb] | + +Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`. + +--- + +## Context + +MIL-003 offers one workflow that any repository calls to run lint, format and +type checks. Before it is built (task 3) its inputs and the meaning of a pass +and a fail must be fixed, because consumers in four organizations will depend +on them and MIL-004 will version them. Facts found on 2026-10-10: + +- The runner image (Ubuntu 24.04, Python 3.12, `git`, Node.js, `jq`, `make`, + run as `root`) has **none** of ruff, mypy, pytest, shellcheck or shfmt. +- PyPI is reachable, and a virtual environment installs all four tools with + pinned versions: `ruff` 0.6.9, `mypy` 1.11.2, `shellcheck-py` 0.10.0.1 + (ShellCheck 0.10.0) and `shfmt-py` 3.11.0.2 (shfmt 3.11.0). +- Each tool exits non-zero on a finding and prints `path:line` and a message. + `shellcheck` also exits 1 on an empty file, so a language with no files must + be skipped before the tool runs. +- Reusable workflows work from the same repository and from other + organizations (issue #15). Secrets passing is untested, and the checks need + none. +- The conventions name the tools: ruff and `mypy --strict` for Python + (QC-PY-001) and shellcheck and shfmt for shell (QC-SH-001). + +Options for the shape of the workflow: + +1. **One reusable workflow with a `languages` input** that selects the tool + sets, defaults that work with no configuration, and one version input per + tool. +2. **One reusable workflow per language** (`python-checks.yml`, + `shell-checks.yml`). Simple, but a mixed repository calls two workflows and + the contract exists twice. +3. **Detect the languages from the files and take no inputs.** Zero + configuration, but a repository cannot opt out of a tool, and versions + change only with the workflow. +4. **The consumer passes its own commands.** Most flexible, but it is not a + shared check any more and defeats the point of a contract. + +## Decision + +The shared workflow `quality-checks.yml` is one reusable workflow with the +inputs `languages` (a comma list of `python` and `shell`, default both), +`working-directory` (default `.`) and one version input per tool whose +defaults are the pinned versions above, and it installs the tools from PyPI +into a virtual environment. A run passes when every selected tool exits 0 and +fails when any exits non-zero, and a language with no files is skipped with a +notice and counts as a pass. + +The rules that follow from it: + +- **Python:** `ruff check`, `ruff format --check` and `mypy --strict`, run on + the files under `working-directory`. +- **Shell:** the tracked `*.sh` files are checked with `shellcheck` and + `shfmt -d`. +- **Configuration:** projects configure the tools in the standard way + (`pyproject.toml`, `.shellcheckrc`, `.editorconfig`); the workflow adds none + and changes no file. +- **Reporting:** each tool runs in its own log group named after the tool, and + its own output carries `path:line` and the message; the job status is the + pull request status. +- **Out of scope for the first version:** running the project's tests + (`pytest` needs the project's dependencies), auto-fixing, and other + languages. + +## Consequences + +**Positive:** + +- A repository gets the checks with one `uses:` and no configuration, and a + mixed repository gets both language sets from one call. +- Tool versions are explicit and reviewed, so a new tool release cannot turn + every consumer red overnight. +- A failure is read from the tool's own message, so the workflow needs no + parser of its own. + +**Negative:** + +- Every run installs the tools from PyPI (about half a minute) and depends on + PyPI being reachable; caching is not part of the first version. +- Projects that need their tests or their own dependencies in the type check + (`mypy` with third-party stubs) must configure that themselves or wait for a + later version. +- `mypy --strict` on an existing codebase is likely to fail at first; a + project that cannot meet it has to configure the tool, which weakens the + shared meaning of "pass". +- Pinned versions need a release (MIL-004) to move; until then they are + updated by changing the workflow on `main`. +- **Security:** the tools are downloaded from PyPI on every run and execute + with the consumer's repository content on a runner that runs as `root`. + Versions are pinned but the packages are not hash-pinned, so a + compromised release of one of the four packages would reach every + consumer; hash pinning is a later hardening step. + +## Affected Artifacts + +- [MIL-003] — tasks 3 to 5 (issues #17 to #19) implement, adopt and document + this contract. +- [UC-005] — the use case this contract serves. +- [US-001] — stories US-001.09 and US-001.10 state its acceptance criteria. +- [ADR-0004] — the same pattern of a shared scoped or reusable workflow with an + explicit gate; this ADR does not change it. + +--- + +[MIL-003]: ../milestones/mil-003-quality-checks.md +[UC-005]: ../uc-005/uc.md +[US-001]: ../user-stories.md +[ADR-0004]: ./adr-0004-shared-wiki-publishing-opt-in.md +[385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7 diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index 12b0220..55ad91f 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 | 007 | -| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 035 | +| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 039 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | -| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0005 | +| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0006 | | 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 | 005 | +| UC | Use Case | docs/uc-NNN/uc.md | 006 | ## Languages diff --git a/docs/sqa/reviews/rc-035-ucd-001.md b/docs/sqa/reviews/rc-035-ucd-001.md new file mode 100644 index 0000000..0b4e5bf --- /dev/null +++ b/docs/sqa/reviews/rc-035-ucd-001.md @@ -0,0 +1,48 @@ +# Review Record: UCD-001 (quality checks) + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-035 | +| CrossReference | [UCD-001], [QC-UCD-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | [385d2fb] | + +--- + +## Artifact Under Review + +- Instance reviewed: [UCD-001] +- Checklist used: [QC-UCD-001] + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | Actors are defined with correct UML stereotypes (e.g. `<>`, `<>`) | Pass | Software Engineer is `<>`, like the others. | +| 2 | System boundary is clearly drawn and labeled | Pass | Unchanged. | +| 3 | Include/extend relationships are used correctly per UML 2.5.1, not as generic "uses" arrows | Pass | Unchanged; the new use case has none. | +| 4 | Every actor participates in at least one use case (no orphan actors) | Pass | Software Engineer reaches Run Project Quality Checks. | +| 5 | Diagram is traceable to a documented stakeholder need | Pass | S02 in the Actor Table. | +| 6 | Use case names are verb phrases describing actor goals, not internal system operations | Pass | "Run Project Quality Checks". | +| 7 | Diagram is free of implementation detail (e.g. UI widgets, database tables) | Pass | No tool or file named. | +| 8 | Actor and use case naming is consistent with corresponding Use Case and User Story documents | Pass | Checked mechanically: UC-005's title and the story role match. | + +## Overall Verdict + +Go - all eight criteria pass for the amendment (the actor and use case of UC-005). S01 gave the Go in chat on 2026-10-10, standing in for the other reviewers as ADR-0002 records; there is no independent reader. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| None | - | - | + +--- + +[UCD-001]: ../../use-case-diagram.md +[QC-UCD-001]: ../../../framework/qc/qc-use-case-diagram.md +[385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7 diff --git a/docs/sqa/reviews/rc-036-us-001.md b/docs/sqa/reviews/rc-036-us-001.md new file mode 100644 index 0000000..bbb10ca --- /dev/null +++ b/docs/sqa/reviews/rc-036-us-001.md @@ -0,0 +1,47 @@ +# Review Record: US-001 (quality checks) + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-036 | +| CrossReference | [US-001], [QC-US-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | [385d2fb] | + +--- + +## Artifact Under Review + +- Instance reviewed: [US-001] +- Checklist used: [QC-US-001] + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | Follows INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable) | Pass | INVEST check updated to ten stories; the two new ones are independent of the others. | +| 2 | Written in "As a / I want / So that" form | Pass | US-001.09 and US-001.10. | +| 3 | Clear, testable acceptance criteria are included | Pass | Two Given/When/Then criteria each, matching the ADR-0005 contract. | +| 4 | Traceable to a use case or epic | Pass | UC-005 and MIL-003. | +| 5 | Story is sized to fit within a single iteration | Pass | One goal each. | +| 6 | Story statement avoids technical implementation detail | Pass | No tool named in the statements. | +| 7 | Role named in the story matches an actor defined in the Use Case Diagram | Pass | Software Engineer is in UCD-001. | + +## Overall Verdict + +Go - all seven criteria pass for the two added stories. S01 gave the Go in chat on 2026-10-10, standing in for the other reviewers as ADR-0002 records; there is no independent reader. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| None | - | - | + +--- + +[US-001]: ../../user-stories.md +[QC-US-001]: ../../../framework/qc/qc-user-story.md +[385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7 diff --git a/docs/sqa/reviews/rc-037-uc-005.md b/docs/sqa/reviews/rc-037-uc-005.md new file mode 100644 index 0000000..d64f71e --- /dev/null +++ b/docs/sqa/reviews/rc-037-uc-005.md @@ -0,0 +1,52 @@ +# Review Record: UC-005 (quality checks) + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-037 | +| CrossReference | [UC-005], [QC-UC-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | [385d2fb] | + +--- + +## Artifact Under Review + +- Instance reviewed: [UC-005] +- Checklist used: [QC-UC-001] (Brief format) + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | Consists of a single, concise paragraph summarizing only the primary success scenario | Pass | Finding fixed during this review: the paragraph also described the failure output; it now summarizes only the main success scenario (the failure is US-001.10). | +| 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 stated. | +| 5 | Primary actor is explicitly stated | Pass | Software Engineer. | +| 6 | Stakeholders and their interests are stated | Pass | S02 and S05. | +| 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 | No alternative flows in a Brief use case. | +| 9 | Explicit business rules are captured per step where applicable, rather than embedded loosely in narrative text | N-A | No steps in a Brief use case. | +| 10 | Naming of actors and use case title is consistent with the corresponding Use Case Diagram and User Stories | Pass | Title and actor match UCD-001 and US-001. | +| 11 | Scope/level (e.g. summary, user-goal, subfunction) is explicitly stated | Pass | Scope and 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 named. | + +## Overall Verdict + +Go - all applicable criteria pass; the one finding (criterion 1) was fixed during the review. S01 gave the Go in chat on 2026-10-10, standing in for the other reviewers as ADR-0002 records; there is no independent reader. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| None | - | - | + +--- + +[UC-005]: ../../uc-005/uc.md +[QC-UC-001]: ../../../framework/qc/qc-use-case.md +[385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7 diff --git a/docs/sqa/reviews/rc-038-adr-0005.md b/docs/sqa/reviews/rc-038-adr-0005.md new file mode 100644 index 0000000..62417fd --- /dev/null +++ b/docs/sqa/reviews/rc-038-adr-0005.md @@ -0,0 +1,51 @@ +# Review Record: ADR-0005 (quality checks) + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-038 | +| CrossReference | [ADR-0005], [QC-ADR-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | [385d2fb] | + +--- + +## Artifact Under Review + +- Instance reviewed: [ADR-0005] +- Checklist used: [QC-ADR-001] + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | The ID (`ADR-NNNN`, 4-digit) matches the filename number and is unique and sequential | Pass | ADR-0005 in `adr-0005-quality-check-contract.md`. | +| 2 | Context states the problem, the forces (cost, risk, constraints) and the options evaluated | Pass | Facts measured on the runner on 2026-10-10 and four options. | +| 3 | At least two options were considered, or the absence of alternatives is justified | Pass | Four options. | +| 4 | Decision is stated in one or two unhedged sentences and matches one of the evaluated options | Pass | Two sentences; option 1. | +| 5 | Consequences list both Positive and Negative outcomes | Pass | Three positive and five negative after the fix. | +| 6 | Quality-attribute impacts (performance, security, portability, etc.) are named where the decision affects them | Pass | Finding fixed during this review: the security impact (tools downloaded from PyPI on every run, versions pinned but not hash-pinned, runner runs as root) was not named. It is now a negative consequence; performance and reliability were already named. | +| 7 | Affected Artifacts are listed as links, and each is also in CrossReference | Pass | MIL-003, UC-005, US-001 and ADR-0004 are linked and cited. | +| 8 | Status changes are recorded as new Version History rows with a Change summary and Commit link; retained rows are never rewritten | Pass | The earlier row is kept and only its status changed. | +| 9 | A superseded or deprecated ADR names its successor, and the successor links back | N-A | Nothing is superseded. | +| 10 | Written in business or technical language of the domain, with no unexplained abbreviations | Pass | PyPI, venv and the tools are named where used. | +| 11 | Status is one of `Proposed`, `Accepted`, `Rejected`, `Deprecated` or `Superseded by ADR-NNNN`, and every Version History row uses only these | Pass | Deprecated and Accepted only. | + +## Overall Verdict + +Go - all applicable criteria pass; the one finding (criterion 6) was fixed during the review. The contract unlocks tasks 3 to 5 of MIL-003 under the plan-first gate. S01 gave the Go in chat on 2026-10-10, standing in for the other reviewers as ADR-0002 records; there is no independent reader. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| Decide whether to hash-pin the tool packages before consumers outside this organization rely on the workflow (MIL-004) | S05 | 2026-11-28 | + +--- + +[ADR-0005]: ../../adr/adr-0005-quality-check-contract.md +[QC-ADR-001]: ../../../framework/qc/qc-adr.md +[385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7 diff --git a/docs/sqa/traceability-matrix.md b/docs/sqa/traceability-matrix.md index ad34525..527e4d1 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], [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], [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], [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], [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-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added RC-033 for MIL-003 | [b3f006f] | -| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added RC-034 for MIL-004 | [616c5d2] | +| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added RC-034 for MIL-004 | [616c5d2] | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added UC-005, ADR-0005 and RC-035 to RC-038 | [385d2fb] | --- @@ -55,12 +55,14 @@ 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] | [RC-019] | -| [US-001] | US | [UCD-001], [BC-001], [MIL-001], [MIL-002] | [UC-001], [UC-002], [UC-003], [UC-004] | [RC-020] | +| [UCD-001] | UCD | [SA-001], [BC-001] | [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005] | [RC-019], [RC-035] | +| [US-001] | US | [UCD-001], [BC-001], [MIL-001], [MIL-002], [MIL-003] | [UC-001], [UC-002], [UC-003], [UC-004], [UC-005] | [RC-020], [RC-036] | | [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] | | [UC-004] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-024] | +| [UC-005] | UC | [UCD-001], [US-001], [SA-001] | [ADR-0005] | [RC-037] | +| [ADR-0005] | ADR | [MIL-003], [UC-005], [US-001], [ADR-0004] | - | [RC-038] | | [RC-019] | RC | [UCD-001] | - | - | | [RC-020] | RC | [US-001] | - | - | | [RC-021] | RC | [UC-001] | - | - | @@ -77,6 +79,10 @@ updated whenever an artifact instance is created or reviewed. | [RC-032] | RC | [PP-001] | - | - | | [RC-033] | RC | [MIL-003] | - | - | | [RC-034] | RC | [MIL-004] | - | - | +| [RC-035] | RC | [UCD-001] | - | - | +| [RC-036] | RC | [US-001] | - | - | +| [RC-037] | RC | [UC-005] | - | - | +| [RC-038] | RC | [ADR-0005] | - | - | ## Coverage Notes @@ -140,5 +146,11 @@ updated whenever an artifact instance is created or reviewed. [RC-032]: ./reviews/rc-032-pp-001-dates.md [RC-033]: ./reviews/rc-033-mil-003-reusable-workflows.md [RC-034]: ./reviews/rc-034-mil-004-scripts.md -[b3f006f]: https://git.tirsystem.com/TirSystem/github-action/commit/b3f006f7a482392189a46c324ad4f28c4c3a2d2a +[RC-035]: ./reviews/rc-035-ucd-001.md +[RC-036]: ./reviews/rc-036-us-001.md +[RC-037]: ./reviews/rc-037-uc-005.md +[RC-038]: ./reviews/rc-038-adr-0005.md +[UC-005]: ../uc-005/uc.md +[ADR-0005]: ../adr/adr-0005-quality-check-contract.md [616c5d2]: https://git.tirsystem.com/TirSystem/github-action/commit/616c5d2e48f0d76399a6f78923891fc7f50c8e22 +[385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7 diff --git a/docs/uc-005/uc.md b/docs/uc-005/uc.md new file mode 100644 index 0000000..71539c6 --- /dev/null +++ b/docs/uc-005/uc.md @@ -0,0 +1,44 @@ +# UC-005: Run Project Quality Checks + +## Metadata +| Key | Value | +| --- | --- | +| ID | UC-005 | +| CrossReference | [UCD-001], [US-001], [SA-001], [ADR-0005] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | [385d2fb] | + +--- + +**Format:** Brief + +**Title:** Run Project Quality Checks +**Scope:** Reusable Workflow Collection +**Level:** user-goal +**Primary Actor:** Software Engineer +**Stakeholders:** S02, S05 (interests below) +**Stories:** US-001.09, US-001.10 + +## 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. + +**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. + +**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. + +--- + +[UCD-001]: ../use-case-diagram.md +[US-001]: ../user-stories.md +[SA-001]: ../stakeholder-analysis.md +[ADR-0005]: ../adr/adr-0005-quality-check-contract.md +[385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7 diff --git a/docs/use-case-diagram.md b/docs/use-case-diagram.md index 474f338..8a285f1 100644 --- a/docs/use-case-diagram.md +++ b/docs/use-case-diagram.md @@ -4,12 +4,13 @@ | Key | Value | | --- | --- | | ID | UCD-001 | -| CrossReference | [SA-001], [BC-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004] | +| CrossReference | [SA-001], [BC-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005] | ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | [a2bf2d4] | +| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | [a2bf2d4] | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added the actor Software Engineer and the use case Run Project Quality Checks | [385d2fb] | --- @@ -21,8 +22,8 @@ them. Inside it are the four P1 goals of the Project Plan: keeping the GitHub mirror's description and topics equal to Gitea's, configuring the credentials a workflow needs, bringing a repository onto the shared workflows, and finding the cause of a failed run. Gitea and GitHub are outside the boundary and are -shown as external systems. Quality checks and releases (P2) and the software -engineer's use cases (P2, P3) are not drawn yet. +shown as external systems. Running quality checks is the first software engineer goal +(P2). Releases and the other P2 and P3 use cases are not drawn yet. ## Diagram @@ -33,6 +34,7 @@ skinparam packageStyle rectangle actor "DevOps Professional" as DevOps <> actor "Platform Operator" as Operator <> +actor "Software Engineer" as Engineer <> actor "Gitea Instance" as Gitea <> actor "GitHub" as GitHub <> @@ -41,6 +43,7 @@ rectangle "Reusable Workflow Collection" <> { usecase "Configure Workflow Credentials" as UC2 usecase "Onboard a Repository" as UC3 usecase "Diagnose a Failed Workflow" as UC4 + usecase "Run Project Quality Checks" as UC5 } DevOps --> UC1 @@ -49,6 +52,7 @@ DevOps --> UC3 DevOps --> UC4 Operator --> UC2 Operator --> UC4 +Engineer --> UC5 UC1 --> Gitea UC1 --> GitHub UC3 ..> UC2 : <> @@ -62,6 +66,7 @@ UC4 ..> UC1 : <> | --- | --- | --- | --- | | DevOps Professional | `<>` | S05 | Synchronize Repository Metadata, Configure Workflow Credentials, Onboard a Repository, Diagnose a Failed Workflow | | Platform Operator | `<>` | S03 | Configure Workflow Credentials, Diagnose a Failed Workflow | +| Software Engineer | `<>` | S02 | Run Project Quality Checks | | Gitea Instance | `<>` | - | Synchronize Repository Metadata (source of description and topics) | | GitHub | `<>` | S04 (audience of the mirror) | Synchronize Repository Metadata (target) | @@ -73,6 +78,7 @@ UC4 ..> UC1 : <> | Configure Workflow Credentials | DevOps Professional, Platform Operator | Least-privilege tokens that a workflow accepts | | Onboard a Repository | DevOps Professional | A repository consumes the shared workflows | | Diagnose a Failed Workflow | DevOps Professional, Platform Operator | The cause of a failed run is found and placed in a category | +| Run Project Quality Checks | Software Engineer | Lint, format and type checks run on every change and report a pass or a fail | ## Relationships @@ -91,3 +97,5 @@ UC4 ..> UC1 : <> [UC-003]: ./uc-003/uc.md [UC-004]: ./uc-004/uc.md [a2bf2d4]: https://git.tirsystem.com/TirSystem/github-action/commit/a2bf2d420416f7aff2badc6fe32a7690e2e523fd +[UC-005]: ./uc-005/uc.md +[385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7 diff --git a/docs/user-stories.md b/docs/user-stories.md index b74b3d4..134f328 100644 --- a/docs/user-stories.md +++ b/docs/user-stories.md @@ -4,12 +4,13 @@ | Key | Value | | --- | --- | | ID | US-001 | -| CrossReference | [UCD-001], [BC-001], [MIL-001], [MIL-002], [UC-001], [UC-002], [UC-003], [UC-004] | +| CrossReference | [UCD-001], [BC-001], [MIL-001], [MIL-002], [MIL-003], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005] | ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | [a2bf2d4] | +| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | [a2bf2d4] | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added US-001.09 and US-001.10 (quality checks, UC-005) | [385d2fb] | --- @@ -18,8 +19,7 @@ These stories cover the P1 use cases of the Project Plan that MIL-002 delivers (O1 to O3 of [BC-001]): keeping the mirror metadata correct, configuring credentials, onboarding a repository and diagnosing a failed run. Roles are the -actors of [UCD-001]. Stories for quality checks and releases (MIL-003, -MIL-004) and for the wiki (MIL-005, MIL-006) are not written yet. +actors of [UCD-001]. Stories for quality checks and releases (MIL-004) and for the wiki (MIL-005, MIL-006) are not written yet. ## Story List @@ -127,9 +127,35 @@ MIL-004) and for the wiki (MIL-005, MIL-006) are not written yet. | --- | --- | --- | | [UC-004], [MIL-002] | fits one iteration | none | +### US-001.09 — Same checks on every change + +**As a** Software Engineer, **I want** every pull request to run the same quality checks for the languages of my repository, **so that** a defect is found before review without me writing a pipeline. + +**Acceptance Criteria** + +- Given a repository that calls the shared workflow and has Python files, when a pull request is opened, then lint, format and type checks run and the status is pass or fail. +- Given a repository that has shell scripts, when a pull request is opened, then lint and format checks run for them and the status is pass or fail. + +| Traces to | Size | INVEST exceptions | +| --- | --- | --- | +| [UC-005], [MIL-003] | fits one iteration | none | + +### US-001.10 — A failure says what to fix + +**As a** Software Engineer, **I want** a failed check to show the tool, the file, the line and the message, **so that** I can fix it without reading the workflow. + +**Acceptance Criteria** + +- 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 language that has no files in the repository, when the check runs, then it passes and the log says that nothing was checked. + +| Traces to | Size | INVEST exceptions | +| --- | --- | --- | +| [UC-005], [MIL-003] | fits one iteration | none | + ## INVEST Check -All eight stories are independent of each other except that US-001.05 and +All ten 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 @@ -143,8 +169,11 @@ behaviour is tested rather than built. [BC-001]: ./business-case.md [MIL-001]: ./milestones/mil-001-stabilise-metadata-sync.md [MIL-002]: ./milestones/mil-002-onboarding-and-operations.md +[MIL-003]: ./milestones/mil-003-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 [a2bf2d4]: https://git.tirsystem.com/TirSystem/github-action/commit/a2bf2d420416f7aff2badc6fe32a7690e2e523fd +[UC-005]: ./uc-005/uc.md +[385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7