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..ad99ba8 --- /dev/null +++ b/docs/milestones/mil-011-code-metrics-default-tools-ref.md @@ -0,0 +1,88 @@ +# 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 | [02e3794] | + +--- + +## 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 +[02e3794]: https://git.tirsystem.com/TirSystem/github-action/commit/02e3794d7b05799af2544ca303c99271da788e82 diff --git a/docs/project-plan.md b/docs/project-plan.md index 63dcd12..35f75e4 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 | [02e3794] | --- @@ -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 @@ -289,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