diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index 1b5d11a..1d97d94 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 | 006 | +| MIL | Milestone / Gateway | docs/milestones/*.md | 007 | | RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 016 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | | ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0004 | diff --git a/docs/milestones/mil-006-shared-wiki-publishing.md b/docs/milestones/mil-006-shared-wiki-publishing.md new file mode 100644 index 0000000..1057cf5 --- /dev/null +++ b/docs/milestones/mil-006-shared-wiki-publishing.md @@ -0,0 +1,77 @@ +# MIL-006: Shared wiki publishing + +## Metadata +| Key | Value | +| --- | --- | +| ID | MIL-006 | +| CrossReference | [BC-001], [MIL-005], [ADR-0003] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-10 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | [6b8e36d] | + +--- + +## Purpose + +Decide whether any repository on the instance can publish its own wiki from a +`wiki/` folder through one shared workflow, without a copy of the workflow and +without risk to repositories that did not ask for it. + +## Deliverable + +A scoped workflow `publish-wiki.yml` in `.gitea/scoped_workflows/` with its +publish script embedded, an opt-in rule that leaves every repository without +it untouched, offline tests, updated guides and wiki pages, and one +repository other than this one that publishes its wiki through it. + +## Go / No-Go Criteria + +| # | Criterion (objectively checkable) | Go | No-Go | +| --- | --- | --- | --- | +| 1 | A repository without the opt-in marker is never written to, shown by offline tests and by a run in one such repository | No request writes to its wiki | Any write | +| 2 | The workflow exists once: the copy in `.gitea/workflows/` is removed and no script is needed from `tools/` | Count is 1 | A second copy exists | +| 3 | One repository outside this one publishes its wiki through the shared workflow | Pages on the wiki equal its `wiki/` | Pages differ or run fails | +| 4 | An empty or missing `wiki/` never deletes pages, and a failure names its category | Verified by tests | A wiki was emptied | +| 5 | The per-organisation secret `TOKEN_FOR_GITEA_WIKI` is documented, and stored in the pilot's organisation | Documented and stored | Missing | +| 6 | The onboarding and credentials guides and their three wiki languages describe opting in | Pages updated | Out of date | + +## Dependencies + +| Depends on | Reason | +| --- | --- | +| MIL-005 | The publisher, the page layout and the wiki rules come from it | +| MIL-002 | Scoped delivery across organisations was verified there (issue #9) | + +## 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-12-26 — proposed; to be confirmed by S01 and S05 (the Business Case sets no deadline). + +## Tasks + +| # | Task | Summary | Needs its own Use Case/User Story? | Reference | +| --- | --- | --- | --- | --- | +| 1 | Decide the opt-in rule and the secret handling | A scoped workflow runs in every repository of an organisation, and the publisher deletes pages that are not in `wiki/`. Choose how a repository opts in (a marker file such as `wiki/.publish`, a repository variable, or an allow list), what happens when the secret is missing, and whether the pilot uses `TOKEN_FOR_GITEA_WIKI` or the fallback. Record it as an ADR that refines ADR-0003. | No | | +| 2 | Make the publisher a scoped workflow | Embed the publish script in `.gitea/scoped_workflows/publish-wiki.yml` as the metadata sync does, so it needs nothing from `tools/` in the target repository, and run it only on a change under `wiki/`. Remove `.gitea/workflows/publish-wiki.yml` and `tools/publish_wiki.py` so the workflow has one source, and keep this repository's drift check in the validation tests. | No | | +| 3 | Implement the opt-in gate and the safety limits | Skip, successfully and with a log line, any repository that has not opted in. Keep the refusal on an empty `wiki/` and the categorised errors, and add offline tests with a fake Gitea for opted-in, not opted-in and missing-secret runs. | No | | +| 4 | Pilot in one other repository | Choose one repository outside this one, add a `wiki/` folder with the marker, store `TOKEN_FOR_GITEA_WIKI` in its organisation (S03), publish, and read the pages back. Also confirm that a repository without the marker was not touched. | No | | +| 5 | Update the guides and the wiki | Describe how a repository opts in and which secrets its organisation needs in the onboarding and credentials guides, regenerate the wiki pages and update the Danish and Bahasa Malaysia translations (rule 8 of `AGENTS.md`). | No | | + +--- + +[BC-001]: ../business-case.md +[6b8e36d]: https://git.tirsystem.com/TirSystem/github-action/commit/6b8e36d67ac9af165b180bc0045289e41cfd1fc3 diff --git a/docs/project-plan.md b/docs/project-plan.md index 0d479ef..cad7bb0 100644 --- a/docs/project-plan.md +++ b/docs/project-plan.md @@ -4,25 +4,25 @@ | Key | Value | | --- | --- | | ID | PP-001 | -| CrossReference | [BC-001], [SA-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005] | +| CrossReference | [BC-001], [SA-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006] | ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | UC candidate 2 names the secret PAT_FOR_GITHUB | [a26a491] | | 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Reviewed (RC-015): JSON removed from the credential failures, answered MIL-001 decisions removed from Open Issues | [b282e10] | +| 2026-10-10 | Proposed | Jens Tirsvad Nielsen | S01 | Added gateway MIL-006 (shared wiki publishing) | [6b8e36d] | --- ## Purpose -This plan schedules five milestones that move the repository from one +This plan schedules six milestones that move the repository from one workflow with known defects to a documented, versioned collection of shared workflows. The Business Case sets no deadline, so the dates are proposals. ## Planning Assumptions -- Week 1 starts 2026-10-05; phases are two weeks long; the last decision is 2026-12-12. +- Week 1 starts 2026-10-05; phases are two weeks long; the last decision is 2026-12-26. - Work on a milestone starts only after its `MIL-*` document is `Accepted`. - Dates are proposed by the author and need confirmation by S01 and S05. @@ -35,6 +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 | ```plantuml @startgantt @@ -49,6 +50,8 @@ Project starts 2026-10-05 [MIL-004 Go/No-Go] happens 2026-11-28 [MIL-005 Wiki] starts 2026-11-30 and ends 2026-12-12 [MIL-005 Go/No-Go] happens 2026-12-12 +[MIL-006 Shared wiki] starts 2026-12-14 and ends 2026-12-26 +[MIL-006 Go/No-Go] happens 2026-12-26 @endgantt ``` @@ -61,12 +64,13 @@ Project starts 2026-10-05 | Gitea Actions workflows for software engineers (quality checks) | [MIL-003] | | Gitea Actions workflows for software engineers (release and publishing) | [MIL-004] | | Wiki pages in English, Danish and Bahasa Malaysia | [MIL-005] | +| The wiki publisher shared with other repositories through scoped delivery | [MIL-006] | ## Dependencies ``` MIL-001 → MIL-002 → MIL-003 → MIL-004 - MIL-002 → MIL-005 + MIL-002 → MIL-005 → MIL-006 ``` A No-Go moves every later window by the rework time of the failed milestone. @@ -245,10 +249,11 @@ no tests, no release process. [MIL-003]: ./milestones/mil-003-quality-checks.md [MIL-004]: ./milestones/mil-004-versioned-release.md [MIL-005]: ./milestones/mil-005-wiki-and-translations.md +[MIL-006]: ./milestones/mil-006-shared-wiki-publishing.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 [Milestone MIL-004]: https://git.tirsystem.com/TirSystem/github-action/milestone/21 [Milestone MIL-005]: https://git.tirsystem.com/TirSystem/github-action/milestone/93 -[a26a491]: https://git.tirsystem.com/TirSystem/github-action/commit/a26a49173718b89785ea4a6e4c8bdbfb9aca975d [b282e10]: https://git.tirsystem.com/TirSystem/github-action/commit/b282e107416a890d6df27e6bdf23ab8a65e17123 +[6b8e36d]: https://git.tirsystem.com/TirSystem/github-action/commit/6b8e36d67ac9af165b180bc0045289e41cfd1fc3