Tirsvad
385d2fb7cb
Add the brief use case UC-005 (Run Project Quality Checks), the actor and use case in UCD-001, stories US-001.09 and US-001.10, and ADR-0005 with the inputs, the pinned tools and what a pass and a fail mean, based on a probe of the runner image. Review and accept them (RC-035 to RC-038) and update TM-001 and the registry. Task: MIL-003#2
8.1 KiB
User Story
Metadata
| Key | Value |
|---|---|
| ID | US-001 |
| 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 | 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) | pending |
Purpose and Scope
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-004) and for the wiki (MIL-005, MIL-006) are not written yet.
Story List
US-001.01 — Mirror shows the Gitea metadata
As a DevOps Professional, I want the GitHub mirror to show the description and topics of the Gitea repository, so that visitors of the mirror see the same repository metadata as on the primary repository.
Acceptance Criteria
- Given a repository with one GitHub push mirror, when the workflow runs, then the GitHub description and topics equal the Gitea ones.
- Given the description or the topics changed on Gitea, when the next run completes, then the GitHub mirror shows the new values.
| Traces to | Size | INVEST exceptions |
|---|---|---|
| UC-001, MIL-002 | fits one iteration | none |
US-001.02 — Repository without a mirror is skipped
As a DevOps Professional, I want a repository without a GitHub mirror to be skipped successfully, so that repositories that have no mirror do not show failed runs.
Acceptance Criteria
- Given a repository with no GitHub push mirror, when the workflow runs, then the run succeeds and the log says that there is nothing to sync.
- Given a repository with several GitHub push mirrors, when the workflow runs, then the run fails with a configuration message and changes nothing.
| Traces to | Size | INVEST exceptions |
|---|---|---|
| UC-001, MIL-002 | fits one iteration | none |
US-001.03 — Check the tokens before changing anything
As a DevOps Professional, I want both tokens to be checked before the workflow changes anything, so that a wrong or too weak token is found without any side effect.
Acceptance Criteria
- Given a token that GitHub rejects, when the workflow runs, then nothing is changed and the log names the credentials category.
- Given a GitHub token without administration access, when the workflow runs, then it stops with a permissions message before the first change.
| Traces to | Size | INVEST exceptions |
|---|---|---|
| UC-002, MIL-002 | fits one iteration | none |
US-001.04 — Store the secrets once per organization
As a Platform Operator, I want to store a workflow's secrets once for an organization, so that every repository of the organization can use the workflow without its own copy of the secrets.
Acceptance Criteria
- Given the secrets are stored for an organization, when a repository of that organization runs the workflow, then it passes the credential check.
- Given a repository of another organization, when it runs the workflow, then it does not see these secrets and the log names the missing secret.
| Traces to | Size | INVEST exceptions |
|---|---|---|
| UC-002, MIL-002 | fits one iteration | none |
US-001.05 — Use the workflow without a copy
As a DevOps Professional, I want a repository to use the shared workflow without copying it, so that a fix made once reaches every repository.
Acceptance Criteria
- Given a repository without its own workflow files, when a push is made to
main, then the shared workflow runs in it. - Given the shared workflow changes, when the next run starts in another repository, then it runs the changed version.
| Traces to | Size | INVEST exceptions |
|---|---|---|
| UC-003, MIL-002 | fits one iteration | none |
US-001.06 — Onboard from one guide
As a DevOps Professional, I want to onboard a repository by following one guide, so that the first run passes without undocumented steps.
Acceptance Criteria
- Given a repository with Actions enabled and a runner, when its owner follows only the onboarding guide, then the first run succeeds.
- Given a step of the guide is wrong or missing, when it is found during onboarding, then it is raised as a defect of the guide.
| Traces to | Size | INVEST exceptions |
|---|---|---|
| UC-003, MIL-002 | fits one iteration | none |
US-001.07 — Every failure names its category
As a DevOps Professional, I want every failure message to name its category, so that I know at once whether to look at configuration, credentials, permissions, the service or the runner.
Acceptance Criteria
- Given any failure of the workflow, when its log is read, then the message starts with one of the categories configuration, credentials, permissions or api.
- Given a message that has no category, when it is found, then it is raised as a defect.
| Traces to | Size | INVEST exceptions |
|---|---|---|
| UC-004, MIL-002 | fits one iteration | none |
US-001.08 — Recognise a runner problem
As a Platform Operator, I want to recognise a runner problem from its symptom, so that I fix the runner and not the workflow.
Acceptance Criteria
- Given a run that stays waiting, when the troubleshooting guide is read, then it names the missing runner label as the cause.
- Given a job that fails before the script, when the guide is read, then it names the tool missing from the runner image.
| Traces to | Size | INVEST exceptions |
|---|---|---|
| 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:lineand 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 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 criteria that are checked with a run or a read of the guide. Exception: US-001.01 and US-001.02 are already implemented and are written so that their behaviour is tested rather than built.