TirSystem/github-action
0
1
Fork 0
Code Issues 5 Pull Requests 1 Actions Packages Projects Releases 3 Wiki Activity

Define the release process and version pinning

Browse Source 
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
This commit is contained in:
Tirsvad
2026-10-10 22:46:23 +08:00
parent aa18811003
commit 044d8ba21f
11 changed files with 513 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/adr/adr-0006-release-process-and-version-pinning.md
+136
View File
@@ -0,0 +1,136 @@
# ADR-0006: Release process and version pinning
## Metadata
| Key | Value |
| --- | --- |
| ID | ADR-0006 |
| CrossReference | [MIL-004], [UC-006], [US-001], [ADR-0004], [ADR-0005] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | pending |
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Reviewed (RC-043): SemVer expanded at first use | pending |
Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
---
## Context
Every consumer of the shared workflows runs this repository's code, and today
that code is whatever `main` holds: the scoped workflows (sync and publish
wiki) are delivered from `main` and fetch their scripts at `ref: main`, and
the reusable quality-check workflow is called as `@main` in the guide. A merge
to `main` therefore changes the pipelines of repositories in four
organizations at their next run, with no version, no changelog and no way to
stay on the previous behaviour. MIL-004 gives releases a version.
Facts that shape the decision:
- A reusable workflow is referenced with `@<ref>` where the ref may be a
branch or a tag (verified on 2026-10-10), and a tag is not deleted when a
pull request is merged, unlike the branch the first trial used.
- A **scoped** workflow is delivered by the instance from `main` of this
repository; a consumer cannot pin it. Only what the workflow fetches (the
script files) and what a consumer calls explicitly (the reusable workflow)
can be pinned.
- The repository has a validation run (YAML parse, offline tests, wiki
freshness) that is green or red per commit, and no release process, no
changelog and no tags yet.
Options for the unit and the scheme of a version:
1. **One version for the whole repository** with a semantic version (SemVer) tag `vMAJOR.MINOR.PATCH`
and a moving major tag `vMAJOR`. One changelog, one release page.
2. **One version per workflow** (`quality-checks/v1.2.0`). Precise, but five
moving parts for one maintainer, and the scripts and guides span several
workflows.
3. **Date-based tags** (`2026.10.10`). Simple, but they say nothing about
whether a change is breaking.
4. **No versions; consumers copy the files.** The situation MIL-002 moved away
from.
Options for how a consumer pins:
a. **Exact tag** (`@v1.2.0`): never changes, never receives fixes.
b. **Moving major tag** (`@v1`): receives compatible releases only.
c. **`@main`**: always the newest, unreviewed by the consumer.
## Decision
The repository is released as a whole with a SemVer tag `vMAJOR.MINOR.PATCH`
and a moving major tag `vMAJOR` that always points to the latest compatible
release, and consumers pin `@vMAJOR` or an exact tag and never `@main`. A
release is created from `main` only when the validation run of that exact
commit is green and `CHANGELOG.md` has an entry for the version that marks
each breaking change, and it is announced by a release page generated from
that entry.
The rules that follow from it:
- **Breaking (new major):** renaming or removing a workflow, an input, a
secret name or an output; raising a default tool version or changing a
default so that a previously green consumer can turn red; changing the
meaning of a pass or a fail (ADR-0005).
- **Minor:** a new optional input, a new workflow or a new capability that
changes nothing for existing callers. **Patch:** a fix, or a change of
documentation or tests, with no visible change for consumers.
- **First release:** `v1.0.0`, with `v1` pointing to it.
- **Tags are not deleted or moved,** except that the major tag moves forward
with each compatible release and may be moved back to the previous exact
tag when a release proves faulty.
- **Who:** the DevOps Professional (S05) cuts the release and S01 approves it;
a release that touches credentials, tokens or permissions says so in the
changelog.
- **Scripts:** once `v1` exists the scoped workflows fetch their scripts at
`ref: v1` instead of `main`, so that a merge to `main` stops reaching
consumers until it is released.
- **Not automated yet:** the steps are a checklist in
`guides/release-process.md`; the release workflow is task 5 of MIL-004.
## Consequences
**Positive:**
- A consumer chooses between "never changes" (`@v1.2.0`) and "compatible
fixes only" (`@v1`), and a breaking change cannot reach a pipeline that
pins a major version.
- A merge to `main` no longer reaches consumers of the scripts and the
reusable workflow until it is released, so a faulty merge costs a revert,
not an incident in four organizations.
- The changelog gives S02 and S03 one place to see what changed and whether
credentials or permissions are involved.
**Negative:**
- **A scoped workflow file is still delivered from `main`:** a consumer cannot
pin it, so a bad merge of `sync-github-metadata.yml` or `publish-wiki.yml`
still reaches every repository at its next run. Review of `main` is the only
protection for those two files, and the release process cannot change that.
- Moving the major tag needs permission to force-update a tag, which is a
second sensitive permission next to merging.
- One version for the whole repository means a fix to one workflow produces a
release for all, and a consumer of one workflow sees changelog entries that
concern another.
- Raising a default tool version is treated as breaking, so keeping the
quality checks current costs a major version each time.
## Affected Artifacts
- [MIL-004] — tasks 2 to 5 (issues #21 to #24) implement the changelog and tag
convention, the upgrade guide, the publish destination and the release
workflow on this decision.
- [UC-006] — the use case this process serves.
- [US-001] — stories US-001.11 to US-001.13 state its acceptance criteria.
- [ADR-0005] — its pinned tool versions become defaults that a release moves.
- [ADR-0004] — the scoped publish-wiki workflow is covered by the limitation
above.
---
[MIL-004]: ../milestones/mil-004-versioned-release.md
[UC-006]: ../uc-006/uc.md
[US-001]: ../user-stories.md
[ADR-0004]: ./adr-0004-shared-wiki-publishing-opt-in.md
[ADR-0005]: ./adr-0005-quality-check-contract.md
docs/artifact-registry.md
+3 -3
View File
@@ -11,12 +11,12 @@ each document lives in *this* project and the next version to use.
| SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 | | SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 |
| PP | Project Plan | docs/project-plan.md | 002 | | PP | Project Plan | docs/project-plan.md | 002 |
| MIL | Milestone / Gateway | docs/milestones/*.md | 007 | | MIL | Milestone / Gateway | docs/milestones/*.md | 007 |
| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 040 | | RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 044 |
| TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0006 | | ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0007 |
| UCD | Use Case Diagram | docs/use-case-diagram.md | 002 | | UCD | Use Case Diagram | docs/use-case-diagram.md | 002 |
| US | User Story | docs/user-stories.md | 002 | | US | User Story | docs/user-stories.md | 002 |
| UC | Use Case | docs/uc-NNN/uc.md | 006 | | UC | Use Case | docs/uc-NNN/uc.md | 007 |
## Languages ## Languages
docs/sqa/reviews/rc-040-ucd-001-release.md
+47
View File
@@ -0,0 +1,47 @@
# Review Record: UCD-001 (release process)
## Metadata
| Key | Value |
| --- | --- |
| ID | RC-040 |
| 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. |
| 4 | Every actor participates in at least one use case (no orphan actors) | Pass | DevOps Professional reaches Release a Reusable Workflow. |
| 5 | Diagram is traceable to a documented stakeholder need | Pass | S05 in the Actor Table. |
| 6 | Use case names are verb phrases describing actor goals, not internal system operations | Pass | "Release a Reusable Workflow". |
| 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-006's title and the story roles match. |
## Overall Verdict
Go - all eight criteria pass for the amendment (the use case of UC-006). 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-041-us-001-release.md
+46
View File
@@ -0,0 +1,46 @@
# Review Record: US-001 (release process)
## Metadata
| Key | Value |
| --- | --- |
| ID | RC-041 |
| 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 thirteen stories. |
| 2 | Written in "As a / I want / So that" form | Pass | US-001.11 to US-001.13. |
| 3 | Clear, testable acceptance criteria are included | Pass | Two Given/When/Then criteria each, matching ADR-0006. |
| 4 | Traceable to a use case or epic | Pass | Finding fixed during this review: US-001.13 is a consumer's goal (pin a version) but traced to UC-006, whose actor is the DevOps Professional. It now traces to the epic MIL-004 and names its use case, Consume a Workflow Update, as not yet written; UC-006 lists only US-001.11 and US-001.12. |
| 5 | Story is sized to fit within a single iteration | Pass | One goal each. |
| 6 | Story statement avoids technical implementation detail | Pass | Tags are named only in the criteria, as the observable result. |
| 7 | Role named in the story matches an actor defined in the Use Case Diagram | Pass | DevOps Professional and Software Engineer are in UCD-001. |
## Overall Verdict
Go - all seven criteria pass; the one finding (criterion 4) 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 | - | - |
---
[US-001]: ../../user-stories.md
[QC-US-001]: ../../../framework/qc/qc-user-story.md
docs/sqa/reviews/rc-042-uc-006.md
+51
View File
@@ -0,0 +1,51 @@
# Review Record: UC-006
## Metadata
| Key | Value |
| --- | --- |
| ID | RC-042 |
| CrossReference | [UC-006], [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-006]
- 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 the main flow: validation, changelog, tags, release page. The failure and undo paths are in the process guide and the stories. |
| 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 | DevOps Professional. |
| 6 | Stakeholders and their interests are stated | Pass | S05, S02 and S03. |
| 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; its stories are US-001.11 and US-001.12. |
| 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; tags and the changelog are domain terms. |
## 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-006]: ../../uc-006/uc.md
[QC-UC-001]: ../../../framework/qc/qc-use-case.md
docs/sqa/reviews/rc-043-adr-0006.md
+51
View File
@@ -0,0 +1,51 @@
# Review Record: ADR-0006
## Metadata
| Key | Value |
| --- | --- |
| ID | RC-043 |
| CrossReference | [ADR-0006], [QC-ADR-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: [ADR-0006]
- 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-0006 in `adr-0006-release-process-and-version-pinning.md`. |
| 2 | Context states the problem, the forces (cost, risk, constraints) and the options evaluated | Pass | Names that every consumer runs `main`, what can and cannot be pinned, and the options. |
| 3 | At least two options were considered, or the absence of alternatives is justified | Pass | Four options for the version unit and three for the pin. |
| 4 | Decision is stated in one or two unhedged sentences and matches one of the evaluated options | Pass | Two sentences; options 1 and b. |
| 5 | Consequences list both Positive and Negative outcomes | Pass | Three positive and four negative. |
| 6 | Quality-attribute impacts (performance, security, portability, etc.) are named where the decision affects them | Pass | Reliability for consumers and the security of tag permissions and of a bad merge of a scoped file are named. |
| 7 | Affected Artifacts are listed as links, and each is also in CrossReference | Pass | MIL-004, UC-006, US-001, ADR-0005 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 | Finding fixed during this review: SemVer was used without being expanded; it is now introduced as semantic version (SemVer). |
| 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 10) was fixed during the review. It unlocks tasks 2 to 5 of MIL-004 (#21 to #24) 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 |
| --- | --- | --- |
| Pin the scripts fetched by the two scoped workflows to `v1` once it exists (the workflows still say `ref: main`) | S05 | 2026-11-28 |
| Review who may merge to `main` and who may move tags, since a scoped workflow file cannot be pinned by consumers | S01 | 2026-11-14 |
---
[ADR-0006]: ../../adr/adr-0006-release-process-and-version-pinning.md
[QC-ADR-001]: ../../../framework/qc/qc-adr.md
docs/sqa/traceability-matrix.md
+17 -6
View File
@@ -4,13 +4,13 @@
| Key | Value | | Key | Value |
| --- | --- | | --- | --- |
| ID | TM-001 | | 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], [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], [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 ## Version History
| Date | Status | Author | Reviewer | Change | Commit | | Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- | --- |
| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added UC-005, ADR-0005 and RC-035 to RC-038 | [385d2fb] | | 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added RC-039 for MIL-003 | [3b8681d] |
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added RC-039 for MIL-003 | [3b8681d] | | 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added UC-006, ADR-0006 and RC-040 to RC-043 | pending |
--- ---
@@ -55,14 +55,16 @@ updated whenever an artifact instance is created or reviewed.
| [RC-016] | RC | [MIL-006] | - | - | | [RC-016] | RC | [MIL-006] | - | - |
| [RC-017] | RC | [PP-001] | - | - | | [RC-017] | RC | [PP-001] | - | - |
| [RC-018] | RC | [ADR-0004] | - | - | | [RC-018] | RC | [ADR-0004] | - | - |
| [UCD-001] | UCD | [SA-001], [BC-001] | [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005] | [RC-019], [RC-035] | | [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] |
| [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] | | [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] |
| [UC-001] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-021] | | [UC-001] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-021] |
| [UC-002] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-022] | | [UC-002] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-022] |
| [UC-003] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-023] | | [UC-003] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-023] |
| [UC-004] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-024] | | [UC-004] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-024] |
| [UC-005] | UC | [UCD-001], [US-001], [SA-001] | [ADR-0005] | [RC-037] | | [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] | | [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] |
| [RC-019] | RC | [UCD-001] | - | - | | [RC-019] | RC | [UCD-001] | - | - |
| [RC-020] | RC | [US-001] | - | - | | [RC-020] | RC | [US-001] | - | - |
| [RC-021] | RC | [UC-001] | - | - | | [RC-021] | RC | [UC-001] | - | - |
@@ -84,6 +86,10 @@ updated whenever an artifact instance is created or reviewed.
| [RC-037] | RC | [UC-005] | - | - | | [RC-037] | RC | [UC-005] | - | - |
| [RC-038] | RC | [ADR-0005] | - | - | | [RC-038] | RC | [ADR-0005] | - | - |
| [RC-039] | RC | [MIL-003] | - | - | | [RC-039] | RC | [MIL-003] | - | - |
| [RC-040] | RC | [UCD-001] | - | - |
| [RC-041] | RC | [US-001] | - | - |
| [RC-042] | RC | [UC-006] | - | - |
| [RC-043] | RC | [ADR-0006] | - | - |
## Coverage Notes ## Coverage Notes
@@ -152,7 +158,12 @@ updated whenever an artifact instance is created or reviewed.
[RC-037]: ./reviews/rc-037-uc-005.md [RC-037]: ./reviews/rc-037-uc-005.md
[RC-038]: ./reviews/rc-038-adr-0005.md [RC-038]: ./reviews/rc-038-adr-0005.md
[RC-039]: ./reviews/rc-039-mil-003-adoption.md [RC-039]: ./reviews/rc-039-mil-003-adoption.md
[RC-040]: ./reviews/rc-040-ucd-001-release.md
[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
[UC-006]: ../uc-006/uc.md
[ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.md
[UC-005]: ../uc-005/uc.md [UC-005]: ../uc-005/uc.md
[ADR-0005]: ../adr/adr-0005-quality-check-contract.md [ADR-0005]: ../adr/adr-0005-quality-check-contract.md
[385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7
[3b8681d]: https://git.tirsystem.com/TirSystem/github-action/commit/3b8681d0236c669b794ffbba725433fff600a2d2 [3b8681d]: https://git.tirsystem.com/TirSystem/github-action/commit/3b8681d0236c669b794ffbba725433fff600a2d2
docs/uc-006/uc.md
+44
View File
@@ -0,0 +1,44 @@
# UC-006: Release a Reusable Workflow
## Metadata
| Key | Value |
| --- | --- |
| ID | UC-006 |
| CrossReference | [UCD-001], [US-001], [SA-001], [ADR-0006] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending |
---
**Format:** Brief
**Title:** Release a Reusable Workflow
**Scope:** Reusable Workflow Collection
**Level:** user-goal
**Primary Actor:** DevOps Professional
**Stakeholders:** S05, S02, S03 (interests below)
**Stories:** US-001.11, US-001.12
## Brief
When a change to the workflows or their scripts is ready on the default branch, the DevOps Professional checks that the repository's validation run on that commit is green, adds the version to the changelog with each breaking change marked, and creates the version tag and moves the major tag of the same major version. The release page for the tag is created from the changelog entry and announces what changed and whether consumers need to act. Consumers pinned to the previous version are not affected.
**Stakeholder interests**
- S05 — a release is a deliberate, validated, reviewed step, and a faulty one can be undone
- S02 — a pinned pipeline never changes under them, and a changelog tells them whether to act
- S03 — a change to credentials, tokens or permissions is visible in the changelog before it reaches runners
**Preconditions:** The repository's validation run exists and is green on the commit to be released, and the version scheme of ADR-0006 is defined.
**Postconditions (success guarantee):** A version tag and a changelog entry exist for the commit, the major tag points to the latest compatible release, the release page announces it, and pipelines pinned to earlier versions run unchanged.
---
[UCD-001]: ../use-case-diagram.md
[US-001]: ../user-stories.md
[SA-001]: ../stakeholder-analysis.md
[ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.md
docs/use-case-diagram.md
+8 -5
View File
@@ -4,13 +4,13 @@
| Key | Value | | Key | Value |
| --- | --- | | --- | --- |
| ID | UCD-001 | | ID | UCD-001 |
| CrossReference | [SA-001], [BC-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005] | | CrossReference | [SA-001], [BC-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006] |
## Version History ## Version History
| Date | Status | Author | Reviewer | Change | Commit | | Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- | --- |
| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | [a2bf2d4] | | 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 | Accepted | Jens Tirsvad Nielsen | S01 | Added the actor Software Engineer and the use case Run Project Quality Checks | [385d2fb] | | 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added the use case Release a Reusable Workflow (UC-006) | pending |
--- ---
@@ -44,12 +44,14 @@ rectangle "Reusable Workflow Collection" <<System>> {
usecase "Onboard a Repository" as UC3 usecase "Onboard a Repository" as UC3
usecase "Diagnose a Failed Workflow" as UC4 usecase "Diagnose a Failed Workflow" as UC4
usecase "Run Project Quality Checks" as UC5 usecase "Run Project Quality Checks" as UC5
usecase "Release a Reusable Workflow" as UC6
} }
DevOps --> UC1 DevOps --> UC1
DevOps --> UC2 DevOps --> UC2
DevOps --> UC3 DevOps --> UC3
DevOps --> UC4 DevOps --> UC4
DevOps --> UC6
Operator --> UC2 Operator --> UC2
Operator --> UC4 Operator --> UC4
Engineer --> UC5 Engineer --> UC5
@@ -64,7 +66,7 @@ UC4 ..> UC1 : <<extend>>
| Actor | Stereotype | Stakeholder ID (SA) | Goals (use cases) | | Actor | Stereotype | Stakeholder ID (SA) | Goals (use cases) |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| DevOps Professional | `<<Actor>>` | S05 | Synchronize Repository Metadata, Configure Workflow Credentials, Onboard a Repository, Diagnose a Failed Workflow | | 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 | | 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 |
| Gitea Instance | `<<System>>` | - | Synchronize Repository Metadata (source of description and topics) | | Gitea Instance | `<<System>>` | - | Synchronize Repository Metadata (source of description and topics) |
@@ -79,6 +81,7 @@ UC4 ..> UC1 : <<extend>>
| Onboard a Repository | DevOps Professional | A repository consumes the shared workflows | | 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 | | 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 | | 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 |
## Relationships ## Relationships
@@ -96,6 +99,6 @@ UC4 ..> UC1 : <<extend>>
[UC-002]: ./uc-002/uc.md [UC-002]: ./uc-002/uc.md
[UC-003]: ./uc-003/uc.md [UC-003]: ./uc-003/uc.md
[UC-004]: ./uc-004/uc.md [UC-004]: ./uc-004/uc.md
[a2bf2d4]: https://git.tirsystem.com/TirSystem/github-action/commit/a2bf2d420416f7aff2badc6fe32a7690e2e523fd
[UC-005]: ./uc-005/uc.md [UC-005]: ./uc-005/uc.md
[385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7 [385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7
[UC-006]: ./uc-006/uc.md
docs/user-stories.md
+46 -6
View File
@@ -4,13 +4,13 @@
| Key | Value | | Key | Value |
| --- | --- | | --- | --- |
| ID | US-001 | | ID | US-001 |
| CrossReference | [UCD-001], [BC-001], [MIL-001], [MIL-002], [MIL-003], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005] | | 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 ## Version History
| Date | Status | Author | Reviewer | Change | Commit | | Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- | --- |
| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | [a2bf2d4] | | 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.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 |
--- ---
@@ -19,7 +19,7 @@
These stories cover the P1 use cases of the Project Plan that MIL-002 delivers 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 (O1 to O3 of [BC-001]): keeping the mirror metadata correct, configuring
credentials, onboarding a repository and diagnosing a failed run. Roles are the 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. 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 ## Story List
@@ -153,9 +153,48 @@ actors of [UCD-001]. Stories for quality checks and releases (MIL-004) and for t
| --- | --- | --- | | --- | --- | --- |
| [UC-005], [MIL-003] | fits one iteration | none | | [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 ## INVEST Check
All ten stories are independent of each other except that US-001.05 and 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 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 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 to the named role, is small enough for one iteration, and has acceptance
@@ -170,10 +209,11 @@ behaviour is tested rather than built.
[MIL-001]: ./milestones/mil-001-stabilise-metadata-sync.md [MIL-001]: ./milestones/mil-001-stabilise-metadata-sync.md
[MIL-002]: ./milestones/mil-002-onboarding-and-operations.md [MIL-002]: ./milestones/mil-002-onboarding-and-operations.md
[MIL-003]: ./milestones/mil-003-quality-checks.md [MIL-003]: ./milestones/mil-003-quality-checks.md
[MIL-004]: ./milestones/mil-004-versioned-release.md
[UC-001]: ./uc-001/uc.md [UC-001]: ./uc-001/uc.md
[UC-002]: ./uc-002/uc.md [UC-002]: ./uc-002/uc.md
[UC-003]: ./uc-003/uc.md [UC-003]: ./uc-003/uc.md
[UC-004]: ./uc-004/uc.md [UC-004]: ./uc-004/uc.md
[a2bf2d4]: https://git.tirsystem.com/TirSystem/github-action/commit/a2bf2d420416f7aff2badc6fe32a7690e2e523fd
[UC-005]: ./uc-005/uc.md [UC-005]: ./uc-005/uc.md
[385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7 [385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7
[UC-006]: ./uc-006/uc.md
guides/release-process.md
+64
View File
@@ -0,0 +1,64 @@
# Release process
For the maintainers of this repository: how a change to the shared workflows
is validated, versioned and announced, and how consumers pin a version. The
decisions are in ADR-0006; this guide is the checklist. It is not published
on the wiki.
Until the release workflow exists (MIL-004 task 5) the steps are done by hand.
## What a version is
| Item | Rule |
| --- | --- |
| Unit | The whole repository: the workflows, their scripts and the guides |
| Version tag | `vMAJOR.MINOR.PATCH`, for example `v1.2.0`; never deleted or moved |
| Major tag | `vMAJOR`, for example `v1`; points to the latest compatible release |
| First release | `v1.0.0` |
| Breaking (new major) | A renamed or removed workflow, input, secret name or output; a raised default tool version or a changed default that can turn a green consumer red; a changed meaning of pass or fail |
| Minor | A new optional input, workflow or capability; nothing changes for existing callers |
| Patch | A fix, or documentation and tests, with no visible change for consumers |
## Checklist for a release
1. **Decide the version** from the table above, looking at every merged change
since the last tag.
2. **Check the commit.** The validation run (`validate-workflows`) on the exact
commit of `main` to be released is green; do not release from a red or
unchecked commit.
3. **Write the changelog entry** in `CHANGELOG.md`: the version, the date, and
the changes in the groups Breaking, Added, Changed and Fixed. A change that
touches credentials, tokens or permissions says so.
4. **Get the approval** of S01 for the release, in the pull request that adds
the changelog entry.
5. **Tag.** Create `vMAJOR.MINOR.PATCH` on the approved commit, then move
`vMAJOR` to it:
```bash
git tag -a v1.2.0 -m "v1.2.0" <commit>
git push origin v1.2.0
git tag -f v1 <commit> && git push -f origin v1
```
6. **Announce.** Create the release page for the tag with the changelog entry
as its text, and say whether consumers must act.
7. **Verify.** One repository pinned to the previous exact tag still runs the
same code; one repository on the major tag receives the release.
## How consumers pin
| Pin | Receives | Use when |
| --- | --- | --- |
| `@v1.2.0` | nothing new, ever | a pipeline must not change |
| `@v1` | compatible releases only | the default for a project |
| `@main` | everything, unreleased | never; only this repository's own tests |
Reusable workflows are pinned in the `uses:` line of the caller. The scoped
workflows (sync and publish wiki) are delivered from `main` by the instance
and cannot be pinned by a consumer; they fetch their scripts at the major tag
once `v1` exists.
## Undoing a faulty release
1. Move the major tag back to the previous exact tag:
`git tag -f v1 v1.1.0 && git push -f origin v1`.
2. Fix forward on `main` and release a patch version.
3. Do not delete or move an exact tag; consumers may have pinned it.