github-action/docs/milestones/mil-011-code-metrics-default-tools-ref.md

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

---