MIL-008: plan the wiki as a reusable workflow, ADR-0009, RC-060, RC-061

MIL-008 plans publishing the wiki through a reusable workflow that reads docs/wiki/. ADR-0009 records the decision. RC-060 accepts the plan; RC-061 accepts the amendment that deprecates the scoped workflow instead of removing it, because eight repositories still publish through it.
2026-10-13 22:20:09 +08:00
parent ea3fa44018
commit 01b9c2972b
6 changed files with 294 additions and 6 deletions
@@ -0,0 +1,92 @@
 # ADR-0009: Wiki publishing as a reusable workflow
 ## Metadata
 | Key | Value |
 | --- | --- |
 | ID | ADR-0009 |
 | CrossReference | [MIL-008], [ADR-0003], [ADR-0004], [ADR-0005], [ADR-0006] |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-13 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | pending |
 Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
 ---
 ## Context
 [ADR-0004] chose a scoped workflow to publish wikis: Gitea runs it in every
 repository of an organisation, and a marker file `wiki/.publish` is the opt-in.
 That avoids a copy of the workflow, but it runs where nobody asked for it and
 needs a safety gate for that reason; its trigger path (`wiki/**`) and the
 version of the script (`v1`) are fixed centrally. The framework now prescribes
 the wiki in `docs/wiki/` with English and the PO language as a minimum, and
 repositories need to say where their wiki is.
 Options:
 1. **Keep the scoped workflow and read both folders.** No file in consumers,
   but the central trigger lists every location and the gate stays.
 2. **A reusable workflow (`workflow_call`) that each repository calls.** One
   source in this repository, called as `uses: ...@v1` the way
   `quality-checks` and `release` already are ([ADR-0005], [ADR-0006]). The
   caller sets its own trigger paths and the folder.
 ## Decision
 Wiki publishing is the reusable workflow `publish-wiki-pages.yml`, called by
 each repository that wants a published wiki; the caller file is the opt-in and
 `docs/wiki/` is the default folder. The scoped `publish-wiki.yml` and the
 `wiki/.publish` marker are deprecated and stay until every publishing repository
 has a caller; they are then removed in a later major release.
 The rules that follow from it:
 - Inputs: `wiki_dir` (default `docs/wiki`), `prune` (default `false`) and
  `tools-ref` (default `v1`). The secret `TOKEN_FOR_GITEA_WIKI` is declared and
  passed by the caller; there is no fallback to another token.
 - With the reusable workflow the marker is not read: the script treats the
  `prune` input as the setting, and a missing folder is a configuration error
  rather than a skip, because the caller asked for it.
 - The script, the page-title rules, the empty-folder protection and the error
  categories of [ADR-0004] and [ADR-0003] are unchanged.
 ## Consequences
 **Positive:**
 - A repository states its own folder and trigger paths, so the wiki can move
  to `docs/wiki/` one repository at a time.
 - Opting in is a file in the repository, reviewed in a pull request, and a
  repository without a caller is never written to.
 - One call convention for every shared workflow of this repository.
 **Negative:**
 - Every publishing repository needs a caller file, and the removal of the
  scoped workflow stops publishing in any repository that still relies on the
  marker; the list of those repositories is taken before the removal.
 - Eight repositories still publish through the scoped workflow (checked on
  2026-10-13), so it is deprecated and not removed here; removing it is a
  breaking change under [ADR-0006] and belongs to a follow-up milestone with
  their migrations.
 - The owner chose a patch release (1.2.2) for this change although a new
  workflow is a minor one under [ADR-0006]; the changelog states the deviation.
 - Passing a declared secret through `workflow_call` is not yet verified on this
  Gitea instance; it is checked by the first call, in this repository.
 ## Affected Artifacts
 - [MIL-008] — the plan this decision belongs to.
 - [ADR-0004] — its scoped delivery and marker parts are replaced once the
  scoped workflow is removed; its token and safety rules stand.
 ---
 [MIL-008]: ../milestones/mil-008-wiki-reusable-workflow.md
 [ADR-0003]: ./adr-0003-wiki-publish-token.md
 [ADR-0004]: ./adr-0004-shared-wiki-publishing-opt-in.md
 [ADR-0006]: ./adr-0006-release-process-and-version-pinning.md
 [ADR-0005]: ./adr-0005-quality-check-contract.md
@@ -10,10 +10,10 @@ 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 | 008 |
+| MIL | Milestone / Gateway | docs/milestones/*.md | 009 |
-| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 060 |
+| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 062 |
 | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
-| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0009 |
+| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0010 |
 | UCD | Use Case Diagram | docs/use-case-diagram.md | 002 |
 | US | User Story | docs/user-stories.md | 002 |
 | UC | Use Case | docs/uc-NNN/uc.md | 008 |
@@ -0,0 +1,85 @@
 # MIL-008: Wiki publishing as a reusable workflow
 ## Metadata
 | Key | Value |
 | --- | --- |
 | ID | MIL-008 |
 | CrossReference | [BC-001], [MIL-006], [ADR-0004], [RC-060], [RC-061] |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-13 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version; reviewed (RC-060) | pending |
 | 2026-10-13 | Accepted | Jens Tirsvad Nielsen | S01 | Task 5 changed to deprecate the scoped workflow (8 repositories still use it); reviewed (RC-061) | pending |
 ---
 ## Purpose
 Decide whether the wiki can be published by a reusable workflow that each
 repository calls, from `docs/wiki/` (the location `process/wiki.md` of the
 framework prescribes), instead of a scoped workflow that runs in every
 repository of the organisation and reads `wiki/`.
 ## Deliverable
 A reusable workflow `publish-wiki-pages.yml` in `.gitea/workflows/` with a
 `wiki_dir` input, a caller template for projects, offline tests, a superseding
 ADR, updated guides and wiki pages, this repository publishing its own wiki
 from `docs/wiki/` through it, the scoped workflow marked deprecated (not
 removed), and a release that projects can pin.
 ## Go / No-Go Criteria
 | # | Criterion (objectively checkable) | Go | No-Go |
 | --- | --- | --- | --- |
 | 1 | The reusable workflow publishes the folder named by `wiki_dir` (default `docs/wiki`), and a repository that has no caller workflow is never written to | Offline tests pass; no caller means no run | Any write without a caller |
 | 2 | An empty or missing folder never deletes pages, the failure names its category, and the secret is passed explicitly (criteria 1 and 4 of MIL-006 still hold) | Existing tests pass unchanged | A regression |
 | 3 | This repository publishes its own wiki from `docs/wiki/` through a caller that uses the reusable workflow, and the pages on the host equal the folder | 0 differences read back through the API | Pages differ or the run fails |
 | 4 | A caller template exists for projects, with the trigger `docs/wiki/**` and the secret named | File exists and is linted (QC-WF-001) | Missing |
 | 5 | The scoped `publish-wiki.yml` is marked deprecated in its header, the README and ADR-0009, and the repositories that still use it are listed; it is not removed here | Notice present and the list recorded (8 repositories on 2026-10-13) | No notice, or the workflow was removed while a repository still depends on it |
 | 6 | The change is released as patch 1.2.2 and the moving major tag points at it | `v1` includes the change | Not released |
 ## Dependencies
 | Depends on | Reason |
 | --- | --- |
 | MIL-006 | The publisher script, the prune rule and the safety limits come from it |
 | `TirSystem/sqa-qc-framework` `process/wiki.md` | Defines `docs/wiki/` and the English plus PO language minimum; unmerged when this was written |
 ## Traceability
 | Business Case objective / KPI / user story | Reference |
 | --- | --- |
 | O2, O3 | [BC-001] |
 ## Ownership
 | Role | Stakeholder ID (SA) |
 | --- | --- |
 | Owner | S05 |
 | Approving reviewer | S01 |
 ## Target Date
 2026-11-15 — the Business Case sets no deadline.
 ## Tasks
 | # | Task | Summary | Needs its own Use Case/User Story? | Reference |
 | --- | --- | --- | --- | --- |
 | 1 | Record the decision | An ADR that supersedes the scoped-delivery part of ADR-0004: publishing is a reusable workflow called by each repository; the caller file is the opt-in, so `wiki/.publish` is no longer a gate; the `prune` setting becomes an input. Keep the rest of ADR-0004 (secret handling) as it stands. | No | |
 | 2 | Add the reusable workflow | `.gitea/workflows/publish-wiki-pages.yml` with `on: workflow_call`, inputs `wiki_dir` (default `docs/wiki`) and `prune`, and the token as a declared secret. It runs `tools/publish_wiki.py` with `WIKI_DIR` and the prune setting from the inputs. Update the script and its tests: the marker is no longer required. | No | |
 | 3 | Add the caller template | A `publish-wiki.yml` caller for projects (`uses: TirSystem/github-action/.gitea/workflows/publish-wiki-pages.yml@v1`, `paths: docs/wiki/**`, `secrets:` mapped). Proposed in `sqa-qc-framework` under `templates/ci/` once this is released. | No | |
 | 4 | Move this repository's wiki and call the workflow | `git mv wiki docs/wiki`, check the links and the translation hash comments, add the caller, publish, read the pages back. | No | |
 | 5 | Deprecate the scoped workflow | Do not remove it: on 2026-10-13, 8 repositories still publish through it with `wiki/.publish` (`sqa-and-qc`, `sqa-qc-framework`, `sqa-qc-checklists`, `github-action`, `repo-foundry` and three of `Tirsvad-Udemy-100-days-of-code`), and none calls the reusable workflow yet. Add a deprecation notice to its header, the README table and ADR-0009, and record the list. The migrations and the removal are a follow-up milestone after this release (ADR-0006: a removed workflow is a new major). | No | |
 | 6 | Update guides and wiki pages | Describe the caller, `docs/wiki/` and the removed marker in the onboarding and credentials guides and in the English, Danish and Bahasa Malaysia pages (rule 8 of `AGENTS.md`). | No | |
 | 7 | Release | Release as a patch, 1.2.1 to 1.2.2, as the owner instructed: changelog entry and a release through the release workflow; the `v1` tag moves with it. ADR-0006 classes a new workflow as minor, so the changelog entry states the deviation and the reason. Nothing is removed, so no consumer breaks. | No | |
 ---
 [BC-001]: ../business-case.md
 [MIL-006]: ./mil-006-shared-wiki-publishing.md
 [ADR-0004]: ../adr/adr-0004-shared-wiki-publishing-opt-in.md
 [RC-060]: ../sqa/reviews/rc-060-mil-008-plan.md
 [RC-061]: ../sqa/reviews/rc-061-mil-008-task-5-deferred.md
@@ -0,0 +1,53 @@
 # Review Record: MIL-008
 ## Metadata
 | Key | Value |
 | --- | --- |
 | ID | RC-060 |
 | CrossReference | [MIL-008], [QC-MIL-001] |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-13 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending |
 ---
 ## Artifact Under Review
 - Instance reviewed: [MIL-008]
 - Checklist used: [QC-MIL-001]
 - Scope: full review
 - Language and domain: n/a (technical type)
 - Language reviewer: none
 - Mode: supervised (S01, the user, accepted the plan in chat on 2026-10-13; the AI prepared the record)
 ## Checklist Results
 | # | Criterion | Status | Evidence/Notes |
 | --- | --- | --- | --- |
 | 1 | A concrete deliverable is defined for every gate | Pass | The Deliverable section names the reusable workflow, the caller template, tests, the superseding ADR, the moved wiki and the release. |
 | 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Six criteria, each with a checkable Go and No-Go (tests, a read-back with 0 differences, the `v1` tag). |
 | 3 | Dependencies on other milestones are explicitly mapped | Pass | MIL-006, and the framework's `process/wiki.md`, which is still unmerged and is named as such. |
 | 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | O2 and O3 of [BC-001], as for MIL-006. |
 | 5 | Milestone owner and approving reviewer are identified | Pass | Owner S05, approving reviewer S01. |
 | 6 | Milestone has a defined target date consistent with project constraints | Pass | 2026-11-15; the Business Case sets no deadline and the plan's last decision is 2026-12-26. |
 ## Overall Verdict
 Go - all six criteria pass. The release is a patch (1.2.1 to 1.2.2) by the owner's decision, although ADR-0006 classes a new workflow as minor and a removed one as breaking; task 7 records the deviation in the changelog, and S01 chose it over a minor release and over keeping the scoped workflow.
 ## Action Items
 | Action | Owner | Due |
 | --- | --- | --- |
 | Add MIL-008 to the Project Plan (milestone table, CrossReference, dependency graph) and review it | S05 | before the pull request |
 | Merge `process/wiki.md` in `sqa-qc-framework` before this repository pins it | S05 | before task 3 ships |
 | List the repositories that publish through the scoped workflow before task 5 removes it | S05 | before task 5 |
 ---
 ---
 [MIL-008]: ../../milestones/mil-008-wiki-reusable-workflow.md
 [QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
@@ -0,0 +1,53 @@
 # Review Record: MIL-008 (task 5 deferred)
 ## Metadata
 | Key | Value |
 | --- | --- |
 | ID | RC-061 |
 | CrossReference | [MIL-008], [QC-MIL-001], [RC-060] |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-13 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending |
 ---
 ## Artifact Under Review
 - Instance reviewed: [MIL-008] after the amendment of 2026-10-13: task 5 changed from removing the scoped workflow to deprecating it, with the criterion that follows from it
 - Checklist used: [QC-MIL-001]
 - Scope: delta re-review of the amended task 5, criterion 5 and the Deliverable; the earlier record is [RC-060]
 - Language and domain: n/a (technical type)
 - Language reviewer: none
 - Mode: supervised (S01, the user, chose option 1, defer the removal, in chat on 2026-10-13; the AI prepared the record)
 ## Checklist Results
 | # | Criterion | Status | Evidence/Notes |
 | --- | --- | --- | --- |
 | 1 | A concrete deliverable is defined for every gate | Pass | The Deliverable now says the scoped workflow is marked deprecated, not removed. |
 | 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Criterion 5 is checkable: a notice in the header, the README and ADR-0009, and the list of repositories recorded; No-Go if it was removed while a repository depends on it. |
 | 3 | Dependencies on other milestones are explicitly mapped | Pass | Unchanged: MIL-006 and the framework's `process/wiki.md`. |
 | 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | Unchanged: O2, O3. |
 | 5 | Milestone owner and approving reviewer are identified | Pass | Owner S05, approving reviewer S01. |
 | 6 | Milestone has a defined target date consistent with project constraints | Pass | 2026-11-15, unchanged. |
 ## Overall Verdict
 Go - all six criteria pass. The amendment follows from a scan on 2026-10-13: 8 repositories still publish through the scoped workflow and none calls the reusable one, so removal would have broken them. Removal and the migrations move to a follow-up milestone that needs its own plan.
 ## Action Items
 | Action | Owner | Due |
 | --- | --- | --- |
 | Plan the follow-up milestone: migrate the 8 repositories (move `wiki/` to `docs/wiki/`, add the caller from `templates/ci/publish-wiki.yml`), then remove the scoped workflow in a major release | S05 | after the 1.2.2 release |
 | Add MIL-008 to the Project Plan and review it (open since RC-060) | S05 | before the pull request |
 ---
 ---
 [MIL-008]: ../../milestones/mil-008-wiki-reusable-workflow.md
 [QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
 [RC-060]: ./rc-060-mil-008-plan.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], [MIL-007], [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], [RC-049], [RC-050], [RC-051], [RC-052], [RC-053], [RC-054], [RC-055], [RC-056], [RC-057], [RC-058], [RC-059], [ADR-0007], [ADR-0008], [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], [MIL-007], [MIL-008], [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], [RC-049], [RC-050], [RC-051], [RC-052], [RC-053], [RC-054], [RC-055], [RC-056], [RC-057], [RC-058], [RC-059], [RC-060], [ADR-0007], [ADR-0008], [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
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-13 | Proposed | Jens Tirsvad Nielsen | S01 | Added RC-058 (MIL-006 task 6 amendment) | [8051cc4] |
 | 2026-10-13 | Proposed | Jens Tirsvad Nielsen | S01 | Added RC-059 (MIL-007 task 7 results) | [2481c26] |
 | 2026-10-13 | Proposed | Jens Tirsvad Nielsen | S01 | Added MIL-008, RC-060 and RC-061 | pending |
 ---
@@ -40,6 +40,7 @@ updated whenever an artifact instance is created or reviewed.
 | [MIL-005] | MIL | [BC-001], [PP-001], [MIL-002] | [MIL-006] | [RC-010], [RC-011], [RC-030], [RC-050] |
 | [MIL-006] | MIL | [BC-001], [PP-001], [MIL-002], [MIL-005] | - | [RC-016], [RC-031], [RC-049], [RC-058] |
 | [MIL-007] | MIL | [BC-001], [PP-001], [MIL-003], [MIL-004], [ADR-0008] | - | [RC-052], [RC-055], [RC-059] |
 | [MIL-008] | MIL | [BC-001], [MIL-006], [ADR-0004] | - | [RC-060], [RC-061] |
 | [RC-007] | RC | [MIL-004] | - | - |
 | [RC-008] | RC | [BC-001] | - | - |
 | [RC-009] | RC | [PP-001] | - | - |
@@ -110,6 +111,8 @@ updated whenever an artifact instance is created or reviewed.
 | [RC-057] | RC | [US-001] | - | - |
 | [RC-058] | RC | [MIL-006] | - | - |
 | [RC-059] | RC | [MIL-007] | - | - |
 | [RC-060] | RC | [MIL-008] | - | - |
 | [RC-061] | RC | [MIL-008] | - | - |
 ## Coverage Notes
@@ -130,6 +133,7 @@ updated whenever an artifact instance is created or reviewed.
 [MIL-005]: ../milestones/mil-005-wiki-and-translations.md
 [MIL-006]: ../milestones/mil-006-shared-wiki-publishing.md
 [MIL-007]: ../milestones/mil-007-cpp-csharp-quality-checks.md
 [MIL-008]: ../milestones/mil-008-wiki-reusable-workflow.md
 [RC-001]: ./reviews/rc-001-business-case.md
 [RC-002]: ./reviews/rc-002-project-plan.md
 [RC-003]: ./reviews/rc-003-mil-001.md
@@ -199,6 +203,8 @@ updated whenever an artifact instance is created or reviewed.
 [RC-057]: ./reviews/rc-057-us-001-cpp-csharp.md
 [RC-058]: ./reviews/rc-058-mil-006-task-6.md
 [RC-059]: ./reviews/rc-059-mil-007-adoption.md
 [RC-060]: ./reviews/rc-060-mil-008-plan.md
 [RC-061]: ./reviews/rc-061-mil-008-task-5-deferred.md
 [ADR-0008]: ../adr/adr-0008-cpp-csharp-quality-check-contract.md
 [ADR-0007]: ../adr/adr-0007-release-publish-destination.md
 [UC-007]: ../uc-007/uc.md
@@ -208,5 +214,4 @@ updated whenever an artifact instance is created or reviewed.
 [ADR-0005]: ../adr/adr-0005-quality-check-contract.md
 [faf13b2]: https://git.tirsystem.com/TirSystem/github-action/commit/faf13b2c2a4901c0171977de1ffc2841023f537a
 [1bc56f8]: https://git.tirsystem.com/TirSystem/github-action/commit/1bc56f8b771531f221f218fc00b147ecc73c051e
 [8051cc4]: https://git.tirsystem.com/TirSystem/github-action/commit/8051cc4489ee9bcf3b6c62f2eafcb2013b7d2f90
 [2481c26]: https://git.tirsystem.com/TirSystem/github-action/commit/2481c26d802464decd51d75539157093b60e08e8