diff --git a/docs/adr/adr-0004-shared-wiki-publishing-opt-in.md b/docs/adr/adr-0004-shared-wiki-publishing-opt-in.md new file mode 100644 index 0000000..c25d645 --- /dev/null +++ b/docs/adr/adr-0004-shared-wiki-publishing-opt-in.md @@ -0,0 +1,117 @@ +# ADR-0004: Opt-in rule and secret handling of the shared wiki publisher + +## Metadata +| Key | Value | +| --- | --- | +| ID | ADR-0004 | +| CrossReference | [MIL-006], [ADR-0003], [ADR-0002] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | [b22a2cd] | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Reviewed (RC-018): the `prune` variant added to the evaluated options | [b22a2cd] | + +Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`. + +--- + +## Context + +MIL-006 turns the Publish wiki workflow into a scoped workflow, which Gitea +runs in every repository of every organisation on the instance (verified, +issue #9). The publisher writes to a repository's wiki and removes pages that +are not in `wiki/`. Without a gate, any of the 26 repositories of +`Tirsvad-Udemy-100-days-of-code`, or any other repository, that happens to +have a `wiki/` folder would have its wiki overwritten or emptied by a +workflow it never asked for. The secret is also per organisation, so the +shared workflow must say what happens where it is missing, and +[ADR-0003] let this repository fall back to `TOKEN_FOR_GITEA`. + +Options for how a repository opts in: + +1. **A marker file `wiki/.publish`** on the default branch. Visible in the + repository, reviewed in a pull request, and nothing to configure in an + organisation. It comes in two forms: + - **(a) the marker alone** makes the wiki equal `wiki/`, so pages that are + not in the folder are deleted, as in ADR-0003; + - **(b) the marker plus the word `prune`** in it: without the word the + workflow only creates and updates pages, and deleting is a second, + explicit choice. +2. **A repository variable** (for example `PUBLISH_WIKI=true`). Not part of + the repository content, so it is not reviewed or versioned, and it has to + be set in the web interface once per repository. +3. **An allow list** in this repository. One place to read, but every + repository in every organisation has to ask this repository for a change. +4. **Publish whenever `wiki/` exists.** No setup, which is the risk the gate + is meant to remove. + +Option 1(b) is chosen for the reason in the first paragraph: a repository +that adds `wiki/` to a wiki it wrote by hand should not lose that wiki by +opting in. + +Options for the secret: + +1. **`TOKEN_FOR_GITEA_WIKI` of the organisation only.** The sync token stays + read-only everywhere. +2. **Fall back to `TOKEN_FOR_GITEA`** as in ADR-0003. A missing wiki secret is + hidden until a write is refused (HTTP 403). + +## Decision + +A repository opts in by committing `wiki/.publish` on its default branch; the +file may contain the single word `prune`, which is the only thing that lets the +workflow delete wiki pages that are not in `wiki/`, and without the marker the +workflow ends successfully without any request. The shared workflow uses the +organisation's `TOKEN_FOR_GITEA_WIKI` only, and fails with a configuration +error when a repository has opted in and the secret is missing. + +The rules that follow from it: + +- Without `prune` the workflow only creates and updates pages. +- An empty `wiki/` (no Markdown page) never deletes anything, with or without + `prune`. +- A repository that has not opted in is skipped with one log line, so its + runs stay green. +- This repository commits `wiki/.publish` containing `prune`, because its wiki + must equal `wiki/` (ADR-0001, ADR-0003). +- The fallback to `TOKEN_FOR_GITEA` of ADR-0003 is removed from the shared + workflow; the sync token is read-only everywhere. + +## Consequences + +**Positive:** + +- A repository that did not opt in is never written to, and the marker is a + reviewed change in the repository that wants it. +- Deleting pages is a second, explicit choice, so adopting the workflow in a + repository with hand-written wiki pages loses nothing. +- A missing wiki secret is reported where it happens, in the repository that + opted in, and the sync token never gets write access. + +**Negative:** + +- Each organisation that wants this needs its own `TOKEN_FOR_GITEA_WIKI`; it + cannot borrow the sync token. +- A repository that opts in without `prune` keeps pages that were removed from + `wiki/`, so its wiki can drift from the folder until someone adds `prune`. +- Anyone with write access to a repository can opt it in and, with `prune`, + make the workflow delete its wiki pages; that is the intended scope of write + access, but it is not a separate approval. +- The change supersedes the fallback part of [ADR-0003], so the credentials + guide and the wiki pages that mention it need an update (MIL-006 task 5). + +## Affected Artifacts + +- [MIL-006] — tasks 2, 3 and 4 (issues #57 to #59) implement and pilot this + decision. +- [ADR-0003] — its fallback to `TOKEN_FOR_GITEA` no longer applies to the + shared workflow. +- [ADR-0002] — the stand-in rule applies to the review of this ADR. + +--- + +[MIL-006]: ../milestones/mil-006-shared-wiki-publishing.md +[ADR-0003]: ./adr-0003-wiki-publish-token.md +[ADR-0002]: ./adr-0002-s01-approves-as-stand-in.md +[b22a2cd]: https://git.tirsystem.com/TirSystem/github-action/commit/b22a2cd59235078656c4440b945b787f88fbd345 diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index 9a11c57..d77b2dd 100644 --- a/docs/artifact-registry.md +++ b/docs/artifact-registry.md @@ -11,9 +11,9 @@ each document lives in *this* project and the next version to use. | SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 | | PP | Project Plan | docs/project-plan.md | 002 | | MIL | Milestone / Gateway | docs/milestones/*.md | 007 | -| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 018 | +| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 019 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | -| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0004 | +| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0005 | ## Languages diff --git a/docs/project-plan.md b/docs/project-plan.md index aec9612..6826fb9 100644 --- a/docs/project-plan.md +++ b/docs/project-plan.md @@ -35,7 +35,7 @@ workflows. The Business Case sets no deadline, so the dates are proposals. | Shared quality checks | [MIL-003] | 2026-11-02 to 2026-11-14 | 2026-11-14 | S05 | None yet | Reusable quality-check workflow | [Milestone MIL-003] | | Versioned release and publishing | [MIL-004] | 2026-11-16 to 2026-11-28 | 2026-11-28 | S05 | None yet | Release process and reusable release workflow | [Milestone MIL-004] | | Wiki and translations | [MIL-005] | 2026-11-30 to 2026-12-12 | 2026-12-12 | S05 | None yet | Wiki pages in English, Danish and Bahasa Malaysia, kept current by every pull request | [Milestone MIL-005] | -| Shared wiki publishing | [MIL-006] | 2026-12-14 to 2026-12-26 | 2026-12-26 | S05 | None yet | Scoped publish-wiki workflow with opt-in, piloted in one other repository | Not created yet | +| Shared wiki publishing | [MIL-006] | 2026-12-14 to 2026-12-26 | 2026-12-26 | S05 | None yet | Scoped publish-wiki workflow with opt-in, piloted in one other repository | [Milestone MIL-006] | ```plantuml @startgantt @@ -255,5 +255,6 @@ no tests, no release process. [Milestone MIL-003]: https://git.tirsystem.com/TirSystem/github-action/milestone/20 [Milestone MIL-004]: https://git.tirsystem.com/TirSystem/github-action/milestone/21 [Milestone MIL-005]: https://git.tirsystem.com/TirSystem/github-action/milestone/93 +[Milestone MIL-006]: https://git.tirsystem.com/TirSystem/github-action/milestone/94 [b282e10]: https://git.tirsystem.com/TirSystem/github-action/commit/b282e107416a890d6df27e6bdf23ab8a65e17123 [6b8e36d]: https://git.tirsystem.com/TirSystem/github-action/commit/6b8e36d67ac9af165b180bc0045289e41cfd1fc3 diff --git a/docs/sqa/reviews/rc-018-adr-0004.md b/docs/sqa/reviews/rc-018-adr-0004.md new file mode 100644 index 0000000..98156cf --- /dev/null +++ b/docs/sqa/reviews/rc-018-adr-0004.md @@ -0,0 +1,52 @@ +# Review Record: ADR-0004 Opt-in rule and secret handling of the shared wiki publisher + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-018 | +| CrossReference | [ADR-0004], [QC-ADR-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | [b22a2cd] | + +--- + +## Artifact Under Review + +- Instance reviewed: [ADR-0004] +- Checklist used: [QC-ADR-001] + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | The ID (`ADR-NNNN`, 4-digit) matches the filename number and is unique and sequential | Pass | ADR-0004 in `adr-0004-shared-wiki-publishing-opt-in.md`; follows ADR-0003. | +| 2 | Context states the problem, the forces (cost, risk, constraints) and the options evaluated | Pass | States the scoped delivery, the deletion risk, the per-organisation secret and the fallback. | +| 3 | At least two options were considered, or the absence of alternatives is justified | Pass | Four options for opting in (one with two forms) and two for the secret. | +| 4 | Decision is stated in one or two unhedged sentences and matches one of the evaluated options | Pass | Finding fixed during this review: the `prune` form was not among the evaluated options. It is now option 1(b), with the reason. The decision is two sentences. | +| 5 | Consequences list both Positive and Negative outcomes | Pass | Three positive, four negative. | +| 6 | Quality-attribute impacts (performance, security, portability, etc.) are named where the decision affects them | Pass | Security is named: no write without opt-in, no write access for the sync token, write access of anyone with repository write rights. | +| 7 | Affected Artifacts are listed as links, and each is also in CrossReference | Pass | MIL-006, ADR-0003 and ADR-0002 are linked and cited. | +| 8 | Status changes are recorded as new Version History rows with a Change summary and Commit link; retained rows are never rewritten | Pass | The earlier row is kept and only its status changed. | +| 9 | A superseded or deprecated ADR names its successor, and the successor links back | N-A | ADR-0003 is superseded only in part and stays in force for this repository's local workflow until MIL-006 task 2 lands; see the action item. | +| 10 | Written in business or technical language of the domain, with no unexplained abbreviations | Pass | IT Professional English; `prune` and the marker are explained where they are introduced. | +| 11 | Status is one of `Proposed`, `Accepted`, `Rejected`, `Deprecated` or `Superseded by ADR-NNNN`, and every Version History row uses only these | Pass | Deprecated and Accepted only. | + +## Overall Verdict + +Go - all applicable criteria pass; the one finding (criterion 4) was fixed during the review. S01 gave the Go in chat on 2026-10-10, standing in for the other reviewers as ADR-0002 records; there is no independent reader. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| When MIL-006 task 2 (#57) merges, mark ADR-0003 as superseded by ADR-0004 for the shared workflow (new version row and review record) | S01 | 2026-12-26 | +| Choose the pilot repository (MIL-006 task 4, already an action item in RC-016) | S01 | 2026-12-14 | + +--- + +[ADR-0004]: ../../adr/adr-0004-shared-wiki-publishing-opt-in.md +[QC-ADR-001]: ../../../framework/qc/qc-adr.md +[b22a2cd]: https://git.tirsystem.com/TirSystem/github-action/commit/b22a2cd59235078656c4440b945b787f88fbd345 diff --git a/docs/sqa/traceability-matrix.md b/docs/sqa/traceability-matrix.md index 7d4cd7b..1c2dfba 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], [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], [ADR-0001], [ADR-0002], [ADR-0003] | +| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [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], [ADR-0001], [ADR-0002], [ADR-0003], [ADR-0004] | ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added MIL-006 and RC-016 | [676a262] | -| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added RC-017 for PP-001 | [676a262] | +| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added RC-017 for PP-001 | [676a262] | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added ADR-0004 and RC-018 | [b22a2cd] | --- @@ -45,7 +45,8 @@ updated whenever an artifact instance is created or reviewed. | [RC-010] | RC | [MIL-005] | - | - | | [ADR-0001] | ADR | [BC-001], [MIL-005] | [ADR-0003] | [RC-012] | | [ADR-0002] | ADR | [SA-001], [RC-001] | - | [RC-013] | -| [ADR-0003] | ADR | [MIL-005], [ADR-0001], [RC-011] | - | [RC-014] | +| [ADR-0003] | ADR | [MIL-005], [ADR-0001], [RC-011] | [ADR-0004] | [RC-014] | +| [ADR-0004] | ADR | [MIL-006], [ADR-0003], [ADR-0002] | - | [RC-018] | | [RC-011] | RC | [MIL-005] | - | - | | [RC-012] | RC | [ADR-0001] | - | - | | [RC-013] | RC | [ADR-0002] | - | - | @@ -53,6 +54,7 @@ updated whenever an artifact instance is created or reviewed. | [RC-015] | RC | [PP-001] | - | - | | [RC-016] | RC | [MIL-006] | - | - | | [RC-017] | RC | [PP-001] | - | - | +| [RC-018] | RC | [ADR-0004] | - | - | ## Coverage Notes @@ -87,9 +89,12 @@ updated whenever an artifact instance is created or reviewed. [ADR-0001]: ../adr/adr-0001-wiki-structure-and-languages.md [ADR-0002]: ../adr/adr-0002-s01-approves-as-stand-in.md [ADR-0003]: ../adr/adr-0003-wiki-publish-token.md +[ADR-0004]: ../adr/adr-0004-shared-wiki-publishing-opt-in.md [RC-013]: ./reviews/rc-013-adr-0002.md [RC-014]: ./reviews/rc-014-adr-0003.md [RC-015]: ./reviews/rc-015-project-plan-pat.md [RC-016]: ./reviews/rc-016-mil-006.md [RC-017]: ./reviews/rc-017-project-plan-mil-006.md +[RC-018]: ./reviews/rc-018-adr-0004.md [676a262]: https://git.tirsystem.com/TirSystem/github-action/commit/676a26240563338307c0454c3bf15b960bdb58ca +[b22a2cd]: https://git.tirsystem.com/TirSystem/github-action/commit/b22a2cd59235078656c4440b945b787f88fbd345