From 02e3794d7b05799af2544ca303c99271da788e82 Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Wed, 14 Oct 2026 15:57:16 +0800 Subject: [PATCH 1/2] Plan MIL-011: fix the defaults of the code metrics workflow Release 2.1.0 documents code-metrics.yml at @v1 and defaults tools-ref to v1, but the workflow and its scripts exist only from v2.1.0. MIL-011 plans the fix (a patch release 2.1.1), the test that would have caught it, the guide and wiki corrections, and the removal of the workaround from the framework Badges page. Proposed; no code changes yet. --- docs/artifact-registry.md | 2 +- .../mil-011-code-metrics-default-tools-ref.md | 87 +++++++++++++++++++ docs/project-plan.md | 13 ++- 3 files changed, 97 insertions(+), 5 deletions(-) create mode 100644 docs/milestones/mil-011-code-metrics-default-tools-ref.md diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index bac6072..8500754 100644 --- a/docs/artifact-registry.md +++ b/docs/artifact-registry.md @@ -10,7 +10,7 @@ each document lives in *this* project and the next version to use. | BC | Business Case | docs/business-case.md | 002 | | SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 | | PP | Project Plan | docs/project-plan.md | 002 | -| MIL | Milestone / Gateway | docs/milestones/*.md | 011 | +| MIL | Milestone / Gateway | docs/milestones/*.md | 012 | | RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 076 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | | ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0011 | diff --git a/docs/milestones/mil-011-code-metrics-default-tools-ref.md b/docs/milestones/mil-011-code-metrics-default-tools-ref.md new file mode 100644 index 0000000..74d5dfc --- /dev/null +++ b/docs/milestones/mil-011-code-metrics-default-tools-ref.md @@ -0,0 +1,87 @@ +# MIL-011: Fix the defaults of the code metrics workflow + +## Metadata +| Key | Value | +| --- | --- | +| ID | MIL-011 | +| CrossReference | [BC-001], [US-001], [MIL-010], [ADR-0010], [ADR-0006] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Purpose + +Decide whether the released code metrics workflow can be called with its documented defaults, and correct it if it cannot. + +Release 2.1.0 ([MIL-010]) added `code-metrics.yml`. Its guide, its header comment and the default of its `tools-ref` input name `v1`, but the workflow and its scripts (`tools/code-metrics.sh`, `tools/count_loc.py`, `tools/badges.py`) exist only from `v2.1.0`. A caller who follows the guide (`@v1`) cannot resolve the workflow, and a caller at `@v2` that leaves `tools-ref` at its default fetches the scripts from `v1`, where they are absent, so the run fails. The offline tests of [MIL-010] did not see it, because they run the scripts from the checkout and never resolve a ref. The framework wiki page `Badges` works around it by telling callers to set `tools-ref: v2`. + +The other four reusable workflows also default `tools-ref` to `v1`; their scripts exist at `v1`, but a default that follows an old major is the same kind of error, so this milestone checks them too. + +## Deliverable + +A patch release (`2.1.1`, [ADR-0006]) in which: the default `tools-ref` of every reusable workflow names a tag that holds the scripts it runs; the guide, the header comment of `code-metrics.yml`, the upgrading guide, the README and the wiki pages in English, Danish and Bahasa Malaysia call the workflow at `@v2`; a test fails when a default `tools-ref` names a tag without the script; and the changelog has a `Fixed` entry. In `TirSystem/sqa-qc-framework`: the `Badges` wiki page without the `tools-ref` workaround. + +## Go / No-Go Criteria + +| # | Criterion (objectively checkable) | Go | No-Go | +| --- | --- | --- | --- | +| 1 | The defect is reproduced before the fix: a call at the major tag with the defaults fails, and the failure names the missing script, recorded in this milestone | Reproduced and recorded | Not reproduced, or not recorded | +| 2 | Every reusable workflow's default `tools-ref` names a tag that contains the script file the workflow runs, listed per workflow in this milestone | All five checked and listed | A default names a tag without its script | +| 3 | The default is derived, not copied: one place gives the current major, and a test fails when a workflow default differs from it or names a tag without the script | Test fails on a seeded wrong default and passes on the fix | No such test | +| 4 | No guide, comment, README or wiki page tells a caller to use `@v1` for `code-metrics.yml`; a search of `guides/`, `README.md`, `docs/wiki/` and `.gitea/workflows/` finds none | Count is 0 | A page still says `@v1` for it | +| 5 | A call with the documented defaults runs on the instance and commits the badges to a `badges` branch, verified on a throwaway branch and recorded | Run succeeds | Fails or is not run | +| 6 | The release is a patch (`2.1.1`): the changelog has a `Fixed` entry, the major tag `v2` moves to it, and `v1` is not touched | Released | Released as another level, or `v1` moved | +| 7 | The framework `Badges` page no longer tells a caller to set `tools-ref`, in all three languages, and still calls the workflow at `@v2` | Page merged | The workaround remains | +| 8 | Reviewed | A review record (`RC-*`) for this milestone and the changed workflow, tests and guides, each with a verdict of Go | An instance without a record | + +## Dependencies + +| Depends on | Reason | +| --- | --- | +| [MIL-010] | The workflow and its guide are its deliverables; the defect is in release 2.1.0 | +| [ADR-0006] | The release process: a fix is a patch release, and a moving major tag follows it | + +## Traceability + +| Business Case objective / KPI / user story | Reference | +| --- | --- | +| Business Case objective O5 (shared workflows that a repository can call without writing its own) | [BC-001] | +| User stories | [US-001] (no new story: the tasks below are technical, and the story of [MIL-010] for the badges stays as written) | + +## Ownership + +| Role | Stakeholder ID (SA) | +| --- | --- | +| Owner | S05 | +| Approving reviewer | S01 | + +## Target Date + +2026-10-23 (Friday), one week of work: the fix is small and a caller cannot use the workflow until it is released. This precedes the planned decision date of [MIL-010] (2027-01-30) because that milestone was released on 2026-10-14, ahead of its date; the schedule row of [MIL-010] is not changed here. The Business Case sets no deadline. + +## Tasks + +| # | Task | Summary | Needs its own Use Case/User Story? | Reference | +| --- | --- | --- | --- | --- | +| 1 | Reproduce the defect and list the defaults | On a throwaway branch, call `code-metrics.yml` at `@v2` with the defaults and at `@v1`, and record both failures and the message. List, for each of the five reusable workflows, the default `tools-ref` and whether the script it runs exists at that tag. Record the result in this milestone. | No | [MIL-010] | +| 2 | Fix the defaults | Give the repository one definition of the current major (a file the workflows' tests and the release workflow read), set the default `tools-ref` of every reusable workflow from it, and change the header comment of `code-metrics.yml` to `@v2`. A workflow whose script is at the previous major keeps that tag only with a comment that says why. | No | [ADR-0006] | +| 3 | Add the test | An offline test that reads every workflow in `.gitea/workflows/`, takes the default `tools-ref` and the script it runs, and fails when the default differs from the current major or the script is not in that tag (checked with `git cat-file` against the tags of the checkout). Show it fails on a seeded wrong default and passes on the fix. | No | [MIL-010] | +| 4 | Correct the guides, README and wiki | Change `@v1` to `@v2` for `code-metrics.yml` in `guides/code-metrics.md`, `guides/upgrading.md`, `README.md` and `docs/wiki/CodeMetrics.md`, `.da.md` and `.ms.md`; say in the guide that `tools-ref` defaults to the current major. Search the repository for the remaining `@v1`. | No | | +| 5 | Verify on the instance | On a throwaway branch of a repository, call the fixed workflow at the branch with the defaults, and check that the `badges` branch gets the SVG files. Record the run. | No | [MIL-010] | +| 6 | Release 2.1.1 | Add the `Fixed` entry to the changelog (ADR-0006: a patch), run the Release workflow, and check that `v2` points at `v2.1.1` and `v1` at `v1.2.2`. | No | [ADR-0006] | +| 7 | Remove the workaround from the framework page | In `TirSystem/sqa-qc-framework`, remove the `tools-ref: v2` line and the two bullets about it from `docs/wiki/Badges.md`, `Badges-da.md` and `Badges-ms.md`, and add a changelog line. This is a change in another repository, made after release 2.1.1 and in its own pull request. | No | | +| 8 | Add MIL-011 to the Project Plan | Add the schedule row, the Gantt bar, the scope entry and the dependency to [PP-001], and its review to the traceability matrix. | No | | +| 9 | Review | Record `RC-*` for this milestone, the workflow and tests, and the guides, each with a verdict. | No | | + +--- + +[BC-001]: ../business-case.md +[US-001]: ../user-stories.md +[MIL-010]: ./mil-010-code-metrics-badges.md +[ADR-0010]: ../adr/adr-0010-code-metrics-badges-contract.md +[ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.md +[PP-001]: ../project-plan.md diff --git a/docs/project-plan.md b/docs/project-plan.md index 63dcd12..4f4df6d 100644 --- a/docs/project-plan.md +++ b/docs/project-plan.md @@ -4,13 +4,13 @@ | Key | Value | | --- | --- | | ID | PP-001 | -| CrossReference | [BC-001], [SA-001], [ADR-0002], [US-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010] | +| CrossReference | [BC-001], [SA-001], [ADR-0002], [US-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010], [MIL-011] | ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-14 | Deprecated | Jens Tirsvad Nielsen | AI as stand-in for S01 | MIL-009 plan accepted in chat with the defaults; target date 2026-11-30 confirmed (RC-064) | [2f267df] | -| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added MIL-010 (code metrics and coverage badges); reviewed (RC-068) | [5002450] | +| 2026-10-14 | Deprecated | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added MIL-010 (code metrics and coverage badges); reviewed (RC-068) | [5002450] | +| 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | Added MIL-011 (fix the defaults of the code metrics workflow); not yet reviewed | pending | --- @@ -40,6 +40,7 @@ workflows. The Business Case sets no deadline, so the dates are the plan's own; | Wiki publishing as a reusable workflow | [MIL-008] | 2026-10-13 to 2026-11-15 | 2026-11-15 | S05 | None yet | Reusable publish-wiki-pages workflow, wiki in docs/wiki, scoped workflow deprecated, released as 1.2.2 | [Milestone MIL-008] | | Migrate the wiki callers and remove the scoped workflow | [MIL-009] | 2026-11-16 to 2026-11-30 | 2026-11-30 | S05 | None yet | Seven repositories publish through a caller, scoped workflow removed, ADR-0004 superseded, released as 2.0.0 | Not created yet (the sync creates it when MIL-009 is Accepted) | | Code metrics and coverage badges | [MIL-010] | 2027-01-18 to 2027-01-30 | 2027-01-30 | S05 | None yet (task 1 writes them) | Reusable workflow that counts code files and lines of code, reads coverage and commits SVG badges, released | Not created yet (the sync creates it when MIL-010 is Accepted) | +| Fix the defaults of the code metrics workflow | [MIL-011] | 2026-10-14 to 2026-10-23 | 2026-10-23 | S05 | None (technical tasks) | Patch release 2.1.1: the default `tools-ref` of every reusable workflow names a tag that holds its scripts, a test for it, guides and wiki at `@v2`, the framework Badges page without the workaround | Not created yet (the sync creates it when MIL-011 is Accepted) | ```plantuml @startgantt @@ -64,6 +65,8 @@ Project starts 2026-10-05 [MIL-009 Go/No-Go] happens 2026-11-30 [MIL-010 Badges] starts 2027-01-18 and ends 2027-01-30 [MIL-010 Go/No-Go] happens 2027-01-30 +[MIL-011 Defaults fix] starts 2026-10-14 and ends 2026-10-23 +[MIL-011 Go/No-Go] happens 2026-10-23 @endgantt ``` @@ -81,6 +84,7 @@ Project starts 2026-10-05 | The wiki publisher as a workflow that repositories call, from docs/wiki | [MIL-008] | | Moving every publishing repository to the called workflow and removing the scoped one | [MIL-009] | | A shared workflow for code metrics and coverage badges | [MIL-010] | +| The code metrics workflow works with its documented defaults | [MIL-011] | ## Dependencies @@ -89,7 +93,7 @@ MIL-001 → MIL-002 → MIL-003 → MIL-004 MIL-002 → MIL-005 → MIL-006 MIL-003 + MIL-004 → MIL-007 MIL-006 → MIL-008 → MIL-009 - MIL-003 + MIL-004 → MIL-010 + MIL-003 + MIL-004 → MIL-010 → MIL-011 ``` A No-Go moves every later window by the rework time of the failed milestone. @@ -278,6 +282,7 @@ no tests, no release process. [MIL-008]: ./milestones/mil-008-wiki-reusable-workflow.md [MIL-009]: ./milestones/mil-009-migrate-wiki-callers-and-remove-scoped-workflow.md [MIL-010]: ./milestones/mil-010-code-metrics-badges.md +[MIL-011]: ./milestones/mil-011-code-metrics-default-tools-ref.md [Milestone MIL-001]: https://git.tirsystem.com/TirSystem/github-action/milestone/18 [Milestone MIL-002]: https://git.tirsystem.com/TirSystem/github-action/milestone/19 [Milestone MIL-003]: https://git.tirsystem.com/TirSystem/github-action/milestone/20 From 60f39e385412ca1612cc583518795d9d38974e87 Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Wed, 14 Oct 2026 15:57:20 +0800 Subject: [PATCH 2/2] Resolve pending commit links for MIL-011 --- docs/milestones/mil-011-code-metrics-default-tools-ref.md | 3 ++- docs/project-plan.md | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/milestones/mil-011-code-metrics-default-tools-ref.md b/docs/milestones/mil-011-code-metrics-default-tools-ref.md index 74d5dfc..ad99ba8 100644 --- a/docs/milestones/mil-011-code-metrics-default-tools-ref.md +++ b/docs/milestones/mil-011-code-metrics-default-tools-ref.md @@ -9,7 +9,7 @@ ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | pending | +| 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | [02e3794] | --- @@ -85,3 +85,4 @@ A patch release (`2.1.1`, [ADR-0006]) in which: the default `tools-ref` of every [ADR-0010]: ../adr/adr-0010-code-metrics-badges-contract.md [ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.md [PP-001]: ../project-plan.md +[02e3794]: https://git.tirsystem.com/TirSystem/github-action/commit/02e3794d7b05799af2544ca303c99271da788e82 diff --git a/docs/project-plan.md b/docs/project-plan.md index 4f4df6d..35f75e4 100644 --- a/docs/project-plan.md +++ b/docs/project-plan.md @@ -10,7 +10,7 @@ | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | | 2026-10-14 | Deprecated | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added MIL-010 (code metrics and coverage badges); reviewed (RC-068) | [5002450] | -| 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | Added MIL-011 (fix the defaults of the code metrics workflow); not yet reviewed | pending | +| 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | Added MIL-011 (fix the defaults of the code metrics workflow); not yet reviewed | [02e3794] | --- @@ -294,3 +294,4 @@ no tests, no release process. [b74ee0e]: https://git.tirsystem.com/TirSystem/github-action/commit/b74ee0e5cfd04f25ba5f2c1addc80699147c479a [2f267df]: https://git.tirsystem.com/TirSystem/github-action/commit/2f267df2a270087cb7dc482af4ce4f4341e97b03 [5002450]: https://git.tirsystem.com/TirSystem/github-action/commit/50024505fe788b1c5e3021c0d1fc3d079590070e +[02e3794]: https://git.tirsystem.com/TirSystem/github-action/commit/02e3794d7b05799af2544ca303c99271da788e82