Pin the scoped workflows to v1 and record the MIL-004 results #82

Merged
Tirsvad merged 2 commits from mil-004-pin-scripts-v1 into main 2026-10-10 21:04:24 +02:00
13 changed files with 96 additions and 28 deletions
Showing only changes of commit 6933e91c83 - Show all commits
+1 -1
View File
@@ -31,7 +31,7 @@ jobs:
uses: actions/checkout@v4 uses: actions/checkout@v4
with: with:
repository: TirSystem/github-action repository: TirSystem/github-action
ref: main ref: v1
path: shared-scripts path: shared-scripts
- name: Publish the pages to the wiki - name: Publish the pages to the wiki
@@ -21,7 +21,7 @@ jobs:
uses: actions/checkout@v4 uses: actions/checkout@v4
with: with:
repository: TirSystem/github-action repository: TirSystem/github-action
ref: main ref: v1
path: shared-scripts path: shared-scripts
- name: Sync description and topics - name: Sync description and topics
+1 -1
View File
@@ -4,7 +4,7 @@ name: Quality checks
# #
# jobs: # jobs:
# quality: # quality:
# uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@main # uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1
# #
# It checks the Python and shell files of the repository with pinned tools, # It checks the Python and shell files of the repository with pinned tools,
# changes no file and needs no secret. # changes no file and needs no secret.
+5
View File
@@ -20,6 +20,11 @@ Each release lists its changes in these groups, in this order:
## [Unreleased] ## [Unreleased]
### Changed
- The scoped workflows fetch their scripts at the tag `v1` instead of `main`,
so a merge to `main` reaches consumers only when it is released.
## [1.0.0] - 2026-10-10 ## [1.0.0] - 2026-10-10
First release. The reusable workflow can be pinned at `v1` or `v1.0.0`. The First release. The reusable workflow can be pinned at `v1` or `v1.0.0`. The
+1 -1
View File
@@ -11,7 +11,7 @@ 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 | 048 | | RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 049 |
| 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 | 0008 | | ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0008 |
| UCD | Use Case Diagram | docs/use-case-diagram.md | 002 | | UCD | Use Case Diagram | docs/use-case-diagram.md | 002 |
+19 -4
View File
@@ -9,8 +9,8 @@
## Version History ## Version History
| Date | Status | Author | Reviewer | Change | Commit | | Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- | --- |
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Target date 2026-11-28 confirmed on 2026-10-10 by S01 (stand-in for S05) | [ea06eaa] | | 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added task 6 (embedded scripts to files) and Go/No-Go criterion 5; traceability adds O2 (RC-034) | [616c5d2] |
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added task 6 (embedded scripts to files) and Go/No-Go criterion 5; traceability adds O2 (RC-034) | [616c5d2] | | 2026-10-11 | Accepted | Jens Tirsvad Nielsen | S01 | Added the verification results of the first release (v1.0.0) | pending |
--- ---
@@ -71,10 +71,25 @@ reference that a release can pin, instead of Python embedded in their YAML.
| 5 | Implement the reusable release workflow | Validate the version, build release notes from the changelog and publish to the chosen destination. | Yes | Use case candidate: publish a release | | 5 | Implement the reusable release workflow | Validate the version, build release notes from the changelog and publish to the chosen destination. | Yes | Use case candidate: publish a release |
| 6 | Move the embedded scripts of the scoped workflows to files | The sync (`sync-github-metadata.yml`) and publish-wiki workflows embed 200 to 300 lines of Python in their YAML, which is hard to read, lint and review. Move the code to `tools/sync_github_metadata.py` and `tools/publish_wiki.py`; each scoped workflow then checks out `TirSystem/github-action` into its own folder with `actions/checkout` and runs the file, as verified on 2026-10-10 from repositories of two organizations. Keep the behaviour, the messages and the offline tests, which import the files instead of executing the YAML; use `ref: main` first, and let the release process of task 1 define how a consumer pins a tag. | No | | | 6 | Move the embedded scripts of the scoped workflows to files | The sync (`sync-github-metadata.yml`) and publish-wiki workflows embed 200 to 300 lines of Python in their YAML, which is hard to read, lint and review. Move the code to `tools/sync_github_metadata.py` and `tools/publish_wiki.py`; each scoped workflow then checks out `TirSystem/github-action` into its own folder with `actions/checkout` and runs the file, as verified on 2026-10-10 from repositories of two organizations. Keep the behaviour, the messages and the offline tests, which import the files instead of executing the YAML; use `ref: main` first, and let the release process of task 1 define how a consumer pins a tag. | No | |
## Verification results
The first release was cut on 2026-10-11 with the Release workflow (run 623 on
`97ffa49`, after a dry run, run 622): the tag `v1.0.0`, the moving tag `v1`
and the release page were created, and the job token was enough (ADR-0007).
| # | Criterion | Result |
| --- | --- | --- |
| 1 | A release is validated before a tag is created | Go: `tools/release.py` refuses unless the status `Validate workflows / validate (push)` of the tip of `main` is success; tested for failed and missing runs |
| 2 | Version tag and changelog entry that marks breaking changes | Go: `v1.0.0` and `CHANGELOG.md` `[1.0.0]`; `tools/changelog.py` checks the convention |
| 3 | A consumer pinned to the previous version keeps working | Go: tags are never moved or deleted; the upgrade guide describes the way back; the first release has no previous version, so this is by construction until `v1.0.1` |
| 4 | Publish destination decided, token scope documented | Go: ADR-0007 |
| 5 | No embedded Python in the scoped workflows | Go: both run files of this repository, with offline tests that exercise the files (MIL-004 task 6) |
After the release the two scoped workflows fetch their scripts at `ref: v1`
(RC-043 action item).
--- ---
[BC-001]: ../business-case.md [BC-001]: ../business-case.md
[4de5438]: https://git.tirsystem.com/TirSystem/github-action/commit/4de5438a88b4bbf18b165f52f797d1a52af89f6d
[ADR-0002]: ../adr/adr-0002-s01-approves-as-stand-in.md [ADR-0002]: ../adr/adr-0002-s01-approves-as-stand-in.md
[ea06eaa]: https://git.tirsystem.com/TirSystem/github-action/commit/ea06eaaa698247d20e4a8e2694d7acbb1de58b63
[616c5d2]: https://git.tirsystem.com/TirSystem/github-action/commit/616c5d2e48f0d76399a6f78923891fc7f50c8e22 [616c5d2]: https://git.tirsystem.com/TirSystem/github-action/commit/616c5d2e48f0d76399a6f78923891fc7f50c8e22
@@ -0,0 +1,45 @@
# Review Record: MIL-004 (verification results)
## Metadata
| Key | Value |
| --- | --- |
| ID | RC-048 |
| CrossReference | [MIL-004], [QC-MIL-001] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-11 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending |
---
## Artifact Under Review
- Instance reviewed: [MIL-004] after the first release, with its new Verification results section
- Checklist used: [QC-MIL-001]
## Checklist Results
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 1 | A concrete deliverable is defined for every gate | Pass | The release process, the upgrade guide, the release workflow and the scripts at a pinned reference now exist; the release page of `v1.0.0` is the proof. |
| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | All five criteria have a result in the Verification results table, each naming its evidence. |
| 3 | Dependencies on other milestones are explicitly mapped | Pass | Unchanged (MIL-003). |
| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | O2 and O4, unchanged. |
| 5 | Milestone owner and approving reviewer are identified | Pass | Owner S05, approving reviewer S01, unchanged. |
| 6 | Milestone has a defined target date consistent with project constraints | Pass | 2026-11-28; the criteria are met on 2026-10-11. |
## Overall Verdict
Go - all six criteria pass, and the five Go/No-Go criteria of MIL-004 are met. One limit is stated, not hidden: criterion 3 (a consumer pinned to the previous version keeps working) is met by construction until a second release exists, because tags are never moved. S01 gave the Go in chat on 2026-10-11, standing in for the other reviewers as ADR-0002 records; there is no independent reader.
## Action Items
| Action | Owner | Due |
| --- | --- | --- |
| Verify criterion 3 with a real consumer when `v1.0.1` or `v1.1.0` is released | S05 | next release |
---
[MIL-004]: ../../milestones/mil-004-versioned-release.md
[QC-MIL-001]: ../../../framework/qc/qc-milestones-gateways.md
+6 -5
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], [RC-040], [RC-041], [RC-042], [RC-043], [RC-044], [RC-045], [RC-046], [RC-047], [ADR-0007], [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] | | 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], [RC-047], [RC-048], [ADR-0007], [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 ## Version History
| Date | Status | Author | Reviewer | Change | Commit | | Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- | --- |
| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added UC-007 and RC-044 to RC-046 | [4cf52af] | | 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added ADR-0007 and RC-047 | [d9cd3c6] |
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added ADR-0007 and RC-047 | [d9cd3c6] | | 2026-10-11 | Accepted | Jens Tirsvad Nielsen | S01 | Added RC-048 (MIL-004 verification results) | pending |
--- ---
@@ -30,7 +30,7 @@ updated whenever an artifact instance is created or reviewed.
| [MIL-001] | MIL | [BC-001], [PP-001] | [MIL-002] | [RC-003], [RC-026] | | [MIL-001] | MIL | [BC-001], [PP-001] | [MIL-002] | [RC-003], [RC-026] |
| [MIL-002] | MIL | [BC-001], [PP-001], [MIL-001] | [MIL-003], [MIL-005] | [RC-005], [RC-027] | | [MIL-002] | MIL | [BC-001], [PP-001], [MIL-001] | [MIL-003], [MIL-005] | [RC-005], [RC-027] |
| [MIL-003] | MIL | [BC-001], [PP-001], [MIL-002] | [MIL-004] | [RC-006], [RC-028], [RC-033], [RC-039] | | [MIL-003] | MIL | [BC-001], [PP-001], [MIL-002] | [MIL-004] | [RC-006], [RC-028], [RC-033], [RC-039] |
| [MIL-004] | MIL | [BC-001], [PP-001], [MIL-003] | - | [RC-007], [RC-029], [RC-034] | | [MIL-004] | MIL | [BC-001], [PP-001], [MIL-003] | - | [RC-007], [RC-029], [RC-034], [RC-048] |
| [RC-001] | RC | [BC-001] | - | - | | [RC-001] | RC | [BC-001] | - | - |
| [RC-002] | RC | [PP-001] | - | - | | [RC-002] | RC | [PP-001] | - | - |
| [RC-003] | RC | [MIL-001] | - | - | | [RC-003] | RC | [MIL-001] | - | - |
@@ -96,6 +96,7 @@ updated whenever an artifact instance is created or reviewed.
| [RC-045] | RC | [UCD-001] | - | - | | [RC-045] | RC | [UCD-001] | - | - |
| [RC-046] | RC | [US-001] | - | - | | [RC-046] | RC | [US-001] | - | - |
| [RC-047] | RC | [ADR-0007] | - | - | | [RC-047] | RC | [ADR-0007] | - | - |
| [RC-048] | RC | [MIL-004] | - | - |
## Coverage Notes ## Coverage Notes
@@ -172,11 +173,11 @@ updated whenever an artifact instance is created or reviewed.
[RC-045]: ./reviews/rc-045-ucd-001-consume.md [RC-045]: ./reviews/rc-045-ucd-001-consume.md
[RC-046]: ./reviews/rc-046-us-001-consume.md [RC-046]: ./reviews/rc-046-us-001-consume.md
[RC-047]: ./reviews/rc-047-adr-0007.md [RC-047]: ./reviews/rc-047-adr-0007.md
[RC-048]: ./reviews/rc-048-mil-004-outcome.md
[ADR-0007]: ../adr/adr-0007-release-publish-destination.md [ADR-0007]: ../adr/adr-0007-release-publish-destination.md
[UC-007]: ../uc-007/uc.md [UC-007]: ../uc-007/uc.md
[UC-006]: ../uc-006/uc.md [UC-006]: ../uc-006/uc.md
[ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.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
[4cf52af]: https://git.tirsystem.com/TirSystem/github-action/commit/4cf52afe00f546c6b20424fb8dfc12796ffd9296
[d9cd3c6]: https://git.tirsystem.com/TirSystem/github-action/commit/d9cd3c67d4017984af8958f32240d3d66217e153 [d9cd3c6]: https://git.tirsystem.com/TirSystem/github-action/commit/d9cd3c67d4017984af8958f32240d3d66217e153
+5 -4
View File
@@ -19,7 +19,7 @@ jobs:
quality: quality:
permissions: permissions:
contents: read contents: read
uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@main uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1
with: with:
languages: python,shell languages: python,shell
``` ```
@@ -33,9 +33,10 @@ jobs:
| `shellcheck-py-version` | `0.10.0.1` | Version of the shellcheck-py package (ShellCheck 0.10.0) | | `shellcheck-py-version` | `0.10.0.1` | Version of the shellcheck-py package (ShellCheck 0.10.0) |
| `shfmt-py-version` | `3.11.0.2` | Version of the shfmt-py package (shfmt 3.11.0) | | `shfmt-py-version` | `3.11.0.2` | Version of the shfmt-py package (shfmt 3.11.0) |
Reference the workflow at `main` or at a tag, never at the branch of a pull Reference the workflow at the major tag (`@v1`) or at an exact tag
request: that branch is deleted when the pull request is merged and the (`@v1.0.0`), never at `main` and never at the branch of a pull request: that
reference stops working. branch is deleted when the pull request is merged and the reference stops
working. See the upgrade guide for what each choice receives.
## What is checked ## What is checked
+1 -1
View File
@@ -469,7 +469,7 @@ class TestWorkflow:
assert steps[0]["uses"].startswith("actions/checkout@") assert steps[0]["uses"].startswith("actions/checkout@")
assert steps[1]["with"] == { assert steps[1]["with"] == {
"repository": "TirSystem/github-action", "repository": "TirSystem/github-action",
"ref": "main", "ref": "v1",
"path": "shared-scripts", "path": "shared-scripts",
} }
assert steps[-1]["run"] == "python3 shared-scripts/tools/publish_wiki.py" assert steps[-1]["run"] == "python3 shared-scripts/tools/publish_wiki.py"
+3 -3
View File
@@ -1,4 +1,4 @@
<!-- translation of QualityChecks.md, source sha256 84ed5e09689a --> <!-- translation of QualityChecks.md, source sha256 aa9c7296fa52 -->
> Dette er en oversættelse af [`QualityChecks`](QualityChecks). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres. > Dette er en oversættelse af [`QualityChecks`](QualityChecks). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
@@ -22,7 +22,7 @@ jobs:
quality: quality:
permissions: permissions:
contents: read contents: read
uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@main uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1
with: with:
languages: python,shell languages: python,shell
``` ```
@@ -36,7 +36,7 @@ jobs:
| `shellcheck-py-version` | `0.10.0.1` | Version af pakken shellcheck-py (ShellCheck 0.10.0) | | `shellcheck-py-version` | `0.10.0.1` | Version af pakken shellcheck-py (ShellCheck 0.10.0) |
| `shfmt-py-version` | `3.11.0.2` | Version af pakken shfmt-py (shfmt 3.11.0) | | `shfmt-py-version` | `3.11.0.2` | Version af pakken shfmt-py (shfmt 3.11.0) |
Henvis til workflowet ved `main` eller et tag, aldrig ved en pull requests gren: den gren slettes, når pull requesten flettes, og henvisningen holder op med at virke. Henvis til workflowet ved major-tagget (`@v1`) eller et præcist tag (`@v1.0.0`), aldrig ved `main` og aldrig ved en pull requests gren: den gren slettes, når pull requesten flettes, og henvisningen holder op med at virke. Se opgraderingsvejledningen for, hvad hvert valg modtager.
## Hvad der kontrolleres ## Hvad der kontrolleres
+5 -4
View File
@@ -25,7 +25,7 @@ jobs:
quality: quality:
permissions: permissions:
contents: read contents: read
uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@main uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1
with: with:
languages: python,shell languages: python,shell
``` ```
@@ -39,9 +39,10 @@ jobs:
| `shellcheck-py-version` | `0.10.0.1` | Version of the shellcheck-py package (ShellCheck 0.10.0) | | `shellcheck-py-version` | `0.10.0.1` | Version of the shellcheck-py package (ShellCheck 0.10.0) |
| `shfmt-py-version` | `3.11.0.2` | Version of the shfmt-py package (shfmt 3.11.0) | | `shfmt-py-version` | `3.11.0.2` | Version of the shfmt-py package (shfmt 3.11.0) |
Reference the workflow at `main` or at a tag, never at the branch of a pull Reference the workflow at the major tag (`@v1`) or at an exact tag
request: that branch is deleted when the pull request is merged and the (`@v1.0.0`), never at `main` and never at the branch of a pull request: that
reference stops working. branch is deleted when the pull request is merged and the reference stops
working. See the upgrade guide for what each choice receives.
## What is checked ## What is checked
+3 -3
View File
@@ -1,4 +1,4 @@
<!-- translation of QualityChecks.md, source sha256 84ed5e09689a --> <!-- translation of QualityChecks.md, source sha256 aa9c7296fa52 -->
> Ini ialah terjemahan [`QualityChecks`](QualityChecks). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya. > Ini ialah terjemahan [`QualityChecks`](QualityChecks). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
@@ -22,7 +22,7 @@ jobs:
quality: quality:
permissions: permissions:
contents: read contents: read
uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@main uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1
with: with:
languages: python,shell languages: python,shell
``` ```
@@ -36,7 +36,7 @@ jobs:
| `shellcheck-py-version` | `0.10.0.1` | Versi pakej shellcheck-py (ShellCheck 0.10.0) | | `shellcheck-py-version` | `0.10.0.1` | Versi pakej shellcheck-py (ShellCheck 0.10.0) |
| `shfmt-py-version` | `3.11.0.2` | Versi pakej shfmt-py (shfmt 3.11.0) | | `shfmt-py-version` | `3.11.0.2` | Versi pakej shfmt-py (shfmt 3.11.0) |
Rujuk aliran kerja pada `main` atau pada tag, jangan sekali-kali pada cabang pull request: cabang itu dipadam apabila pull request digabungkan dan rujukan itu berhenti berfungsi. Rujuk aliran kerja pada tag major (`@v1`) atau pada tag tepat (`@v1.0.0`), jangan sekali-kali pada `main` dan jangan pada cabang pull request: cabang itu dipadam apabila pull request digabungkan dan rujukan itu berhenti berfungsi. Lihat panduan naik taraf untuk apa yang diterima oleh setiap pilihan.
## Perkara yang disemak ## Perkara yang disemak