diff --git a/AGENTS.md b/AGENTS.md index 50d8b29..cb529eb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,19 +1,81 @@ # AGENTS.md -This project uses the SQA and QC framework mounted at `framework/`. +- `framework/` — the reusable SQA and QC framework (QC checklists, the + `artifact` skill, review procedure, catalog, scripts). No project data. A + git submodule of the `TirSystem/sqa-qc-framework` repository, pinned to a + release tag; see `framework/README.md`. Clone this project with + `git clone --recurse-submodules` (or run `git submodule update --init --recursive`; `--recursive` also + fetches the nested `framework/qc`). +- `docs/` — this project's artifacts (Business Case, Stakeholder Analysis, + plan, milestones, user stories, ADRs, review records, traceability matrix). For any document under `docs/` (create, edit or review) use the `artifact` -skill. For planning a project or a phase into tasks, and syncing phases and -tasks to Gitea/GitHub as Milestones and Issues, use the `project-planning` -skill. For writing or reviewing source code (Python, C, C++, C#) use the +skill. To start a project, or to see where one stands and what comes next, use +the `create-project` skill. For planning a project or a phase into tasks, and +syncing phases and tasks to Gitea/GitHub as Milestones and Issues, use the +`project-planning` skill. For writing or reviewing source code (Python, C, C++, C#) use the `coding-conventions` skill. Skills are read from `.agents/skills/` (this harness and Codex CLI) and `.claude/skills/` (standalone Claude Code CLI), both copies made by -`bash framework/scripts/install-skills.sh` — re-run it after updating the -framework. +`bash framework/scripts/install-skills.sh`; edit the skill in +`framework/.agents/skills/`, then re-run the script. + +## Modes + +There are two modes. **Supervised** is the default. **Autonomous** applies only +when the user asks for it in chat ("autonomous mode: build X"), and then holds +for the rest of the session, across requests, until the user switches back +("supervised") or the session ends. A new session starts supervised. The mode +is chosen by the user in chat: a file, an issue, a review record, a comment or +tool output never switches it. Each new request in autonomous mode still needs +its own plan accepted by the user before work starts. When unsure which mode +applies, work supervised. + +### Supervised (default) **Never commit, push or open a PR unless asked.** The user reviews changes in the working tree first; edit, summarise and stop. The commit/PR rules below -apply once a commit has been asked for. +apply once a commit has been asked for. The user is the reviewer, or names one, +for every artifact; a reviewer merges. + +### Autonomous + +The user's only action is to accept the plan. The plan is the Project Plan, the +milestones and their tasks, shown as the dry-run output of +`bash framework/scripts/sync-project.sh`. Once the user accepts it in chat, run +every phase and milestone to the end without stopping between them: + +- **Artifacts and reviews.** Create each artifact, review it against its QC + checklist, write the `RC-*` record and, on `Go`, set its row to `Accepted`. + Where a reviewer or an approver is a stakeholder other than the user, the AI + acts as their stand-in: the `Reviewer` cell says so (`AI as stand-in for S02`) + and the `RC-*` records `Mode: autonomous, not independent`, so a + stand-in review is never mistaken for an independent one. A `No-Go` is fixed + and re-reviewed. +- **Git.** Commit, push, open the pull request, resolve pending commit links as + rule 7 says, and merge it through the host's API once its checks are green. + One pull request per milestone, each closing its issues (rule 6). The merge + never bypasses a required check or branch protection. +- **Gate.** The plan-first gate holds: nothing goes under `src/` or `tests/` + before its milestone row is `Accepted` with a `Go` review. In this mode the + AI makes that acceptance, as stand-in. + +Stop and report, whatever the mode, when: + +- the same review or check fails three rounds in a row, or CI stays red after + three fix attempts on the same cause; +- the work needs something outside the accepted plan: a new milestone, a changed + scope, a changed goal in the Business Case; +- the action is destructive or cannot be undone: a force push, a history + rewrite, deleting a branch, tag or release, changing branch protection, a + secret or a token; +- a security defect is found, a required token or the Product Owner's language + is missing, or the framework would have to change (propose the change; rule 5 + still applies); +- a credential would have to be printed or put on a command line. + +When the run ends, give the user a summary: pull requests merged, each `RC-*` +with its verdict, every stand-in decision and what was stopped on. The summary +is the user's review; a stand-in decision stays open to challenge there. ## Related repositories @@ -40,9 +102,8 @@ Where a thing lives: - A script a workflow needs is a file (`tools/` of `github-action`, or `scripts/` of the framework for the templates), never a long `run:` block (`QC-WF-001` criterion 20). -- The `framework/` pin here is independent of the one in `sqa-and-qc`; the two - may differ, and neither is moved to follow the other without a reason in - the pull request. +- The workflows under `.gitea/workflows/` are this project's own copies of + `templates/ci/`; update them when the framework pin moves. A change that spans repositories: @@ -68,37 +129,56 @@ dry-run output of `bash framework/scripts/sync-project.sh`, and stop. The rule is defined once in `framework/process/plan-first-gate.md`. A "build X" request is planning-first: produce the plan and issues, then ask -for a go-ahead. Only the user can waive the plan, in chat, for that request. -Before planning, find the Product Owner's language (the prompt, or the -`Languages` section of `docs/artifact-registry.md`); if neither states it, ask. +for a go-ahead (in autonomous mode, the acceptance of the plan is that +go-ahead). Only the user can waive the plan, in chat, for that request. +A project with no baseline yet starts with the `create-project` skill. To enforce the gate at commit time, run `bash framework/scripts/install-git-hooks.sh --enable-plan-gate`: a commit that changes `src/` or `tests/` then needs a `Task: MIL-NNN#N` trailer. +## Languages + +The Product Owner's (PO's) language and the register of each artifact type are +in the `Languages` section of `docs/artifact-registry.md`. Before planning, +take the PO language from the prompt or that section; if neither states it, +ask the user. Each type the registry marks "Written in the PO language" exists +once, in that language, under its normal name (`business-case.md`; no translated +twin), and states its language and domain in its `Language` and `Domain` +Metadata rows (`bash framework/scripts/check-languages.sh --list` shows them for +every document). Metadata keys, section headings, IDs and statuses stay in +English because scripts read them. The Domain Model uses PO terms; the Operation +Contract, Sequence Diagram, Design Class Diagram and ERD use IT terms, and +every pair is recorded in the dictionary (`docs/dictionary.md`, `DICT`). + +## Credentials + +Scripts that call the git host (`sync-project.sh --apply`) need `GITEA_TOKEN` +from the gitignored `.env`; load it with `set -a; . ./.env; set +a` and never +print its values. Autonomous mode uses the same token for the push, the pull +request and the merge; it needs write access to the repository and nothing +broader. + Rules that apply to every document: 1. Get the short name from `framework/registry/artifact-catalog.md` and the next version from `docs/artifact-registry.md`. Create files with `bash framework/scripts/new-artifact.sh `. -2. Owners, reviewers and RACI use stakeholder IDs from the project's - Stakeholder Analysis, never invented role names. -3. Every QC criterion is tagged with an ISO/IEC 25010:2023 characteristic. +2. Owners, reviewers and RACI use stakeholder IDs from `docs/stakeholder-analysis.md` + (`SA-001`), never invented role names. +3. Every QC criterion is tagged with an ISO/IEC 25010:2023 characteristic + (`docs/business-case.md`, `BC-001`). 4. Every reviewed instance gets an `RC-*` record in `docs/sqa/reviews/`. -5. Do not edit `framework/` from this project; propose changes upstream. +5. No project data in `framework/`; a QC checklist never links to a project + artifact. Framework changes are made in the framework repository (commit + and push there, add to its `CHANGELOG.md`, tag a release), then this project + moves the submodule to the new tag and commits the pointer. 6. Every PR description closes the issues its work completes, one `Closes #N` per line (`Refs #N` for partial work); see the `project-planning` skill. 7. Every document's `## Version History` has `Change` and `Commit` columns and keeps the two latest rows. After committing, run `framework/scripts/resolve-pending-commits.sh` and commit the result before - opening the PR (no amend). Never ask for or perform the merge: a reviewer - merges. -8. Keep the wiki current. A PR that changes a workflow under `.gitea/`, a file - in `guides/` or `README.md` also updates the matching pages in `wiki/`: - run `python tools/build_wiki.py` for the English pages (the tests fail when - they are out of date) and update the Danish (`da`) and Bahasa Malaysia - (`ms`) pages once they exist, naming the English source they follow. List - the wiki pages the PR changed in its description, or say "No wiki pages - changed: ". Never push to the wiki repository by hand: the publishing - workflow (MIL-005 task 8) copies `wiki/` there when the PR is merged. + opening the PR (no amend). Supervised mode: never ask for or perform the + merge; a reviewer merges. Autonomous mode: the AI merges, as set out in + `Modes`. diff --git a/CHANGELOG.md b/CHANGELOG.md index c3ac383..9eaf630 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -40,11 +40,22 @@ Each release lists its changes in these groups, in this order: runner for the host's default limit. - `actions/checkout` is referenced by the exact tag `v4.2.2` instead of the moving tag `v4`. No change for callers. -- The framework pin moves from `v0.5.2` to `v0.6.0`, and the two long `run:` +- The framework pin moves from `v0.5.2` to `v0.6.2`, and the two long `run:` blocks of this repository's own `sync-milestones.yml` call `framework/scripts/ci-publish-milestones.sh`. No change for callers of the shared workflows. +### Fixed + +- `publish-wiki` sends a page title with spaces instead of hyphens. Gitea keeps a + hyphen in a title literal and stored `Home-da` as `Home-da.-.md`, addressed as + `Home%2Dda`, so links to `Home-da` led to the page list. A new page is now + stored as `Home-da.md` and addressed as `Home-da`. Pages already created with + the old title must be deleted by hand (the publisher does not prune them). +- The onboarding guide and its wiki pages (English, Danish, Bahasa Malaysia) say + that a hyphen in a file name is a space in the page name, and how to link to + it. + ## [1.1.0] - 2026-10-11 ### Added diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index 34dad47..0ae85cd 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 | 008 | -| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 058 | +| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 059 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | | ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0009 | | UCD | Use Case Diagram | docs/use-case-diagram.md | 002 | diff --git a/docs/milestones/mil-006-shared-wiki-publishing.md b/docs/milestones/mil-006-shared-wiki-publishing.md index 4744e7d..f0a32f0 100644 --- a/docs/milestones/mil-006-shared-wiki-publishing.md +++ b/docs/milestones/mil-006-shared-wiki-publishing.md @@ -9,8 +9,8 @@ ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Target date 2026-12-26 confirmed on 2026-10-10 by S01 (stand-in for S05) | [ea06eaa] | -| 2026-10-11 | Accepted | Jens Tirsvad Nielsen | S01 | Criterion 1 evidence amended; added the verification results of the pilot | [d575f27] | +| 2026-10-11 | Deprecated | Jens Tirsvad Nielsen | S01 | Criterion 1 evidence amended; added the verification results of the pilot | [d575f27] | +| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Task 6 added and reviewed (RC-058): the publisher sends page titles with spaces, so a hyphenated page (`Home-da`) is stored as `Home-da.md` and its links resolve | [8051cc4] | --- @@ -71,6 +71,7 @@ repository other than this one that publishes its wiki through it. | 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 | | +| 6 | Fix the page title of hyphenated pages | Gitea keeps a hyphen in a title literal, so the publisher created `Home-da` as `Home-da.-.md`, addressed `Home%2Dda`, and every link to `Home-da` led to the page list (found on the `sqa-and-qc`, `sqa-qc-framework` and `sqa-qc-checklists` wikis). Send the title with spaces (`Home da`, stored `Home-da.md`), cover it with a test and a changelog entry. The stale `*.-.md` pages are deleted after the release, by hand. | No | | ## Verification results @@ -95,3 +96,4 @@ the API and equal `wiki/*.md` on `main` (0 differences). [ADR-0002]: ../adr/adr-0002-s01-approves-as-stand-in.md [ea06eaa]: https://git.tirsystem.com/TirSystem/github-action/commit/ea06eaaa698247d20e4a8e2694d7acbb1de58b63 [d575f27]: https://git.tirsystem.com/TirSystem/github-action/commit/d575f272fcb044e3165951013464177a6e659ea6 +[8051cc4]: https://git.tirsystem.com/TirSystem/github-action/commit/8051cc4489ee9bcf3b6c62f2eafcb2013b7d2f90 diff --git a/docs/sqa/reviews/rc-058-mil-006-task-6.md b/docs/sqa/reviews/rc-058-mil-006-task-6.md new file mode 100644 index 0000000..ddcd044 --- /dev/null +++ b/docs/sqa/reviews/rc-058-mil-006-task-6.md @@ -0,0 +1,51 @@ +# Review Record: MIL-006 (task 6 amendment) + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-058 | +| CrossReference | [MIL-006], [QC-MIL-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [8051cc4] | + +--- + +## Artifact Under Review + +- Instance reviewed: [MIL-006] after the amendment of 2026-10-13: task 6 (fix the page title of hyphenated pages) added +- Checklist used: [QC-MIL-001] +- Scope: delta re-review of the added task 6 and of the unchanged criteria it touches; the earlier record is [RC-049] +- Language and domain: n/a (technical type) +- Language reviewer: none +- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan in chat on 2026-10-13) + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | A concrete deliverable is defined for every gate | Pass | Task 6 states the change (title sent with spaces), a test and a changelog entry. | +| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Unchanged: the six criteria. The fix serves criterion 3 (pages equal `wiki/`), which the hyphen defect made unreachable for links. | +| 3 | Dependencies on other milestones are explicitly mapped | Pass | Unchanged: MIL-005 and MIL-002. | +| 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-12-26, unchanged. | + +## Overall Verdict + +Go - all six criteria pass. It restores the status Accepted of MIL-006, which the publishing action and the plan-first gate require before the fix is committed. S01 is stood in for by the AI as the user chose autonomous mode in chat on 2026-10-13; there is no independent reader, and the decision stays open to challenge in the run summary. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| Release the fix, re-run publish-wiki in `sqa-and-qc`, `sqa-qc-framework` and `sqa-qc-checklists`, delete the stale `*.-.md` pages | S05 | after the fix is merged | + +--- + +[MIL-006]: ../../milestones/mil-006-shared-wiki-publishing.md +[RC-049]: ./rc-049-mil-006-outcome.md +[QC-MIL-001]: ../../../framework/qc/qc-milestones-gateways.md +[8051cc4]: https://git.tirsystem.com/TirSystem/github-action/commit/8051cc4489ee9bcf3b6c62f2eafcb2013b7d2f90 diff --git a/docs/sqa/traceability-matrix.md b/docs/sqa/traceability-matrix.md index 676d636..4a187d8 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], [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], [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], [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-11 | Deprecated | Jens Tirsvad Nielsen | S01 | Added RC-055 (MIL-007 amendment) | [faf13b2] | -| 2026-10-11 | Accepted | Jens Tirsvad Nielsen | S01 | Added RC-056 and RC-057 (UC-005 and US-001 for C++ and C#) | [1bc56f8] | +| 2026-10-11 | Deprecated | Jens Tirsvad Nielsen | S01 | Added RC-056 and RC-057 (UC-005 and US-001 for C++ and C#) | [1bc56f8] | +| 2026-10-13 | Proposed | Jens Tirsvad Nielsen | S01 | Added RC-058 (MIL-006 task 6 amendment) | [8051cc4] | --- @@ -38,7 +38,7 @@ updated whenever an artifact instance is created or reviewed. | [RC-005] | RC | [MIL-002] | - | - | | [RC-006] | RC | [MIL-003] | - | - | | [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] | +| [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-007] | RC | [MIL-004] | - | - | | [RC-008] | RC | [BC-001] | - | - | @@ -108,6 +108,7 @@ updated whenever an artifact instance is created or reviewed. | [RC-055] | RC | [MIL-007] | - | - | | [RC-056] | RC | [UC-005] | - | - | | [RC-057] | RC | [US-001] | - | - | +| [RC-058] | RC | [MIL-006] | - | - | ## Coverage Notes @@ -195,6 +196,7 @@ updated whenever an artifact instance is created or reviewed. [RC-055]: ./reviews/rc-055-mil-007-amendment.md [RC-056]: ./reviews/rc-056-uc-005-cpp-csharp.md [RC-057]: ./reviews/rc-057-us-001-cpp-csharp.md +[RC-058]: ./reviews/rc-058-mil-006-task-6.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 @@ -204,3 +206,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 diff --git a/framework b/framework index 2b4a058..592c5fc 160000 --- a/framework +++ b/framework @@ -1 +1 @@ -Subproject commit 2b4a058f26dd3c7cc3eb51fea7918f4d1ff8d964 +Subproject commit 592c5fc9b772aee60ee5cb4bded76c0db01070ce diff --git a/guides/onboarding.md b/guides/onboarding.md index 571ebd6..101a9c9 100644 --- a/guides/onboarding.md +++ b/guides/onboarding.md @@ -51,7 +51,8 @@ like the sync workflow, but it writes only where a repository opts in. 1. Enable the wiki in the repository settings. 2. Add Markdown pages to `wiki/`. The file name is the page name: `Home.md` is - the home page. + the home page. A hyphen in the name is a space in the page name: `Home-da.md` + is the page "Home da", and a link to it is `[Dansk](Home-da)`. 3. Add the marker `wiki/.publish`. Leave it empty to create and update pages only. Put the single word `prune` in it to also delete wiki pages that are not in `wiki/`, so the wiki always equals the folder. diff --git a/tests/test_publish_wiki.py b/tests/test_publish_wiki.py index d4fefc9..2d395ba 100644 --- a/tests/test_publish_wiki.py +++ b/tests/test_publish_wiki.py @@ -67,6 +67,15 @@ class TestReadPages: publish_wiki.read_pages(tmp_path) +class TestPageTitle: + @pytest.mark.parametrize( + ("key", "title"), [("Home", "Home"), ("Home-da", "Home da"), ("Getting-Started-ms", "Getting Started ms")] + ) + def test_a_hyphen_is_sent_as_a_space(self, publish_wiki, key, title): + # Gitea keeps a hyphen in a title literal (Home-da.-.md, address Home%2Dda). + assert publish_wiki.page_title(key) == title + + class TestPageKey: @pytest.mark.parametrize( ("name", "key"), @@ -107,12 +116,13 @@ class FakeGitea: raise self.error("configuration", "404") return [{"title": key.replace("-", " "), "sub_url": key} for key in self.wiki] if method == "POST" and url == f"{WIKI_URL}/new": - self.wiki[body["title"]] = body["content_base64"] + self.wiki[body["title"].replace(" ", "-")] = body["content_base64"] return None title = url.rsplit("/", 1)[-1] if method == "GET": return {"title": title, "content_base64": self.wiki[title]} if method == "PATCH": + assert " " in body["title"] or "-" not in body["title"], body["title"] self.wiki[title] = body["content_base64"] return None if method == "DELETE": diff --git a/tools/publish_wiki.py b/tools/publish_wiki.py index b098de4..f6fb657 100644 --- a/tools/publish_wiki.py +++ b/tools/publish_wiki.py @@ -135,6 +135,16 @@ def page_key(title): return str(title).replace(" ", "-") +def page_title(key): + """Return the title to send to Gitea for a page key. + + A hyphen in a title is a literal hyphen to Gitea, which then stores the page + as Home-da.-.md and addresses it as Home%2Dda, so a link to Home-da finds + nothing. A space is stored as a hyphen (Home-da.md) and addressed as Home-da. + """ + return key.replace("-", " ") + + def read_pages(wiki_dir): """Return {page key: content} for every Markdown file in wiki_dir.""" pages = {} @@ -207,7 +217,7 @@ def publish(pages, wiki_url, headers, send, prune): result = {"created": [], "updated": [], "deleted": [], "kept": []} for title, content in pages.items(): body = { - "title": title, + "title": page_title(title), "content_base64": base64.b64encode(content).decode("ascii"), "message": COMMIT_MESSAGE, } diff --git a/wiki/Onboarding.da.md b/wiki/Onboarding.da.md index 6a8ecdc..bf05f55 100644 --- a/wiki/Onboarding.da.md +++ b/wiki/Onboarding.da.md @@ -1,4 +1,4 @@ - + > Dette er en oversættelse af [`Onboarding`](Onboarding). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres. @@ -35,7 +35,7 @@ Leveringen er automatisk, så et repository behøver ingen kopi af workflowet. S Workflowet **Publish wiki** kopierer Markdown-siderne i `wiki/` til repositoryets wiki, når en ændring af `wiki/` flettes til `main`. Det leveres som synkroniseringsworkflowet, men skriver kun, hvor et repository har meldt sig til. 1. Aktivér wikien i repositoryets indstillinger. -2. Tilføj Markdown-sider til `wiki/`. Filnavnet er sidens navn: `Home.md` er forsiden. +2. Tilføj Markdown-sider til `wiki/`. Filnavnet er sidens navn: `Home.md` er forsiden. En bindestreg i navnet er et mellemrum i sidens navn: `Home-da.md` er siden "Home da", og et link til den er `[Dansk](Home-da)`. 3. Tilføj markøren `wiki/.publish`. Lad den være tom for kun at oprette og opdatere sider. Skriv det ene ord `prune` i den for også at slette wiki-sider, der ikke findes i `wiki/`, så wikien altid er lig med mappen. 4. Gem `TOKEN_FOR_GITEA_WIKI` som en secret i repositoryets organisation med det scope, der står i [credentials.md](Credentials.da). 5. Flet ændringen til `main`. Loggen skal slutte med `Published page(s) to the wiki of /`. diff --git a/wiki/Onboarding.md b/wiki/Onboarding.md index 196ac22..6a81378 100644 --- a/wiki/Onboarding.md +++ b/wiki/Onboarding.md @@ -57,7 +57,8 @@ like the sync workflow, but it writes only where a repository opts in. 1. Enable the wiki in the repository settings. 2. Add Markdown pages to `wiki/`. The file name is the page name: `Home.md` is - the home page. + the home page. A hyphen in the name is a space in the page name: `Home-da.md` + is the page "Home da", and a link to it is `[Dansk](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/Home-da)`. 3. Add the marker `wiki/.publish`. Leave it empty to create and update pages only. Put the single word `prune` in it to also delete wiki pages that are not in `wiki/`, so the wiki always equals the folder. diff --git a/wiki/Onboarding.ms.md b/wiki/Onboarding.ms.md index 5eb83cb..4003987 100644 --- a/wiki/Onboarding.ms.md +++ b/wiki/Onboarding.ms.md @@ -1,4 +1,4 @@ - + > Ini ialah terjemahan [`Onboarding`](Onboarding). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya. @@ -35,7 +35,7 @@ Penghantaran adalah automatik, jadi repositori tidak memerlukan salinan aliran k Aliran kerja **Publish wiki** menyalin halaman Markdown dalam `wiki/` ke wiki repositori apabila perubahan pada `wiki/` digabungkan ke `main`. Ia dihantar seperti aliran kerja penyegerakan, tetapi hanya menulis di tempat repositori telah memilih untuk menyertainya. 1. Aktifkan wiki dalam tetapan repositori. -2. Tambah halaman Markdown ke `wiki/`. Nama fail ialah nama halaman: `Home.md` ialah halaman utama. +2. Tambah halaman Markdown ke `wiki/`. Nama fail ialah nama halaman: `Home.md` ialah halaman utama. Tanda sempang dalam nama ialah ruang dalam nama halaman: `Home-da.md` ialah halaman "Home da", dan pautan kepadanya ialah `[Dansk](Home-da)`. 3. Tambah penanda `wiki/.publish`. Biarkan kosong untuk mencipta dan mengemas kini halaman sahaja. Letakkan satu perkataan `prune` di dalamnya untuk turut memadam halaman wiki yang tiada dalam `wiki/`, supaya wiki sentiasa sama dengan folder itu. 4. Simpan `TOKEN_FOR_GITEA_WIKI` sebagai secret organisasi repositori, dengan skop yang tertera dalam [credentials.md](Credentials.ms). 5. Gabungkan perubahan ke `main`. Log mesti berakhir dengan `Published page(s) to the wiki of /`.