From 616c5d2e48f0d76399a6f78923891fc7f50c8e22 Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Sat, 10 Oct 2026 13:41:36 +0800 Subject: [PATCH] Plan task 6 of MIL-004: move the embedded scripts to files The sync and publish-wiki scoped workflows embed 200 to 300 lines of Python in their YAML. Add task 6 to move them to tools/ and run them from a checkout of this repository, as verified from two organisations, with a Go/No-Go criterion and O2 in the traceability. Review and accept the amendment (RC-034) and update TM-001. --- docs/artifact-registry.md | 2 +- docs/milestones/mil-004-versioned-release.md | 10 +++-- docs/sqa/reviews/rc-034-mil-004-scripts.md | 45 ++++++++++++++++++++ docs/sqa/traceability-matrix.md | 11 ++--- 4 files changed, 59 insertions(+), 9 deletions(-) create mode 100644 docs/sqa/reviews/rc-034-mil-004-scripts.md diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index d32aea3..12b0220 100644 --- a/docs/artifact-registry.md +++ b/docs/artifact-registry.md @@ -11,7 +11,7 @@ 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 | 034 | +| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 035 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | | ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0005 | | UCD | Use Case Diagram | docs/use-case-diagram.md | 002 | diff --git a/docs/milestones/mil-004-versioned-release.md b/docs/milestones/mil-004-versioned-release.md index 657c925..3217a1b 100644 --- a/docs/milestones/mil-004-versioned-release.md +++ b/docs/milestones/mil-004-versioned-release.md @@ -9,8 +9,8 @@ ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-03 | Deprecated | Jens Tirsvad Nielsen | S01 | Owner is S05 (security authority); S01 remains approving reviewer | [4de5438] | | 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 | Accepted | Jens Tirsvad Nielsen | S01 | Added task 6 (embedded scripts to files) and Go/No-Go criterion 5; traceability adds O2 (RC-034) | pending | --- @@ -23,7 +23,9 @@ workflow. ## Deliverable A documented release process for this repository (validation, version tag, -changelog), a consumer upgrade guide and a reusable release workflow. +changelog), a consumer upgrade guide and a reusable release workflow. The +scoped workflows run scripts that are files in this repository, fetched at a +reference that a release can pin, instead of Python embedded in their YAML. ## Go / No-Go Criteria @@ -33,6 +35,7 @@ changelog), a consumer upgrade guide and a reusable release workflow. | 2 | Each release has a version tag and a changelog entry that marks breaking changes | Present | Missing | | 3 | A consumer pinned to the previous version keeps working after a release | Verified | Breaks | | 4 | The publish destination (release page or package registry) is decided and its token scope documented | Decided | Open | +| 5 | The sync and publish-wiki workflows contain no embedded Python; each runs a script file of this repository, and the tests exercise the files | Count of embedded scripts is 0 and a run in another organization passes | Embedded script remains or a consumer run fails | ## Dependencies @@ -44,7 +47,7 @@ changelog), a consumer upgrade guide and a reusable release workflow. | Business Case objective / KPI / user story | Reference | | --- | --- | -| O4 | [BC-001] | +| O2, O4 | [BC-001] | ## Ownership @@ -66,6 +69,7 @@ changelog), a consumer upgrade guide and a reusable release workflow. | 3 | Write the consumer upgrade guide | Explain how to read a changelog entry, test an update in one repository and roll back. | Yes | Use case candidate: consume a workflow update | | 4 | Decide the publish destination | Choose the release or package destination for built artifacts and document the token scope it needs. | No | | | 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 | | --- diff --git a/docs/sqa/reviews/rc-034-mil-004-scripts.md b/docs/sqa/reviews/rc-034-mil-004-scripts.md new file mode 100644 index 0000000..0eafad8 --- /dev/null +++ b/docs/sqa/reviews/rc-034-mil-004-scripts.md @@ -0,0 +1,45 @@ +# Review Record: MIL-004 (scripts as files) + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-034 | +| CrossReference | [MIL-004], [QC-MIL-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: [MIL-004] +- Checklist used: [QC-MIL-001] + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | A concrete deliverable is defined for every gate | Pass | The deliverable now also names scripts as files fetched at a pinnable reference. | +| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | New criterion 5 is checkable: the count of embedded scripts is 0 and a run in another organization passes. | +| 3 | Dependencies on other milestones are explicitly mapped | Pass | Unchanged (MIL-003); task 6 needs no other milestone, because the checkout of a script repository was verified on 2026-10-10. | +| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | Finding fixed during this review: task 6 serves O2 (one canonical copy and a defined way to reach consuming repositories) and the Traceability table listed only O4. It now lists O2 and O4. | +| 5 | Milestone owner and approving reviewer are identified | Pass | Unchanged: owner S05, approving reviewer S01. | +| 6 | Milestone has a defined target date consistent with project constraints | Pass | 2026-11-28, confirmed (RC-029). | + +## Overall Verdict + +Go - all six 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. Accepting the amendment unlocks task 6 under the plan-first gate; the issue is still to be created with `sync-project.sh --apply`. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| Decide whether consumers pin a tag or follow `main` for the shared scripts (task 1 of this milestone) | S01 | 2026-11-16 | + +--- + +[MIL-004]: ../../milestones/mil-004-versioned-release.md +[QC-MIL-001]: ../../../framework/qc/qc-milestones-gateways.md diff --git a/docs/sqa/traceability-matrix.md b/docs/sqa/traceability-matrix.md index 07edde2..70df64c 100644 --- a/docs/sqa/traceability-matrix.md +++ b/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], [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], [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-026 to RC-032 (dates confirmed) | [ea06eaa] | -| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added RC-033 for MIL-003 | [b3f006f] | +| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added RC-033 for MIL-003 | [b3f006f] | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added RC-034 for MIL-004 | 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-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] | -| [MIL-004] | MIL | [BC-001], [PP-001], [MIL-003] | - | [RC-007], [RC-029] | +| [MIL-004] | MIL | [BC-001], [PP-001], [MIL-003] | - | [RC-007], [RC-029], [RC-034] | | [RC-001] | RC | [BC-001] | - | - | | [RC-002] | RC | [PP-001] | - | - | | [RC-003] | RC | [MIL-001] | - | - | @@ -76,6 +76,7 @@ updated whenever an artifact instance is created or reviewed. | [RC-031] | RC | [MIL-006] | - | - | | [RC-032] | RC | [PP-001] | - | - | | [RC-033] | RC | [MIL-003] | - | - | +| [RC-034] | RC | [MIL-004] | - | - | ## Coverage Notes @@ -138,5 +139,5 @@ updated whenever an artifact instance is created or reviewed. [RC-031]: ./reviews/rc-031-mil-006-date.md [RC-032]: ./reviews/rc-032-pp-001-dates.md [RC-033]: ./reviews/rc-033-mil-003-reusable-workflows.md -[ea06eaa]: https://git.tirsystem.com/TirSystem/github-action/commit/ea06eaaa698247d20e4a8e2694d7acbb1de58b63 +[RC-034]: ./reviews/rc-034-mil-004-scripts.md [b3f006f]: https://git.tirsystem.com/TirSystem/github-action/commit/b3f006f7a482392189a46c324ad4f28c4c3a2d2a