README.md

@@ -68,7 +68,7 @@ Rows that say Implemented or Guides written exist today. The rest is planned and
 | Onboard a repository, manage runners, diagnose failures | Guides written ([onboarding](guides/onboarding.md), [troubleshooting](guides/troubleshooting.md)); scoped delivery to other repositories not yet verified; brief use cases open (MIL-002) |
 | Publish a repository wiki from `wiki/` (opt-in, delivered to every organization) | Implemented in `.gitea/scoped_workflows/publish-wiki.yml`, with offline tests; the pilot in a second repository is pending (MIL-006) |
 | Shared quality checks (Python and shell) | Implemented as the reusable workflow `.gitea/workflows/quality-checks.yml`, with offline tests and a trial in a second organization; adoption in RepoFoundry is in review ([guide](guides/quality-checks.md)) |
-| Versioned release and publishing | Planned (MIL-004) |
+| Versioned release and publishing | Release process, changelog and upgrade guide defined; the first release `v1.0.0` and the release workflow are pending (MIL-004) ([guide](guides/upgrading.md)) |
 
 ### 🔄 Sync GitHub metadata
 

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 | 044 |
+| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 047 |
 | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
 | ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0007 |
 | 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 | 007 |
+| UC | Use Case | docs/uc-NNN/uc.md | 008 |
 
 ## Languages
 

docs/sqa/reviews/rc-044-uc-007.md

@@ -0,0 +1,51 @@
+# Review Record: UC-007
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-044 |
+| CrossReference | [UC-007], [QC-UC-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [UC-007]
+- 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 | The paragraph describes read, try in one repository, read the run, roll out; the rollback and the failures are in the stories and the guide. |
+| 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; the precondition names the release process of UC-006. |
+| 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 `<<include>>`/`<<extend>>` 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 (checked mechanically); stories are US-001.13 to US-001.15. |
+| 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. 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-007]: ../../uc-007/uc.md
+[QC-UC-001]: ../../../framework/qc/qc-use-case.md

docs/sqa/reviews/rc-045-ucd-001-consume.md

@@ -0,0 +1,47 @@
+# Review Record: UCD-001 (consume an update)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-045 |
+| CrossReference | [UCD-001], [QC-UCD-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending |
+
+---
+
+## 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. `<<System>>`, `<<Actor>>`) | Pass | Unchanged actors. |
+| 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 | The new use case has none; its dependency on UC-006 is a precondition. |
+| 4 | Every actor participates in at least one use case (no orphan actors) | Pass | Software Engineer now reaches two use cases. |
+| 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 | "Consume a Workflow Update". |
+| 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 | UC-007's title and the story roles match. |
+
+## Overall Verdict
+
+Go - all eight criteria pass for the amendment (the use case of UC-007). 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

docs/sqa/reviews/rc-046-us-001-consume.md

@@ -0,0 +1,46 @@
+# Review Record: US-001 (consume an update)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-046 |
+| CrossReference | [US-001], [QC-US-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending |
+
+---
+
+## 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 fifteen stories. |
+| 2 | Written in "As a / I want / So that" form | Pass | US-001.14 and US-001.15. |
+| 3 | Clear, testable acceptance criteria are included | Pass | Two Given/When/Then criteria each; both are checked by reading the changelog or a run. |
+| 4 | Traceable to a use case or epic | Pass | UC-007 and MIL-004; US-001.13 is now traced to UC-007 as well, closing the gap noted in RC-041. |
+| 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. 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

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], [RC-035], [RC-036], [RC-037], [RC-038], [RC-039], [RC-040], [RC-041], [RC-042], [RC-043], [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], [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], [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-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added RC-039 for MIL-003 | [3b8681d] |
+| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added UC-006, ADR-0006 and RC-040 to RC-043 | [044d8ba] |
-| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added UC-006, ADR-0006 and RC-040 to RC-043 | [044d8ba] |
+| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added UC-007 and RC-044 to RC-046 | pending |
 
 ---
 
@@ -55,8 +55,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] | [RC-019], [RC-035], [RC-040] |
+| [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] | [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006] | [RC-020], [RC-036], [RC-041] |
+| [US-001] | US | [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] | [RC-020], [RC-036], [RC-041], [RC-046] |
 | [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] |
@@ -65,6 +65,7 @@ updated whenever an artifact instance is created or reviewed.
 | [ADR-0005] | ADR | [MIL-003], [UC-005], [US-001], [ADR-0004] | - | [RC-038] |
 | [UC-006] | UC | [UCD-001], [US-001], [SA-001] | [ADR-0006] | [RC-042] |
 | [ADR-0006] | ADR | [MIL-004], [UC-006], [US-001], [ADR-0004], [ADR-0005] | - | [RC-043] |
+| [UC-007] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-044] |
 | [RC-019] | RC | [UCD-001] | - | - |
 | [RC-020] | RC | [US-001] | - | - |
 | [RC-021] | RC | [UC-001] | - | - |
@@ -90,6 +91,9 @@ updated whenever an artifact instance is created or reviewed.
 | [RC-041] | RC | [US-001] | - | - |
 | [RC-042] | RC | [UC-006] | - | - |
 | [RC-043] | RC | [ADR-0006] | - | - |
+| [RC-044] | RC | [UC-007] | - | - |
+| [RC-045] | RC | [UCD-001] | - | - |
+| [RC-046] | RC | [US-001] | - | - |
 
 ## Coverage Notes
 
@@ -162,9 +166,12 @@ updated whenever an artifact instance is created or reviewed.
 [RC-041]: ./reviews/rc-041-us-001-release.md
 [RC-042]: ./reviews/rc-042-uc-006.md
 [RC-043]: ./reviews/rc-043-adr-0006.md
+[RC-044]: ./reviews/rc-044-uc-007.md
+[RC-045]: ./reviews/rc-045-ucd-001-consume.md
+[RC-046]: ./reviews/rc-046-us-001-consume.md
+[UC-007]: ../uc-007/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
-[3b8681d]: https://git.tirsystem.com/TirSystem/github-action/commit/3b8681d0236c669b794ffbba725433fff600a2d2
 [044d8ba]: https://git.tirsystem.com/TirSystem/github-action/commit/044d8ba21f96f4aceb807d62addc35cdcbb56051

docs/uc-007/uc.md

@@ -0,0 +1,42 @@
+# UC-007: Consume a Workflow Update
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | UC-007 |
+| CrossReference | [UCD-001], [US-001], [SA-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending |
+
+---
+
+**Format:** Brief
+
+**Title:** Consume a Workflow Update
+**Scope:** Reusable Workflow Collection
+**Level:** user-goal
+**Primary Actor:** Software Engineer
+**Stakeholders:** S02, S05 (interests below)
+**Stories:** US-001.13, US-001.14, US-001.15
+
+## Brief
+
+When a new release of the shared workflows is announced, the Software Engineer reads its changelog entry to see whether it is breaking, changes the pinned version in one repository on a branch, opens a pull request and reads the run, and, when it is green, makes the same change in the other repositories.
+
+**Stakeholder interests**
+
+- S02 — an update is adopted deliberately, in one place first, and can be undone
+- S05 — consumers move to supported versions without a support request
+
+**Preconditions:** Releases are versioned with a changelog (the release process), and the repository calls the shared workflow at a version tag.
+
+**Postconditions (success guarantee):** The repository calls the new version, its pipeline still passes, and the previous version remains the way back.
+
+---
+
+[UCD-001]: ../use-case-diagram.md
+[US-001]: ../user-stories.md
+[SA-001]: ../stakeholder-analysis.md

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] |
+| CrossReference | [SA-001], [BC-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007] |
 
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
-| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added the actor Software Engineer and the use case Run Project Quality Checks | [385d2fb] |
+| 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 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) | pending |
 
 ---
 
@@ -45,6 +45,7 @@ rectangle "Reusable Workflow Collection" <<System>> {
   usecase "Diagnose a Failed Workflow" as UC4
   usecase "Run Project Quality Checks" as UC5
   usecase "Release a Reusable Workflow" as UC6
+  usecase "Consume a Workflow Update" as UC7
 }
 
 DevOps --> UC1
@@ -55,6 +56,7 @@ DevOps --> UC6
 Operator --> UC2
 Operator --> UC4
 Engineer --> UC5
+Engineer --> UC7
 UC1 --> Gitea
 UC1 --> GitHub
 UC3 ..> UC2 : <<include>>
@@ -68,7 +70,7 @@ UC4 ..> UC1 : <<extend>>
 | --- | --- | --- | --- |
 | DevOps Professional | `<<Actor>>` | S05 | Synchronize Repository Metadata, Configure Workflow Credentials, Onboard a Repository, Diagnose a Failed Workflow, Release a Reusable Workflow |
 | Platform Operator | `<<Actor>>` | S03 | Configure Workflow Credentials, Diagnose a Failed Workflow |
-| Software Engineer | `<<Actor>>` | S02 | Run Project Quality Checks |
+| Software Engineer | `<<Actor>>` | S02 | Run Project Quality Checks, Consume a Workflow Update |
 | Gitea Instance | `<<System>>` | - | Synchronize Repository Metadata (source of description and topics) |
 | GitHub | `<<System>>` | S04 (audience of the mirror) | Synchronize Repository Metadata (target) |
 
@@ -82,6 +84,7 @@ UC4 ..> UC1 : <<extend>>
 | 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 |
 | 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 |
 
 ## Relationships
 
@@ -100,6 +103,6 @@ UC4 ..> UC1 : <<extend>>
 [UC-003]: ./uc-003/uc.md
 [UC-004]: ./uc-004/uc.md
 [UC-005]: ./uc-005/uc.md
-[385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7
 [UC-006]: ./uc-006/uc.md
 [044d8ba]: https://git.tirsystem.com/TirSystem/github-action/commit/044d8ba21f96f4aceb807d62addc35cdcbb56051
+[UC-007]: ./uc-007/uc.md

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] |
+| 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] |
 
 ## 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 | 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.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) | pending |
 
 ---
 
@@ -19,7 +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 (the consumer's update, 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
 
@@ -190,11 +190,37 @@ actors of [UCD-001]. Stories for quality checks and releases (the consumer's upd
 
 | Traces to | Size | INVEST exceptions |
 | --- | --- | --- |
-| [MIL-004] (epic; its use case, Consume a Workflow Update, is not written yet) | fits one iteration | none |
+| [UC-007], [MIL-004] | fits one iteration | none |
+
+### US-001.14 — A changelog says whether to act
+
+**As a** Software Engineer, **I want** to see in a changelog entry whether a release is breaking, **so that** I know whether I must change my pipeline.
+
+**Acceptance Criteria**
+
+- Given a release page or a changelog entry, when it is read, then the groups Breaking, Added, Changed and Fixed are visible and a breaking change is the first group.
+- Given a breaking release, when the entry is read, then it names what changed and what to do.
+
+| Traces to | Size | INVEST exceptions |
+| --- | --- | --- |
+| [UC-007], [MIL-004] | fits one iteration | none |
+
+### US-001.15 — Try an update in one place and go back
+
+**As a** Software Engineer, **I want** to try a new version in one repository and return to the previous one, **so that** an update cannot harm all my pipelines at once.
+
+**Acceptance Criteria**
+
+- Given a branch that changes the pinned version in one repository, when its pull request runs, then the result of the new version is visible before any other repository changes.
+- Given a failing update, when the pin is set back to the previous exact tag, then the pipeline runs the previous code unchanged.
+
+| Traces to | Size | INVEST exceptions |
+| --- | --- | --- |
+| [UC-007], [MIL-004] | fits one iteration | none |
 
 ## INVEST Check
 
-All thirteen stories are independent of each other except that US-001.05 and
+All fifteen 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
@@ -215,6 +241,6 @@ behaviour is tested rather than built.
 [UC-003]: ./uc-003/uc.md
 [UC-004]: ./uc-004/uc.md
 [UC-005]: ./uc-005/uc.md
-[385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7
 [UC-006]: ./uc-006/uc.md
 [044d8ba]: https://git.tirsystem.com/TirSystem/github-action/commit/044d8ba21f96f4aceb807d62addc35cdcbb56051
+[UC-007]: ./uc-007/uc.md

guides/upgrading.md

@@ -0,0 +1,66 @@
+# Upgrading to a new version of the shared workflows
+
+How a software engineer adopts a new release of the shared workflows safely:
+read the changelog, try the update in one place, and go back if it fails. The
+version rules are those of the release process: one version for the whole
+repository, tags `vMAJOR.MINOR.PATCH` and a moving major tag `vMAJOR`.
+
+## Which version you follow
+
+| In your `uses:` line | You receive | When to use it |
+| --- | --- | --- |
+| `@v1.2.0` | nothing new, ever | a pipeline that must not change |
+| `@v1` | compatible releases only (minor and patch) | the default for a project |
+| `@main` | everything, unreleased | never; only for this repository's own tests |
+
+A breaking release gets a new major version (`v2`), so a pipeline on `@v1`
+never receives it until you change the line yourself.
+
+The two scoped workflows (**Sync GitHub mirror metadata** and **Publish
+wiki**) are delivered by the instance and are not in your `uses:` lines; you
+cannot pin them, but they fetch their scripts at the major tag.
+
+## Reading a changelog entry
+
+Open `CHANGELOG.md` of `TirSystem/github-action`, or the release page of the tag.
+An entry has up to four groups:
+
+| Group | What it means for you |
+| --- | --- |
+| Breaking | You must act: a name, an input, a secret or a default changed. A release with this group has a new major version |
+| Added | Nothing to do; a new optional input, workflow or capability |
+| Changed | Nothing to do; no visible effect for existing callers |
+| Fixed | Nothing to do; a fix you receive on `@v1` |
+
+An entry that changes credentials, tokens or permissions says so; check your
+secrets before you upgrade.
+
+## Trying an update
+
+1. Change the version in **one** repository, on a branch:
+   ```yaml
+   jobs:
+     quality:
+       uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v2
+   ```
+2. Open a pull request and read the run. A failing check shows the tool, the
+   file and the message (see the guide for reading quality-check results).
+3. For a breaking release, follow the upgrade notes of the changelog entry,
+   then repeat.
+4. When the pull request is green, make the same change in the other
+   repositories.
+
+## Going back
+
+1. Change the line back to the previous exact tag, for example `@v1.2.0`, and
+   merge it. Exact tags are never deleted or moved, so this always works.
+2. Tell the maintainers which release failed and what you saw, so that the
+   major tag can be moved back and a fix released.
+
+## When something is unclear
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| The run says the workflow cannot be found | The tag does not exist, or the path is wrong | Check the tag on the release page and the path `.gitea/workflows/quality-checks.yml` |
+| A green pipeline turned red after a release on `@v1` | A compatible release should not do this | Pin the previous exact tag and report it as a defect |
+| An input is no longer accepted | A breaking release renamed it | Read the Breaking group of the entry |

tests/test_build_wiki.py

@@ -96,7 +96,7 @@ def _write_sources(root: Path) -> None:
         "### 🔄 Sync\nDetails.\n\n## 📄 License\nMIT.\n",
         encoding="utf-8",
     )
-    for name in ("onboarding", "credentials", "troubleshooting", "quality-checks"):
+    for name in ("onboarding", "credentials", "troubleshooting", "quality-checks", "upgrading"):
         (root / "guides" / f"{name}.md").write_text(
             f"# {name.title()}\nBody.\n", encoding="utf-8"
         )

tools/build_wiki.py

@@ -44,6 +44,7 @@ PAGES: tuple[Page, ...] = (
     Page("Credentials", "guides/credentials.md"),
     Page("Troubleshooting", "guides/troubleshooting.md"),
     Page("QualityChecks", "guides/quality-checks.md"),
+    Page("Upgrading", "guides/upgrading.md"),
     Page("Capabilities", "README.md", ("Capabilities",)),
 )
 
@@ -61,6 +62,7 @@ _PAGE_FOR_SOURCE = {
     "guides/credentials.md": "Credentials",
     "guides/troubleshooting.md": "Troubleshooting",
     "guides/quality-checks.md": "QualityChecks",
+    "guides/upgrading.md": "Upgrading",
 }
 
 

wiki/Capabilities.da.md

@@ -1,4 +1,4 @@
-<!-- translation of Capabilities.md, source sha256 c55376110b0c -->
+<!-- translation of Capabilities.md, source sha256 c1d5b1f173ef -->
 
 > Dette er en oversættelse af [`Capabilities`](Capabilities). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
 
@@ -15,7 +15,7 @@ Rækker, der siger Implementeret eller Vejledninger er skrevet, findes i dag. Re
 | Tilslutning af et repository, administration af runners, fejlfinding | Vejledninger er skrevet ([tilslutning](Onboarding.da), [fejlfinding](Troubleshooting.da)); scoped levering til andre repositories er ikke verificeret endnu; korte use cases er åbne (MIL-002) |
 | Publicering af et repositorys wiki fra `wiki/` (tilmelding, leveres til alle organisationer) | Implementeret i `.gitea/scoped_workflows/publish-wiki.yml`, med offline-tests; pilotforsøget i et andet repository afventer (MIL-006) |
 | Fælles kvalitetskontrol (Python og shell) | Implementeret som det genbrugelige workflow `.gitea/workflows/quality-checks.yml`, med offline-tests og et forsøg i en anden organisation; tilslutningen i RepoFoundry er til gennemgang ([vejledning](QualityChecks.da)) |
-| Versioneret udgivelse og publicering | Planlagt (MIL-004) |
+| Versioneret udgivelse og publicering | Udgivelsesproces, changelog og opgraderingsvejledning er defineret; den første udgivelse `v1.0.0` og udgivelsesworkflowet mangler (MIL-004) ([vejledning](Upgrading.da)) |
 
 ### Synkronisering af GitHub-metadata
 

wiki/Capabilities.md

@@ -15,7 +15,7 @@ Rows that say Implemented or Guides written exist today. The rest is planned and
 | Onboard a repository, manage runners, diagnose failures | Guides written ([onboarding](Onboarding), [troubleshooting](Troubleshooting)); scoped delivery to other repositories not yet verified; brief use cases open (MIL-002) |
 | Publish a repository wiki from `wiki/` (opt-in, delivered to every organization) | Implemented in `.gitea/scoped_workflows/publish-wiki.yml`, with offline tests; the pilot in a second repository is pending (MIL-006) |
 | Shared quality checks (Python and shell) | Implemented as the reusable workflow `.gitea/workflows/quality-checks.yml`, with offline tests and a trial in a second organization; adoption in RepoFoundry is in review ([guide](QualityChecks)) |
-| Versioned release and publishing | Planned (MIL-004) |
+| Versioned release and publishing | Release process, changelog and upgrade guide defined; the first release `v1.0.0` and the release workflow are pending (MIL-004) ([guide](Upgrading)) |
 
 ### Sync GitHub metadata
 

wiki/Capabilities.ms.md

@@ -1,4 +1,4 @@
-<!-- translation of Capabilities.md, source sha256 c55376110b0c -->
+<!-- translation of Capabilities.md, source sha256 c1d5b1f173ef -->
 
 > Ini ialah terjemahan [`Capabilities`](Capabilities). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
 
@@ -15,7 +15,7 @@ Baris yang menyatakan Dilaksanakan atau Panduan telah ditulis wujud hari ini. Se
 | Menyertakan repositori, mengurus runner, mendiagnosis kegagalan | Panduan telah ditulis ([menyertakan repositori](Onboarding.ms), [diagnosis](Troubleshooting.ms)); penghantaran scoped ke repositori lain belum disahkan; use case ringkas masih terbuka (MIL-002) |
 | Menerbitkan wiki repositori daripada `wiki/` (pilih menyertai, dihantar ke setiap organisasi) | Dilaksanakan dalam `.gitea/scoped_workflows/publish-wiki.yml`, dengan ujian luar talian; juruterbang dalam repositori kedua belum dibuat (MIL-006) |
 | Semakan kualiti bersama (Python dan shell) | Dilaksanakan sebagai aliran kerja boleh guna semula `.gitea/workflows/quality-checks.yml`, dengan ujian luar talian dan percubaan dalam organisasi kedua; penerimaan dalam RepoFoundry sedang disemak ([panduan](QualityChecks.ms)) |
-| Keluaran dan penerbitan berversi | Dirancang (MIL-004) |
+| Keluaran berversi dan penerbitan | Proses keluaran, changelog dan panduan naik taraf telah ditakrifkan; keluaran pertama `v1.0.0` dan aliran kerja keluaran belum ada (MIL-004) ([panduan](Upgrading.ms)) |
 
 ### Menyegerakkan metadata GitHub
 

wiki/Upgrading.da.md

@@ -0,0 +1,59 @@
+<!-- translation of Upgrading.md, source sha256 ff8a06c4a03f -->
+
+> Dette er en oversættelse af [`Upgrading`](Upgrading). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
+
+[English](Upgrading) | Dansk | [Bahasa Melayu](Upgrading.ms)
+
+# Opgradering til en ny version af de fælles workflows
+
+Sådan tager en softwareudvikler en ny udgivelse af de fælles workflows i brug uden risiko: læs changelog, prøv opdateringen ét sted, og gå tilbage, hvis den fejler. Versionsreglerne er udgivelsesprocessens: én version for hele repositoryet, tags `vMAJOR.MINOR.PATCH` og et flytbart major-tag `vMAJOR`.
+
+## Hvilken version du følger
+
+| I din `uses:`-linje | Du modtager | Brug den, når |
+| --- | --- | --- |
+| `@v1.2.0` | aldrig noget nyt | en pipeline ikke må ændre sig |
+| `@v1` | kun kompatible udgivelser (minor og patch) | standardvalget for et projekt |
+| `@main` | alt, også uudgivet | aldrig; kun til dette repositorys egne tests |
+
+En udgivelse, der bryder kompatibiliteten, får en ny major-version (`v2`), så en pipeline på `@v1` aldrig modtager den, før du selv ændrer linjen.
+
+De to scoped workflows (**Sync GitHub mirror metadata** og **Publish wiki**) leveres af instansen og står ikke i dine `uses:`-linjer; du kan ikke fastlåse dem, men de henter deres scripts ved major-tagget.
+
+## Aflæsning af en changelog-post
+
+Åbn `CHANGELOG.md` i `TirSystem/github-action` eller tagget udgivelsesside. En post har op til fire grupper:
+
+| Gruppe | Hvad den betyder for dig |
+| --- | --- |
+| Breaking | Du skal handle: et navn, et input, en secret eller en standardværdi er ændret. En udgivelse med denne gruppe har en ny major-version |
+| Added | Intet at gøre; et nyt valgfrit input, workflow eller en ny funktion |
+| Changed | Intet at gøre; ingen synlig virkning for eksisterende kaldere |
+| Fixed | Intet at gøre; en rettelse, du modtager på `@v1` |
+
+En post, der ændrer credentials, tokens eller tilladelser, siger det; kontroller dine secrets, før du opgraderer.
+
+## Afprøvning af en opdatering
+
+1. Ændr versionen i **ét** repository på en gren:
+   ```yaml
+   jobs:
+     quality:
+       uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v2
+   ```
+2. Åbn en pull request, og læs kørslen. En mislykket kontrol viser værktøj, fil og meddelelse (se vejledningen til aflæsning af kvalitetskontrollens resultater).
+3. For en udgivelse, der bryder kompatibiliteten, følges opgraderingsnoterne i changelog-posten, og trinnet gentages.
+4. Når pull requesten er grøn, foretages den samme ændring i de øvrige repositories.
+
+## Tilbage igen
+
+1. Ret linjen tilbage til det forrige præcise tag, fx `@v1.2.0`, og flet. Præcise tags slettes eller flyttes aldrig, så det virker altid.
+2. Fortæl vedligeholderne, hvilken udgivelse der fejlede, og hvad du så, så major-tagget kan flyttes tilbage og en rettelse udgives.
+
+## Når noget er uklart
+
+| Symptom | Sandsynlig årsag | Rettelse |
+| --- | --- | --- |
+| Kørslen siger, at workflowet ikke kan findes | Tagget findes ikke, eller stien er forkert | Kontroller tagget på udgivelsessiden og stien `.gitea/workflows/quality-checks.yml` |
+| En grøn pipeline blev rød efter en udgivelse på `@v1` | En kompatibel udgivelse burde ikke gøre det | Fastlås det forrige præcise tag, og meld det som en defekt |
+| Et input accepteres ikke længere | En udgivelse, der bryder kompatibiliteten, har omdøbt det | Læs gruppen Breaking i posten |

wiki/Upgrading.md

@@ -0,0 +1,72 @@
+<!-- Generated from guides/upgrading.md by tools/build_wiki.py. Edit the source, not this page. -->
+
+> This page is generated from [`guides/upgrading.md`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/upgrading.md). Changes made here are overwritten the next time the wiki is published.
+
+English | [Dansk](Upgrading.da) | [Bahasa Melayu](Upgrading.ms)
+
+# Upgrading to a new version of the shared workflows
+
+How a software engineer adopts a new release of the shared workflows safely:
+read the changelog, try the update in one place, and go back if it fails. The
+version rules are those of the release process: one version for the whole
+repository, tags `vMAJOR.MINOR.PATCH` and a moving major tag `vMAJOR`.
+
+## Which version you follow
+
+| In your `uses:` line | You receive | When to use it |
+| --- | --- | --- |
+| `@v1.2.0` | nothing new, ever | a pipeline that must not change |
+| `@v1` | compatible releases only (minor and patch) | the default for a project |
+| `@main` | everything, unreleased | never; only for this repository's own tests |
+
+A breaking release gets a new major version (`v2`), so a pipeline on `@v1`
+never receives it until you change the line yourself.
+
+The two scoped workflows (**Sync GitHub mirror metadata** and **Publish
+wiki**) are delivered by the instance and are not in your `uses:` lines; you
+cannot pin them, but they fetch their scripts at the major tag.
+
+## Reading a changelog entry
+
+Open `CHANGELOG.md` of `TirSystem/github-action`, or the release page of the tag.
+An entry has up to four groups:
+
+| Group | What it means for you |
+| --- | --- |
+| Breaking | You must act: a name, an input, a secret or a default changed. A release with this group has a new major version |
+| Added | Nothing to do; a new optional input, workflow or capability |
+| Changed | Nothing to do; no visible effect for existing callers |
+| Fixed | Nothing to do; a fix you receive on `@v1` |
+
+An entry that changes credentials, tokens or permissions says so; check your
+secrets before you upgrade.
+
+## Trying an update
+
+1. Change the version in **one** repository, on a branch:
+   ```yaml
+   jobs:
+     quality:
+       uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v2
+   ```
+2. Open a pull request and read the run. A failing check shows the tool, the
+   file and the message (see the guide for reading quality-check results).
+3. For a breaking release, follow the upgrade notes of the changelog entry,
+   then repeat.
+4. When the pull request is green, make the same change in the other
+   repositories.
+
+## Going back
+
+1. Change the line back to the previous exact tag, for example `@v1.2.0`, and
+   merge it. Exact tags are never deleted or moved, so this always works.
+2. Tell the maintainers which release failed and what you saw, so that the
+   major tag can be moved back and a fix released.
+
+## When something is unclear
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| The run says the workflow cannot be found | The tag does not exist, or the path is wrong | Check the tag on the release page and the path `.gitea/workflows/quality-checks.yml` |
+| A green pipeline turned red after a release on `@v1` | A compatible release should not do this | Pin the previous exact tag and report it as a defect |
+| An input is no longer accepted | A breaking release renamed it | Read the Breaking group of the entry |

wiki/Upgrading.ms.md

@@ -0,0 +1,59 @@
+<!-- translation of Upgrading.md, source sha256 ff8a06c4a03f -->
+
+> Ini ialah terjemahan [`Upgrading`](Upgrading). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
+
+[English](Upgrading) | [Dansk](Upgrading.da) | Bahasa Melayu
+
+# Menaik taraf kepada versi baharu aliran kerja bersama
+
+Cara seorang jurutera perisian menerima keluaran baharu aliran kerja bersama dengan selamat: baca changelog, cuba kemas kini di satu tempat, dan berpatah balik jika gagal. Peraturan versi ialah peraturan proses keluaran: satu versi untuk seluruh repositori, tag `vMAJOR.MINOR.PATCH` dan tag major yang boleh digerakkan `vMAJOR`.
+
+## Versi yang anda ikuti
+
+| Dalam baris `uses:` anda | Anda menerima | Gunakan apabila |
+| --- | --- | --- |
+| `@v1.2.0` | tiada apa-apa yang baharu, selama-lamanya | saluran paip tidak boleh berubah |
+| `@v1` | keluaran serasi sahaja (minor dan patch) | pilihan lalai untuk sesebuah projek |
+| `@main` | semuanya, termasuk yang belum dikeluarkan | jangan sekali-kali; hanya untuk ujian repositori ini sendiri |
+
+Keluaran yang memecahkan keserasian mendapat versi major baharu (`v2`), jadi saluran paip pada `@v1` tidak menerimanya sehingga anda sendiri menukar baris itu.
+
+Dua aliran kerja scoped (**Sync GitHub mirror metadata** dan **Publish wiki**) dihantar oleh instans dan tidak terdapat dalam baris `uses:` anda; anda tidak boleh menyematkannya, tetapi ia mengambil skripnya pada tag major.
+
+## Membaca satu catatan changelog
+
+Buka `CHANGELOG.md` bagi `TirSystem/github-action`, atau halaman keluaran tag itu. Satu catatan mempunyai sehingga empat kumpulan:
+
+| Kumpulan | Maksudnya untuk anda |
+| --- | --- |
+| Breaking | Anda mesti bertindak: nama, input, secret atau nilai lalai telah berubah. Keluaran dengan kumpulan ini mempunyai versi major baharu |
+| Added | Tiada apa-apa untuk dibuat; input pilihan, aliran kerja atau keupayaan baharu |
+| Changed | Tiada apa-apa untuk dibuat; tiada kesan yang kelihatan bagi pemanggil sedia ada |
+| Fixed | Tiada apa-apa untuk dibuat; pembetulan yang anda terima pada `@v1` |
+
+Catatan yang mengubah kelayakan (credentials), token atau kebenaran menyatakannya; semak secret anda sebelum menaik taraf.
+
+## Mencuba satu kemas kini
+
+1. Tukar versi dalam **satu** repositori, pada satu cabang:
+   ```yaml
+   jobs:
+     quality:
+       uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v2
+   ```
+2. Buka pull request dan baca larian. Semakan yang gagal menunjukkan alat, fail dan mesej (lihat panduan membaca keputusan semakan kualiti).
+3. Bagi keluaran yang memecahkan keserasian, ikut nota naik taraf dalam catatan changelog, kemudian ulang.
+4. Apabila pull request hijau, buat perubahan yang sama dalam repositori lain.
+
+## Berpatah balik
+
+1. Tukar baris itu kembali kepada tag tepat yang terdahulu, contohnya `@v1.2.0`, dan gabungkan. Tag tepat tidak pernah dipadam atau digerakkan, jadi ini sentiasa berfungsi.
+2. Beritahu penyelenggara keluaran mana yang gagal dan apa yang anda lihat, supaya tag major boleh digerakkan balik dan pembetulan dikeluarkan.
+
+## Apabila ada yang tidak jelas
+
+| Gejala | Punca yang mungkin | Pembetulan |
+| --- | --- | --- |
+| Larian menyatakan aliran kerja tidak ditemui | Tag tidak wujud, atau laluan salah | Semak tag pada halaman keluaran dan laluan `.gitea/workflows/quality-checks.yml` |
+| Saluran paip hijau menjadi merah selepas keluaran pada `@v1` | Keluaran serasi tidak sepatutnya berbuat demikian | Sematkan tag tepat yang terdahulu dan laporkan sebagai kecacatan |
+| Satu input tidak lagi diterima | Keluaran yang memecahkan keserasian menamakannya semula | Baca kumpulan Breaking dalam catatan itu |