From d0618d929f2ec274d30b10bb1be306e1f04c31ee Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Sat, 10 Oct 2026 09:19:41 +0800 Subject: [PATCH 1/2] Review and accept ADR-0001 (RC-012) Add review record RC-012, accept the ADR with the decision stated in two sentences and update TM-001. --- .../adr-0001-wiki-structure-and-languages.md | 29 ++++++----- docs/artifact-registry.md | 2 +- docs/sqa/reviews/rc-012-adr-0001.md | 50 +++++++++++++++++++ docs/sqa/traceability-matrix.md | 13 +++-- 4 files changed, 76 insertions(+), 18 deletions(-) create mode 100644 docs/sqa/reviews/rc-012-adr-0001.md diff --git a/docs/adr/adr-0001-wiki-structure-and-languages.md b/docs/adr/adr-0001-wiki-structure-and-languages.md index e527893..e326c56 100644 --- a/docs/adr/adr-0001-wiki-structure-and-languages.md +++ b/docs/adr/adr-0001-wiki-structure-and-languages.md @@ -9,7 +9,8 @@ ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-10 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | [f5fb023] | +| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | [f5fb023] | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Reviewed (RC-012): decision stated in two sentences, rules moved below it | pending | Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`. @@ -55,18 +56,22 @@ Options for the source of truth of a translation: ## Decision -The wiki has five pages (Home, Onboarding, Credentials, Troubleshooting, -Capabilities). The English page has no suffix and is generated; a translation -is the page name plus `.da` or `.ms` (`Home.da`, `Credentials.ms`), written by -hand in `wiki/..md`, reviewed by a native reader, and published by -the same workflow. English is authoritative. +A translation is named `.da` or `.ms`, written by hand in +`wiki/..md`, reviewed by a native reader and checked against a +recorded hash of the English page. The English page has no suffix, is +generated, and stays authoritative. -Each translation starts with the comment -``, -so a check can report a translation whose English source has changed. Code -blocks, commands, file names and the workflow's error messages stay in -English. Terms are kept consistent through a term list (`docs/wiki-terms.md`, -created in MIL-005 task 4). +The rules that follow from it: + +- The wiki has five pages: Home, Onboarding, Credentials, Troubleshooting and + Capabilities, each also as `.da` and `.ms` (15 files in `wiki/`). +- Each translation starts with the comment + ``, + so a check can report a translation whose English source has changed. +- Code blocks, commands, file names and the workflows' error messages stay in + English. +- Terms are kept consistent through a term list (`docs/wiki-terms.md`, created + in MIL-005 task 4). ## Consequences diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index f0133c9..fb5128c 100644 --- a/docs/artifact-registry.md +++ b/docs/artifact-registry.md @@ -11,7 +11,7 @@ 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 | 006 | -| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 012 | +| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 013 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | | ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0002 | diff --git a/docs/sqa/reviews/rc-012-adr-0001.md b/docs/sqa/reviews/rc-012-adr-0001.md new file mode 100644 index 0000000..80465bc --- /dev/null +++ b/docs/sqa/reviews/rc-012-adr-0001.md @@ -0,0 +1,50 @@ +# Review Record: ADR-0001 Wiki structure, page names and languages + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-012 | +| CrossReference | [ADR-0001], [QC-ADR-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Artifact Under Review + +- Instance reviewed: [ADR-0001] +- 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-0001 in `adr-0001-wiki-structure-and-languages.md`; the first ADR. | +| 2 | Context states the problem, the forces (cost, risk, constraints) and the options evaluated | Pass | Names the three things to fix, the forces and the options. | +| 3 | At least two options were considered, or the absence of alternatives is justified | Pass | Three naming options and two source-of-truth options. | +| 4 | Decision is stated in one or two unhedged sentences and matches one of the evaluated options | Pass | Finding fixed during this review: the decision ran to several sentences. It is now two sentences (naming option 1, source option 2), and the details are listed under it as rules. | +| 5 | Consequences list both Positive and Negative outcomes | Pass | Three positive and three negative. | +| 6 | Quality-attribute impacts (performance, security, portability, etc.) are named where the decision affects them | Pass | Maintainability is the affected attribute and is named: stale translations are detectable but not self-updating. Performance and security are not affected. | +| 7 | Affected Artifacts are listed as links, and each is also in CrossReference | Pass | MIL-005 and BC-001 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 | Nothing is superseded. | +| 10 | Written in business or technical language of the domain, with no unexplained abbreviations | Pass | IT Professional English; `da`, `ms` and `sha256` are explained in the text. | +| 11 | Status is one of `Proposed`, `Accepted`, `Rejected`, `Deprecated` or `Superseded by ADR-NNNN`, and every Version History row uses only these | Pass | Rows use 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. The author and S01 are the same person, so the independent S05 review recorded in RC-001 is still open. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| Publish and open a page with a dot in its name (`Home.da`) on the wiki; if Gitea rejects it, supersede this ADR with the `Home_da` form (MIL-005 task 7) | S05 | 2026-12-12 | + +--- + +[ADR-0001]: ../../adr/adr-0001-wiki-structure-and-languages.md +[QC-ADR-001]: ../../../framework/qc/qc-adr.md diff --git a/docs/sqa/traceability-matrix.md b/docs/sqa/traceability-matrix.md index 44eba89..bdf3c3a 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], [RC-001], [RC-002], [RC-003], [RC-004], [RC-005], [RC-006], [RC-007], [RC-008], [RC-009], [RC-010], [RC-011] | +| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [RC-001], [RC-002], [RC-003], [RC-004], [RC-005], [RC-006], [RC-007], [RC-008], [RC-009], [RC-010], [RC-011], [RC-012], [ADR-0001] | ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added MIL-005 and RC-008 to RC-010 | [ae4e257] | -| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added RC-011 for the MIL-005 amendment | [20361e8] | +| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added RC-011 for the MIL-005 amendment | [20361e8] | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added ADR-0001 and RC-012 | pending | --- @@ -42,12 +42,14 @@ updated whenever an artifact instance is created or reviewed. | [RC-008] | RC | [BC-001] | - | - | | [RC-009] | RC | [PP-001] | - | - | | [RC-010] | RC | [MIL-005] | - | - | +| [ADR-0001] | ADR | [BC-001], [MIL-005] | - | [RC-012] | | [RC-011] | RC | [MIL-005] | - | - | +| [RC-012] | RC | [ADR-0001] | - | - | ## Coverage Notes - `-` in Upstream means foundational (SA-001 has no prerequisite). In Downstream it means nothing is built on the instance yet. In Last Reviewed it means no `RC-*` exists (review records are not themselves reviewed). -- Types with no instance yet: KPI, BMC, BPMN, UCD, US, UC, SSD, DM, OC, SD, DCD, ERD, ADR, GOV, DICT. The Project Plan lists use case candidates, but the formal use cases wait for a use case diagram and user stories. +- Types with no instance yet: KPI, BMC, BPMN, UCD, US, UC, SSD, DM, OC, SD, DCD, ERD, GOV, DICT. The Project Plan lists use case candidates, but the formal use cases wait for a use case diagram and user stories. - PP-001 and TM-001 have no QC checklist; RC-002 validated PP-001 against its Business Case constraints and the milestone Go / No-Go criteria. TM-001 has no review record. - All review records are `Accepted` after S01 stood in for S05 on 2026-10-10. The author and S01 are the same person, so an independent review by S05 is still open (see RC-001). @@ -72,5 +74,6 @@ updated whenever an artifact instance is created or reviewed. [RC-009]: ./reviews/rc-009-project-plan-mil-005.md [RC-010]: ./reviews/rc-010-mil-005.md [RC-011]: ./reviews/rc-011-mil-005-wiki-publishing.md -[ae4e257]: https://git.tirsystem.com/TirSystem/github-action/commit/ae4e257236095e76132980fad1e9a661b1d082c7 +[RC-012]: ./reviews/rc-012-adr-0001.md +[ADR-0001]: ../adr/adr-0001-wiki-structure-and-languages.md [20361e8]: https://git.tirsystem.com/TirSystem/github-action/commit/20361e881ebd0dc52e1d1c358ceb792c41b76c60 -- 2.54.0 From cf312382712ba229fde8736f39cc6e43d08839bc Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Sat, 10 Oct 2026 09:19:43 +0800 Subject: [PATCH 2/2] Resolve pending commit links in ADR-0001, RC-012 and TM-001 --- docs/adr/adr-0001-wiki-structure-and-languages.md | 3 ++- docs/sqa/reviews/rc-012-adr-0001.md | 3 ++- docs/sqa/traceability-matrix.md | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/adr/adr-0001-wiki-structure-and-languages.md b/docs/adr/adr-0001-wiki-structure-and-languages.md index e326c56..113f8f8 100644 --- a/docs/adr/adr-0001-wiki-structure-and-languages.md +++ b/docs/adr/adr-0001-wiki-structure-and-languages.md @@ -10,7 +10,7 @@ | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | | 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | [f5fb023] | -| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Reviewed (RC-012): decision stated in two sentences, rules moved below it | pending | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Reviewed (RC-012): decision stated in two sentences, rules moved below it | [d0618d9] | Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`. @@ -103,3 +103,4 @@ The rules that follow from it: [MIL-005]: ../milestones/mil-005-wiki-and-translations.md [BC-001]: ../business-case.md [f5fb023]: https://git.tirsystem.com/TirSystem/github-action/commit/f5fb0238f36cbb98de482c68842fc60c7ce959e2 +[d0618d9]: https://git.tirsystem.com/TirSystem/github-action/commit/d0618d929f2ec274d30b10bb1be306e1f04c31ee diff --git a/docs/sqa/reviews/rc-012-adr-0001.md b/docs/sqa/reviews/rc-012-adr-0001.md index 80465bc..b9bd43a 100644 --- a/docs/sqa/reviews/rc-012-adr-0001.md +++ b/docs/sqa/reviews/rc-012-adr-0001.md @@ -9,7 +9,7 @@ ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | [d0618d9] | --- @@ -48,3 +48,4 @@ Go - all applicable criteria pass; the one finding (criterion 4) was fixed durin [ADR-0001]: ../../adr/adr-0001-wiki-structure-and-languages.md [QC-ADR-001]: ../../../framework/qc/qc-adr.md +[d0618d9]: https://git.tirsystem.com/TirSystem/github-action/commit/d0618d929f2ec274d30b10bb1be306e1f04c31ee diff --git a/docs/sqa/traceability-matrix.md b/docs/sqa/traceability-matrix.md index bdf3c3a..38efc54 100644 --- a/docs/sqa/traceability-matrix.md +++ b/docs/sqa/traceability-matrix.md @@ -10,7 +10,7 @@ | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | | 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added RC-011 for the MIL-005 amendment | [20361e8] | -| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added ADR-0001 and RC-012 | pending | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added ADR-0001 and RC-012 | [d0618d9] | --- @@ -77,3 +77,4 @@ updated whenever an artifact instance is created or reviewed. [RC-012]: ./reviews/rc-012-adr-0001.md [ADR-0001]: ../adr/adr-0001-wiki-structure-and-languages.md [20361e8]: https://git.tirsystem.com/TirSystem/github-action/commit/20361e881ebd0dc52e1d1c358ceb792c41b76c60 +[d0618d9]: https://git.tirsystem.com/TirSystem/github-action/commit/d0618d929f2ec274d30b10bb1be306e1f04c31ee -- 2.54.0