diff --git a/docs/adr/adr-0009-wiki-publishing-reusable-workflow.md b/docs/adr/adr-0009-wiki-publishing-reusable-workflow.md new file mode 100644 index 0000000..8b6574d --- /dev/null +++ b/docs/adr/adr-0009-wiki-publishing-reusable-workflow.md @@ -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 diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index cd4c561..5a2de19 100644 --- a/docs/artifact-registry.md +++ b/docs/artifact-registry.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 | -| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 060 | +| MIL | Milestone / Gateway | docs/milestones/*.md | 009 | +| 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 | diff --git a/docs/milestones/mil-008-wiki-reusable-workflow.md b/docs/milestones/mil-008-wiki-reusable-workflow.md new file mode 100644 index 0000000..2c900ea --- /dev/null +++ b/docs/milestones/mil-008-wiki-reusable-workflow.md @@ -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 diff --git a/docs/sqa/reviews/rc-060-mil-008-plan.md b/docs/sqa/reviews/rc-060-mil-008-plan.md new file mode 100644 index 0000000..526ec10 --- /dev/null +++ b/docs/sqa/reviews/rc-060-mil-008-plan.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 diff --git a/docs/sqa/reviews/rc-061-mil-008-task-5-deferred.md b/docs/sqa/reviews/rc-061-mil-008-task-5-deferred.md new file mode 100644 index 0000000..b9fb48a --- /dev/null +++ b/docs/sqa/reviews/rc-061-mil-008-task-5-deferred.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 diff --git a/docs/sqa/traceability-matrix.md b/docs/sqa/traceability-matrix.md index 4018571..22153d7 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], [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