Tirsvad
044d8ba21f
Add the brief use case UC-006 (Release a Reusable Workflow), the use case in UCD-001, stories US-001.11 to US-001.13 and ADR-0006: one version for the repository with SemVer tags and a moving major tag, a release only from a green commit with a changelog entry, consumers pin the major or an exact tag and never main. Add the maintainers' checklist guides/release-process.md. Review and accept them (RC-040 to RC-043), update TM-001 and the registry. Task: MIL-004#1
10 KiB
User Story
Metadata
| 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 |
Version History
| Date | Status | Author | Reviewer | Change | Commit |
|---|---|---|---|---|---|
| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added US-001.09 and US-001.10 (quality checks, UC-005) | 385d2fb |
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added US-001.11 to US-001.13 (releases, UC-006); US-001.13 traced to the epic (RC-041) | 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 (the consumer's update, 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 |
US-001.11 — Only validated commits are released
As a DevOps Professional, I want a release to be created only from a commit whose validation run is green, so that consumers never receive an unchecked version.
Acceptance Criteria
- Given a commit whose validation run failed, when a release is attempted, then no version tag is created.
- Given a green commit and a changelog entry for the version, when the release is created, then the version tag, the major tag and the release page exist.
| Traces to | Size | INVEST exceptions |
|---|---|---|
| UC-006, MIL-004 | fits one iteration | none |
US-001.12 — A release says whether it is breaking
As a DevOps Professional, I want every release to say whether it is breaking, so that consumers know whether they must act.
Acceptance Criteria
- Given a change that renames a workflow, an input or a secret, or can turn a passing consumer red, when it is released, then the changelog marks it as breaking and a new major version is created.
- Given a compatible change, when it is released, then the major tag moves to it and consumers pinned to that major version receive it.
| Traces to | Size | INVEST exceptions |
|---|---|---|
| UC-006, MIL-004 | fits one iteration | none |
US-001.13 — A pin that does not move
As a Software Engineer, I want to pin the shared workflows to a version that does not change under me, so that a release cannot break my pipeline by surprise.
Acceptance Criteria
- Given a repository that calls a shared workflow at an exact version tag, when a new release is made, then its runs use the same code as before.
- Given a repository that calls a shared workflow at a major tag, when a compatible release is made, then it receives the release and a breaking release is not delivered to it.
| Traces to | Size | INVEST exceptions |
|---|---|---|
| MIL-004 (epic; its use case, Consume a Workflow Update, is not written yet) | fits one iteration | none |
INVEST Check
All thirteen 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.