TirSystem/git-workflows
0
2
Fork 0
Code Issues 40 Pull Requests Actions Packages Projects Releases 11 Wiki Activity

Scoped wiki publishing (MIL-014) and rename to git-workflows (MIL-015) #219

Merged
Tirsvad merged 13 commits from mil-014-scoped-wiki-publishing into main 2026-10-27 16:34:30 +01:00
Conversation 0 Commits 13 Files Changed 41
+908 -615
41 changed files with 908 additions and 615 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitea/scoped_workflows/publish-wiki-pages.yml
+52
View File
@@ -0,0 +1,52 @@
name: Publish wiki
# Scoped workflow: it runs in every repository of an organization, so there is
# no caller and no input. A repository opts in by having a docs/wiki folder; a
# repository without one is skipped. It publishes the Markdown pages of
# docs/wiki to the wiki of the repository, creating and updating pages and
# keeping the pages that are not in the folder. The script is a file of
# TirSystem/git-workflows (tools/publish_wiki.py), fetched at v2.
on:
push:
branches: [ main ]
paths:
- "docs/wiki/**"
workflow_dispatch:
jobs:
publish-wiki:
permissions:
contents: read
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Check out the repository
uses: actions/checkout@v4.2.2
- name: Look for the wiki folder
id: source
run: |
if [ -d docs/wiki ]; then
echo "found=true" >> "$GITHUB_OUTPUT"
else
echo "found=false" >> "$GITHUB_OUTPUT"
echo "No docs/wiki folder in this repository; nothing to publish."
fi
- name: Fetch the shared script
if: steps.source.outputs.found == 'true'
uses: actions/checkout@v4.2.2
with:
repository: TirSystem/git-workflows
ref: v2
path: shared-scripts
- name: Publish the pages to the wiki
if: steps.source.outputs.found == 'true'
env:
GITEA_API_URL: ${{ gitea.api_url }}
SOURCE_REPOSITORY: ${{ gitea.repository }}
WIKI_CREDENTIALS: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
WIKI_DIR: docs/wiki
WIKI_PRUNE: "false"
run: python3 shared-scripts/tools/publish_wiki.py
.gitea/workflows/publish-own-wiki.yml
-25
View File
@@ -1,25 +0,0 @@
name: Publish own wiki
# Publishes the wiki of this repository from docs/wiki/ by calling the
# reusable workflow of this repository (ADR-0009, MIL-008 task 4). It is the
# caller a project copies from framework/templates/ci/publish-wiki.yml, with
# two differences: the reusable workflow is called by its local path, and
# tools-ref is main so that the script that is run is the one of this commit.
on:
push:
branches: [ main ]
paths:
- "docs/wiki/**"
workflow_dispatch:
jobs:
wiki:
permissions:
contents: read
uses: ./.gitea/workflows/publish-wiki-pages.yml
with:
wiki_dir: docs/wiki
prune: "true"
tools-ref: main
secrets:
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
.gitea/workflows/publish-wiki-pages.yml
-64
View File
@@ -1,64 +0,0 @@
name: Publish wiki
# Reusable workflow (ADR-0009, MIL-008). A repository calls it with
#
# on:
# push:
# branches: [ main ]
# paths: [ "docs/wiki/**" ]
# jobs:
# wiki:
# uses: TirSystem/git-workflows/.gitea/workflows/publish-wiki-pages.yml@v1
# secrets:
# TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
#
# The caller file is the opt-in; there is no marker file. It publishes the
# Markdown pages of wiki_dir to the wiki of the calling repository, creating
# and updating pages, and deleting pages that are not in the folder only when
# prune is true. The script is a file of this repository
# (tools/publish_wiki.py), fetched at tools-ref.
on:
workflow_call:
inputs:
wiki_dir:
description: "Directory, relative to the repository root, with the wiki pages"
type: string
default: "docs/wiki"
prune:
description: "true deletes wiki pages that are not in the folder; false keeps them"
type: string
default: "false"
tools-ref:
description: "Tag or branch of TirSystem/git-workflows whose tools/publish_wiki.py is run; pin it to the exact tag together with the workflow"
type: string
default: "v2"
secrets:
TOKEN_FOR_GITEA_WIKI:
description: "Gitea token with write access to the wiki of the calling repository"
required: true
jobs:
publish-wiki:
permissions:
contents: read
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Check out the repository
uses: actions/checkout@v4.2.2
- name: Fetch the shared script
uses: actions/checkout@v4.2.2
with:
repository: TirSystem/git-workflows
ref: ${{ inputs.tools-ref }}
path: shared-scripts
- name: Publish the pages to the wiki
env:
GITEA_API_URL: ${{ gitea.api_url }}
SOURCE_REPOSITORY: ${{ gitea.repository }}
WIKI_CREDENTIALS: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
WIKI_DIR: ${{ inputs.wiki_dir }}
WIKI_PRUNE: ${{ inputs.prune }}
run: python3 shared-scripts/tools/publish_wiki.py
README.md
+26 -63
View File
@@ -17,24 +17,23 @@ A collection of reusable Gitea Actions workflows for DevOps professionals and so
This repository is the central collection of reusable automation for TirSystem repositories. The primary repository lives at `git.tirsystem.com` (Gitea) and is push-mirrored to GitHub. This repository is the central collection of reusable automation for TirSystem repositories. The primary repository lives at `git.tirsystem.com` (Gitea) and is push-mirrored to GitHub.
It contains eleven workflows: metadata sync to the GitHub mirror, wiki publishing (called by each repository), shared quality checks for Python and shell, for C and C++ and for C#, code metrics and coverage badges, a check that comments are in English, a release workflow, the publishing of accepted milestones and the repository's own validation. They are listed with their purpose and a diagram under [Workflows](#-workflows). It contains ten workflows: metadata sync to the GitHub mirror, wiki publishing (scoped, for every repository with a `docs/wiki/` folder), shared quality checks for Python and shell, for C and C++ and for C#, code metrics and coverage badges, a check that comments are in English, a release workflow, the publishing of accepted milestones and the repository's own validation. They are listed with their purpose and a diagram under [Workflows](#-workflows).
## 🔧 Workflows ## 🔧 Workflows
When a repository should use each workflow in its SQA and QC is set out in the [adoption rules](guides/adoption-rules.md). When a repository should use each workflow in its SQA and QC is set out in the [adoption rules](guides/adoption-rules.md).
Eleven workflows live in this repository. A **scoped** workflow is delivered by the instance to every repository of the TirSystem organizations and needs nothing in the repository; a **reusable** workflow is called by a repository with `uses:`; the others run only here. The diagrams are PlantUML source. Ten workflows live in this repository. A **scoped** workflow is delivered by the instance to every repository of the TirSystem organizations and needs nothing in the repository; a **reusable** workflow is called by a repository with `uses:`; the others run only here. The diagrams are PlantUML source.
| Workflow | File | Kind | Starts on | Purpose | | Workflow | File | Kind | Starts on | Purpose |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
| Sync GitHub mirror metadata | [`sync-github-metadata.yml`](.gitea/scoped_workflows/sync-github-metadata.yml) | Scoped | push to `main`, manual, daily 03:17 UTC | Copies the description and topics of a Gitea repository to its GitHub push mirror | | Sync GitHub mirror metadata | [`sync-github-metadata.yml`](.gitea/scoped_workflows/sync-github-metadata.yml) | Scoped | push to `main`, manual, daily 03:17 UTC | Copies the description and topics of a Gitea repository to its GitHub push mirror |
| Publish wiki pages | [`publish-wiki-pages.yml`](.gitea/workflows/publish-wiki-pages.yml) | Reusable (`workflow_call`) | a call from another repository | Publishes the pages in `docs/wiki/` (or the folder named by `wiki_dir`) to the wiki of the calling repository | | Publish wiki pages | [`publish-wiki-pages.yml`](.gitea/scoped_workflows/publish-wiki-pages.yml) | Scoped | push to `main` that changes `docs/wiki/**`, manual | Publishes the pages in `docs/wiki/` to the wiki of the repository; skipped where the folder does not exist |
| Quality checks | [`quality-checks.yml`](.gitea/workflows/quality-checks.yml) | Reusable (`workflow_call`) | a call from another repository | Runs ruff, mypy, shellcheck and shfmt on the tracked files and changes nothing | | Quality checks | [`quality-checks.yml`](.gitea/workflows/quality-checks.yml) | Reusable (`workflow_call`) | a call from another repository | Runs ruff, mypy, shellcheck and shfmt on the tracked files and changes nothing |
| Quality checks C++ | [`quality-checks-cpp.yml`](.gitea/workflows/quality-checks-cpp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs clang-format and clang-tidy at exact versions on the tracked C and C++ files and changes nothing | | Quality checks C++ | [`quality-checks-cpp.yml`](.gitea/workflows/quality-checks-cpp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs clang-format and clang-tidy at exact versions on the tracked C and C++ files and changes nothing |
| Quality checks C# | [`quality-checks-csharp.yml`](.gitea/workflows/quality-checks-csharp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs `dotnet format` and `dotnet build` on an exact .NET SDK 10 or later and changes nothing | | Quality checks C# | [`quality-checks-csharp.yml`](.gitea/workflows/quality-checks-csharp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs `dotnet format` and `dotnet build` on an exact .NET SDK 10 or later and changes nothing |
| Code metrics | [`code-metrics.yml`](.gitea/workflows/code-metrics.yml) | Reusable (`workflow_call`) | a call from another repository | Counts the code files and the lines of code (without comment and blank lines), reads a Cobertura coverage report and commits three SVG badges to a `badges` branch | | Code metrics | [`code-metrics.yml`](.gitea/workflows/code-metrics.yml) | Reusable (`workflow_call`) | a call from another repository | Counts the code files and the lines of code (without comment and blank lines), reads a Cobertura coverage report and commits three SVG badges to a `badges` branch |
| English comments | [`english-comments.yml`](.gitea/workflows/english-comments.yml) | Reusable (`workflow_call`) | a call from another repository, on a pull request | Judges the language of the comments and docstrings a pull request adds, fails the run when one is not English and writes one comment on the pull request that mentions the author | | English comments | [`english-comments.yml`](.gitea/workflows/english-comments.yml) | Reusable (`workflow_call`) | a call from another repository, on a pull request | Judges the language of the comments and docstrings a pull request adds, fails the run when one is not English and writes one comment on the pull request that mentions the author |
| Publish own wiki | [`publish-own-wiki.yml`](.gitea/workflows/publish-own-wiki.yml) | This repository only | push to `main` that changes `docs/wiki/**`, manual | Calls the reusable Publish wiki pages workflow for the wiki of this repository |
| Release | [`release.yml`](.gitea/workflows/release.yml) | This repository only | manual | Creates the version tag, the release page and the major tag after the checks | | Release | [`release.yml`](.gitea/workflows/release.yml) | This repository only | manual | Creates the version tag, the release page and the major tag after the checks |
| Publish accepted milestones | [`sync-milestones.yml`](.gitea/workflows/sync-milestones.yml) | This repository only | push to `main` that changes `docs/milestones/**` or `docs/sqa/reviews/**`, manual (dry run by default) | Creates or updates the Gitea milestone and issues of every milestone that is Accepted with a Go review | | Publish accepted milestones | [`sync-milestones.yml`](.gitea/workflows/sync-milestones.yml) | This repository only | push to `main` that changes `docs/milestones/**` or `docs/sqa/reviews/**`, manual (dry run by default) | Creates or updates the Gitea milestone and issues of every milestone that is Accepted with a Go review |
| Validate workflows | [`validate-workflows.yml`](.gitea/workflows/validate-workflows.yml) | This repository only | pull request, push to `main`, manual | Parses every workflow and runs the offline tests | | Validate workflows | [`validate-workflows.yml`](.gitea/workflows/validate-workflows.yml) | This repository only | pull request, push to `main`, manual | Parses every workflow and runs the offline tests |
@@ -376,88 +375,52 @@ deactivate Workflow
### 📖 Publish wiki pages ### 📖 Publish wiki pages
A reusable workflow (ADR-0009). A repository calls it from its own workflow, so the call is the opt-in and no marker file is needed. It publishes the Markdown pages of `wiki_dir` (default `docs/wiki`) to the wiki of the calling repository, and deletes pages that are not in the folder only when `prune` is `true`. A scoped workflow: the instance runs it in every repository of the organization, so no call and no marker file is needed. A repository opts in by having a `docs/wiki` folder; where there is none, the run ends without doing anything. It publishes the Markdown pages of `docs/wiki` to the wiki of the repository and keeps the wiki pages that are not in the folder. It needs the organization secret `TOKEN_FOR_GITEA_WIKI`.
```yaml
on:
push:
branches: [ main ]
paths: [ "docs/wiki/**" ]
jobs:
wiki:
uses: TirSystem/git-workflows/.gitea/workflows/publish-wiki-pages.yml@v1
secrets:
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
```
#### 🔀 Workflow #### 🔀 Workflow
```plantuml ```plantuml
@startuml @startuml
title Publish docs/wiki to the wiki of the calling repository title Publish docs/wiki to the wiki of the repository
autonumber autonumber
actor "Calling repository\nuses: ...publish-wiki-pages.yml@v1" as Caller actor "Push to main that changes docs/wiki/**,
participant "Gitea Actions\npublish-wiki-pages" as Workflow or manual trigger" as Trigger
participant "shared-scripts\n(tools/publish_wiki.py at tools-ref)" as Script participant "Gitea Actions
publish-wiki-pages" as Workflow
participant "shared-scripts
(tools/publish_wiki.py at v2)" as Script
participant "Gitea wiki API" as Wiki participant "Gitea wiki API" as Wiki
Caller -> Workflow: Call with wiki_dir, prune and the secret Trigger -> Workflow: Start workflow
activate Workflow activate Workflow
Workflow -> Script: Check out the repository and the script, run it Workflow -> Workflow: Check out the repository
activate Script
alt wiki_dir does not exist, or has no Markdown pages alt docs/wiki does not exist
Script --> Workflow: Fail with [configuration]\n(an empty folder never deletes pages) Workflow --> Trigger: Nothing to publish
else else
Script -> Script: Read prune and TOKEN_FOR_GITEA_WIKI Workflow -> Script: Fetch the script, run it
activate Script
alt docs/wiki has no Markdown pages
Script --> Workflow: Fail with [configuration]
(an empty folder never deletes pages)
else
Script -> Script: Read TOKEN_FOR_GITEA_WIKI
Script -> Wiki: GET repository (preflight) Script -> Wiki: GET repository (preflight)
Wiki --> Script: Wiki is enabled, token accepted Wiki --> Script: Wiki is enabled, token accepted
Script -> Wiki: GET pages Script -> Wiki: GET pages
Wiki --> Script: Existing pages Wiki --> Script: Existing pages
Script -> Wiki: Create new pages, update changed pages Script -> Wiki: Create new pages, update changed pages
opt prune is true Script --> Workflow: Log created and updated counts
Script -> Wiki: Delete pages that are not in wiki_dir
end end
Script --> Workflow: Log created, updated and deleted counts deactivate Script
Workflow --> Trigger: Workflow result
end end
deactivate Script
Workflow --> Caller: Workflow result
deactivate Workflow deactivate Workflow
@enduml @enduml
``` ```
### 📖 Publish own wiki
The wiki of this repository is `docs/wiki/`. This workflow calls the reusable workflow above by its local path, with `prune` set to `true` so the wiki always equals the folder and `tools-ref` set to `main` so that the script of the same commit runs. It is the caller that a project copies from the framework's `templates/ci/publish-wiki.yml`.
#### 🔀 Workflow
```plantuml
@startuml
title Publish the wiki of this repository (docs/wiki)
autonumber
actor "Push to main that changes docs/wiki/**,\nor manual trigger" as Trigger
participant "Gitea Actions\npublish-own-wiki" as Caller
participant "Gitea Actions\npublish-wiki-pages\n(called by its local path)" as Workflow
participant "Gitea wiki API" as Wiki
Trigger -> Caller: Start workflow
activate Caller
Caller -> Workflow: Call with wiki_dir docs/wiki, prune true,\ntools-ref main and TOKEN_FOR_GITEA_WIKI
activate Workflow
Workflow -> Wiki: Create, update and delete pages\nso the wiki equals docs/wiki
Wiki --> Workflow: Done
Workflow --> Caller: Workflow result
deactivate Workflow
Caller --> Trigger: Workflow result
deactivate Caller
@enduml
```
### 📌 Publish accepted milestones ### 📌 Publish accepted milestones
Standing authorization to publish: on a push to `main` that changes the milestones or their reviews, every milestone whose latest Version History row is Accepted and whose latest review is a Go is created or updated on Gitea with its tasks as issues. Nothing is closed or deleted. A manual run is a dry run unless `dry_run` is switched off. It uses the secret `TOKEN_FOR_GITEA` and the `--accepted-only` rule of the mounted framework (v0.5.0 or later). Standing authorization to publish: on a push to `main` that changes the milestones or their reviews, every milestone whose latest Version History row is Accepted and whose latest review is a Go is created or updated on Gitea with its tasks as issues. Nothing is closed or deleted. A manual run is a dry run unless `dry_run` is switched off. It uses the secret `TOKEN_FOR_GITEA` and the `--accepted-only` rule of the mounted framework (v0.5.0 or later).
@@ -585,7 +548,7 @@ Rows that say Implemented or Guides written exist today. The rest is planned and
| Synchronize repository metadata (Gitea to GitHub mirror) | Implemented in `.gitea/scoped_workflows/`, with offline tests and a validation workflow | | Synchronize repository metadata (Gitea to GitHub mirror) | Implemented in `.gitea/scoped_workflows/`, with offline tests and a validation workflow |
| Configure and validate workflow credentials | Implemented for the sync workflow: preflight checks both tokens before any change ([guide](guides/credentials.md)) | | Configure and validate workflow credentials | Implemented for the sync workflow: preflight checks both tokens before any change ([guide](guides/credentials.md)) |
| Onboard a repository, manage runners, diagnose failures | Guides written ([onboarding](guides/onboarding.md), [troubleshooting](guides/troubleshooting.md)); scoped delivery to the repositories of all four organizations verified (MIL-002) | | Onboard a repository, manage runners, diagnose failures | Guides written ([onboarding](guides/onboarding.md), [troubleshooting](guides/troubleshooting.md)); scoped delivery to the repositories of all four organizations verified (MIL-002) |
| Publish a repository wiki from `docs/wiki/` through a called workflow | Implemented as the reusable workflow `.gitea/workflows/publish-wiki-pages.yml`, with offline tests; called by every repository that publishes a wiki, and this repository's own wiki is in `docs/wiki/` (MIL-008, MIL-009) | | Publish a repository wiki from `docs/wiki/` through a called workflow | Implemented as the scoped workflow `.gitea/scoped_workflows/publish-wiki-pages.yml`, with offline tests; it runs in every repository that has a `docs/wiki/` folder, and this repository's own wiki is in `docs/wiki/` (MIL-008, MIL-009) |
| Shared quality checks (Python and shell) | Implemented as the reusable workflow `.gitea/workflows/quality-checks.yml`, with offline tests and a trial in a second organization; adopted in RepoFoundry ([guide](guides/quality-checks.md)) | | Shared quality checks (Python and shell) | Implemented as the reusable workflow `.gitea/workflows/quality-checks.yml`, with offline tests and a trial in a second organization; adopted in RepoFoundry ([guide](guides/quality-checks.md)) |
| Shared quality checks (C and C++, C#) | Implemented as the reusable workflows `.gitea/workflows/quality-checks-cpp.yml` and `.gitea/workflows/quality-checks-csharp.yml` with exact tool versions and offline tests; not yet used in another repository (MIL-007) ([C and C++ guide](guides/quality-checks-cpp.md), [C# guide](guides/quality-checks-csharp.md)) | | Shared quality checks (C and C++, C#) | Implemented as the reusable workflows `.gitea/workflows/quality-checks-cpp.yml` and `.gitea/workflows/quality-checks-csharp.yml` with exact tool versions and offline tests; not yet used in another repository (MIL-007) ([C and C++ guide](guides/quality-checks-cpp.md), [C# guide](guides/quality-checks-csharp.md)) |
| Code metrics and coverage badges | Implemented and released in 2.1.0 as the reusable workflow `.gitea/workflows/code-metrics.yml` with a counter, a Cobertura reader, an SVG renderer and offline tests; tried in a throwaway repository, not yet used in a project repository (MIL-010) ([guide](guides/code-metrics.md)) | | Code metrics and coverage badges | Implemented and released in 2.1.0 as the reusable workflow `.gitea/workflows/code-metrics.yml` with a counter, a Cobertura reader, an SVG renderer and offline tests; tried in a throwaway repository, not yet used in a project repository (MIL-010) ([guide](guides/code-metrics.md)) |
docs/adr/adr-0012-english-comment-detection.md
+2 -1
View File
@@ -9,7 +9,7 @@
## Version History ## Version History
| Date | Status | Author | Reviewer | Change | Commit | | Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- | --- |
| 2026-10-19 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | pending | | 2026-10-19 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | [1988305] |
Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`. Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
@@ -87,3 +87,4 @@ The rules of the pre-filter came from the build, not from the first measurement.
[MIL-013]: ../milestones/mil-013-english-comments-check.md [MIL-013]: ../milestones/mil-013-english-comments-check.md
[ADR-0005]: ./adr-0005-quality-check-contract.md [ADR-0005]: ./adr-0005-quality-check-contract.md
[ADR-0010]: ./adr-0010-code-metrics-badges-contract.md [ADR-0010]: ./adr-0010-code-metrics-badges-contract.md
[1988305]: https://git.tirsystem.com/TirSystem/git-workflows/commit/198830588caa5047ff2cee4382b8f2a9bd391bff
docs/adr/adr-0013-wiki-publishing-scoped-workflow.md
+102
View File
@@ -0,0 +1,102 @@
# ADR-0013: Wiki publishing as a scoped workflow
## Metadata
| Key | Value |
| --- | --- |
| ID | ADR-0013 |
| CrossReference | [MIL-014], [ADR-0009], [ADR-0004] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-27 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version; Accepted on a Go review (RC-086); accepted by the author in chat on 2026-10-27 as stand-in for S01, not independent | [1fd6ae4] |
Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
---
## Context
[ADR-0004] published wikis with a scoped workflow and a marker file
`wiki/.publish`. [ADR-0009] replaced it with the reusable workflow
`publish-wiki-pages.yml`, because the marker was an opt-in the workflow had to
guard, and a repository needed to say where its wiki is. Since then the folder
is settled: the framework prescribes the wiki in `docs/wiki/`, and every
publishing repository uses the defaults. Seven repositories carry a caller file
with the same trigger and the same secret, and the only setting a caller adds
to the defaults is `prune`; each caller is a file to keep current when the
workflow changes.
Options:
1. **Keep the reusable workflow.** Explicit opt-in per repository, but a caller
file per repository that repeats the same trigger and the same secret.
2. **A scoped workflow that runs in every repository and publishes when
`docs/wiki/` exists.** Nothing to copy or call; the opt-in is the folder
itself, which is also what the content is.
3. **A scoped workflow with a marker file.** The marker was the thing
[ADR-0009] removed; the folder says the same thing.
## Decision
Wiki publishing is the scoped workflow `.gitea/scoped_workflows/publish-wiki-pages.yml`,
which runs in every repository and publishes `docs/wiki/` when the folder
exists; the reusable workflow, its inputs and the caller files are removed.
The rules that follow from it:
- The settings are fixed, not inputs: the folder is `docs/wiki`, pruning is off,
and the script is fetched from this repository at the current major tag.
- The secret `TOKEN_FOR_GITEA_WIKI` is read from the organization secrets of the
running repository; there is no fallback to another token.
- The workflow runs on a push to `main` that changes `docs/wiki/**`, and
manually, and ends without doing anything when the folder does not exist.
- Pages that are in the wiki but not in the folder are kept, so a repository
that needs pruning removes them by hand.
- The script, the page-title rules, the empty-folder protection and the error
categories of [ADR-0004] and [ADR-0003] are unchanged.
## Consequences
**Positive:**
- Nothing to add to a repository: a folder `docs/wiki/` is the whole opt-in, and
there is one workflow to maintain instead of one plus seven callers.
- A change to the workflow reaches every repository at once, the way the
metadata sync does.
**Negative:**
- Security: every repository of an organization that has `docs/wiki/` can write
its own wiki with the organization token. A repository that must not publish
has to disable its wiki or not use the folder; before the release a scan names
the repositories that would start publishing (`027-sandbox` and `028-pomodoro`
did not in MIL-009).
- A repository cannot choose another folder or prune; the repositories whose
caller sets `prune: "true"` lose that, and a page deleted from `docs/wiki/`
then stays in the wiki. One that needs either stays on `@v2` of the reusable
workflow, which keeps working because the `v2` tag is not moved.
- Removing the reusable workflow is a breaking change under [ADR-0006]: release
3.0.0. A repository that keeps its caller at `@v3` fails and one that keeps
both publishes twice, so the callers are removed first (MIL-014 task 5).
- A scoped workflow cannot be pinned by a repository and follows the major tag
of the script; a faulty script release reaches all repositories until the tag
is moved back.
- It reverses a decision reached two weeks earlier ([ADR-0009]) and the
framework template `templates/ci/publish-wiki.yml` is retired with it.
## Affected Artifacts
- [MIL-014] — the plan this decision belongs to.
- [ADR-0009] — its delivery and caller parts are replaced; its token rule and
the amendment of the `tools-ref` default stand as history for `@v2`.
- [ADR-0004] — its token and safety rules stand; its marker is not restored.
---
[MIL-014]: ../milestones/mil-014-wiki-publishing-scoped-again.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-0009]: ./adr-0009-wiki-publishing-reusable-workflow.md
[1fd6ae4]: https://git.tirsystem.com/TirSystem/git-workflows/commit/1fd6ae4ee07202dcd57caffdd267758ea20af005
docs/artifact-registry.md
+3 -3
View File
@@ -10,10 +10,10 @@ each document lives in *this* project and the next version to use.
| BC | Business Case | docs/business-case.md | 002 | | BC | Business Case | docs/business-case.md | 002 |
| SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 | | SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 |
| PP | Project Plan | docs/project-plan.md | 002 | | PP | Project Plan | docs/project-plan.md | 002 |
| MIL | Milestone / Gateway | docs/milestones/*.md | 014 | | MIL | Milestone / Gateway | docs/milestones/*.md | 016 |
| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 086 | | RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 089 |
| TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0013 | | ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0014 |
| UCD | Use Case Diagram | docs/use-case-diagram.md | 002 | | UCD | Use Case Diagram | docs/use-case-diagram.md | 002 |
| US | User Story | docs/user-stories.md | 002 | | US | User Story | docs/user-stories.md | 002 |
| UC | Use Case | docs/uc-NNN/uc.md | 009 | | UC | Use Case | docs/uc-NNN/uc.md | 009 |
docs/milestones/mil-014-wiki-publishing-scoped-again.md
+95
View File
@@ -0,0 +1,95 @@
# MIL-014: Publish wiki pages as a scoped workflow
## Metadata
| Key | Value |
| --- | --- |
| ID | MIL-014 |
| CrossReference | [BC-001], [MIL-009], [ADR-0004], [ADR-0009], [ADR-0013], [RC-086] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-27 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version; Accepted on a Go review (RC-086); accepted by the author in chat on 2026-10-27 as stand-in for S01, not independent | [1fd6ae4] |
---
## Purpose
Decide whether wiki publishing returns to a scoped workflow: the instance runs
`publish-wiki-pages.yml` in every repository of the organizations, and a
repository opts in by having a `docs/wiki/` folder. MIL-008 and MIL-009 replaced
the scoped workflow by a reusable one that each of seven repositories calls; the
owner now wants the call and the caller file gone, because the folder
`docs/wiki/` is already the convention of the framework and a caller file adds
nothing a repository decides. This reverses part of [ADR-0009].
## Deliverable
The scoped workflow `.gitea/scoped_workflows/publish-wiki-pages.yml` (already
written in the working tree, with its tests and the guides, README and wiki
pages in three languages); the reusable workflow and this repository's own
caller removed; [ADR-0013] accepted and [ADR-0009] marked superseded; the seven
repositories that call the reusable workflow have dropped their caller; the
framework template `templates/ci/publish-wiki.yml` retired in the framework
repository; and the major release 3.0.0 with the tag `v3`.
## Go / No-Go Criteria
| # | Criterion (objectively checkable) | Go | No-Go |
| --- | --- | --- | --- |
| 1 | The scoped workflow runs in a repository with `docs/wiki/` and ends without publishing in one without | A run in this repository publishes; a run in a test repository without the folder succeeds and logs that there is nothing to publish | Either run fails, or the second one writes a wiki |
| 2 | The wiki of this repository equals `docs/wiki/` after the first run, and pages that are only in the wiki are kept | 0 differences read back through the API for the pages in the folder | A difference, or a deleted page |
| 3 | The organization secret `TOKEN_FOR_GITEA_WIKI` is available to the scoped run in each organization that has a repository with `docs/wiki/` | A scan lists each such organization with the secret present | A repository with the folder and no secret that is not named as an accepted failure |
| 4 | A scan of the four organizations lists every repository with `docs/wiki/` that has no wiki enabled, or where the first run would write unwanted pages (for example `027-sandbox` and `028-pomodoro`, which MIL-009 decided must not publish) | Each such repository is named and resolved (wiki disabled, folder renamed or owner accepts publishing) before the release | A repository would publish that its owner did not accept |
| 5 | The reusable workflow, this repository's caller, and every mention of calling it are removed; the tests, README, guides and the three wiki languages describe the scoped workflow | Offline tests pass and `python tools/build_wiki.py --check` is clean | A mention remains, or a test fails |
| 6 | [ADR-0013] is `Accepted` with a review record, [ADR-0009] is `Superseded by ADR-0013` with a review record, and [ADR-0013] links back | Both rows and the `RC-*` records present | Missing |
| 7 | The seven repositories no longer call `publish-wiki-pages.yml`, and each wiki still equals its `docs/wiki/` after the first scoped run | 0 differences for each, and no caller workflow found by the scan | A caller remains, or a difference |
| 8 | The framework has retired `templates/ci/publish-wiki.yml` and `process/wiki.md` describes the scoped workflow, released as a tag that this project pins | The tag exists and this project pins it | The pin is an unmerged commit |
| 9 | Release 3.0.0 is published with a Breaking entry, `v3` points to it, and `v2` still points to the last 2.x release | Tags read back through the API | `v2` moved, or no Breaking entry |
## Dependencies
| Depends on | Reason |
| --- | --- |
| MIL-009 | Removed the first scoped workflow, migrated the seven callers and set the list of repositories this milestone migrates back |
| MIL-013 | Release 2.3.0 comes first, so the 3.0.0 release carries one breaking change and nothing else |
| `TirSystem/sqa-qc-framework` release | `process/wiki.md` and the CI template must be a tag before a repository pins them |
## 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-27 — proposed after MIL-013 (2026-11-20); the Business Case sets no deadline, and S01 confirms the date when accepting the plan.
## Tasks
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
| --- | --- | --- | --- | --- |
| 1 | Record the decision | Write [ADR-0013] (wiki publishing as a scoped workflow, with the opt-in, the fixed settings and the security consequence of a token that every repository of an organization can reach) and review it. Mark [ADR-0009] `Superseded by ADR-0013` for the delivery and caller parts, with a review record, once [ADR-0013] is accepted. | No | [ADR-0013] |
| 2 | Check the instance | Verify on this Gitea instance that a scoped workflow with a `paths:` filter fires only on a push that changes `docs/wiki/**`, that the organization secret reaches a scoped run, how the file in `.gitea/scoped_workflows/` reaches the instance (S03), and list every repository of the four organizations that has `docs/wiki/`, its wiki setting and whether its owner wants it published (`027-sandbox` and `028-pomodoro` did not in MIL-009). | No | |
| 3 | Make the repository change | Review the working-tree change (scoped workflow, removed reusable workflow and caller, `tools/publish_wiki.py` message, tests, fixtures, README, guides, wiki pages in three languages) and merge it; confirm the first run on `main` publishes and a repository without the folder is skipped. | No | |
| 4 | Move the framework | In `TirSystem/sqa-qc-framework` retire `templates/ci/publish-wiki.yml`, rewrite `process/wiki.md` and the install guide for the scoped workflow, add the changelog entry and tag the release; then this project moves the submodule pin to the tag. | No | |
| 5 | Remove the callers | In each of `sqa-and-qc`, `sqa-qc-framework`, `sqa-qc-checklists`, `repo-foundry`, `021-snake-game`, `024-snake` and `025-weather`: delete the caller workflow (it would publish twice), keep `docs/wiki/`, one pull request each. Do this only after task 3 is merged and released, so no repository is left without publishing. | No | |
| 6 | Verify the migration | After each first scoped run read the wiki back and compare it with `docs/wiki/`; scan the four organizations for callers of `publish-wiki-pages.yml` and for repositories whose wiki would be written without their owner's agreement. Record the results in this milestone. | No | |
| 7 | Release 3.0.0 | Breaking entry (a removed reusable workflow and its inputs); upgrade guide for callers: remove the call and rely on the scoped workflow; release through the release workflow; `v3` is created and `v2` stays at the last 2.x release, so a caller still pinned at `@v2` keeps working. Move the examples in the guides to `@v3` where they describe the new major. | No | |
---
[BC-001]: ../business-case.md
[MIL-009]: ./mil-009-migrate-wiki-callers-and-remove-scoped-workflow.md
[ADR-0004]: ../adr/adr-0004-shared-wiki-publishing-opt-in.md
[ADR-0009]: ../adr/adr-0009-wiki-publishing-reusable-workflow.md
[ADR-0013]: ../adr/adr-0013-wiki-publishing-scoped-workflow.md
[RC-086]: ../sqa/reviews/rc-086-adr-0013-mil-014-pp-001.md
[1fd6ae4]: https://git.tirsystem.com/TirSystem/git-workflows/commit/1fd6ae4ee07202dcd57caffdd267758ea20af005
docs/milestones/mil-015-rename-to-git-workflows.md
+100
View File
@@ -0,0 +1,100 @@
# MIL-015: Rename the repository references to git-workflows
## Metadata
| Key | Value |
| --- | --- |
| ID | MIL-015 |
| CrossReference | [BC-001], [MIL-014], [ADR-0006], [RC-087], [RC-088] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-27 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version; accepted on a Go review (RC-087); accepted by the author in chat on 2026-10-27 as stand-in for S01, not independent | [851b24c] |
| 2026-10-27 | Accepted | Jens Tirsvad Nielsen | S01 | Updated to pull request 218 (live files renamed) and the removed required check: purpose, deliverable, criterion 5 and tasks 1, 3 and 4; reviewed (RC-088), accepted by the author in chat as stand-in for S01, not independent | [081a17d] |
---
## Purpose
Decide whether every place that names the repository `TirSystem/github-action`
now names `TirSystem/git-workflows`, which is its name on the instance. When this
milestone was accepted the old name was in 369 places outside the `framework/`
submodule. Since then pull request 218 (merged on 2026-10-27) renamed the live
files (code, configuration, README, guides and wiki pages), and the required
status check of `main` that carried the old name is gone: the protection of
`main` now has status checks switched off (read back through the API on
2026-10-27). What is left (checked on 2026-10-27): 194 places in milestones,
ADRs, review records and the plan, 16 in the Business Case, the use cases and the
user stories, and four mentions of `tailscale/github-action` and the changelog,
which are not the old name of this repository. What also remains is the
repositories that call a workflow here, whether the old name still resolves, and
a release.
## Deliverable
Code, configuration and user documentation that name `TirSystem/git-workflows`
(done by this milestone's task 1 and by pull request 218); the history
(milestones, ADRs, review records, changelog) left as written, with the rename
recorded once in the Project Plan; a branch protection whose required checks can
be produced (status checks are off today); the repositories that call a workflow
of this repository pointing at the new name; and a release that carries the
change.
## Go / No-Go Criteria
| # | Criterion (objectively checkable) | Go | No-Go |
| --- | --- | --- | --- |
| 1 | A search of code and configuration (`.gitea/`, `actions/`, `tools/`, `tests/`, `AGENTS.md`) finds `TirSystem/github-action` only in the changelog | Search result lists none outside `CHANGELOG.md` and the unrelated `tailscale/github-action` | A match remains |
| 2 | A search of README, `guides/` and `docs/wiki/` finds the old name only where a sentence explains the rename | Offline tests pass and `python tools/build_wiki.py --check` is clean | A match remains, or a test fails |
| 3 | The history is unchanged | `git diff` of `docs/milestones/`, `docs/adr/` and `docs/sqa/reviews/` against `main` shows only the files of this milestone | A past milestone, ADR or review record is rewritten |
| 4 | The old name still resolves for `uses:`, `repository:` and the tags `v1` and `v2` on this instance, or the release is major | A workflow that calls `TirSystem/github-action/...@v2` and one that checks it out succeed in a test repository | Either fails and the release is not major |
| 5 | The required checks of `main` can be produced by a pull request | Status checks are off, or every required context is produced by a run of this repository, read back through the API | A required context that no run produces |
| 6 | Every repository of the four organizations that calls a workflow of this repository, or checks it out, names the new repository | A scan lists none with the old name | Any remains, or a run fails after its change |
| 7 | The GitHub push mirror and the description and topics sync still work | The next run of **Sync GitHub mirror metadata** succeeds and the GitHub repository shows the same description and topics | A run fails |
| 8 | The release is published with a changelog entry that names the rename | Tag and release page read back through the API | No entry, or `v1` or `v2` moved |
## Dependencies
| Depends on | Reason |
| --- | --- |
| Pull request of MIL-014 (not the milestone) | It changes the same README, guides and wiki pages; the documentation task follows its merge so the two do not conflict. MIL-015 is decided before MIL-014 and does not depend on its decision |
| ADR-0006 | Decides the version of the release: a rename that keeps the old name working is a patch; one that does not is a major |
## Traceability
| Business Case objective / KPI / user story | Reference |
| --- | --- |
| O2, O4 | [BC-001] |
## Ownership
| Role | Stakeholder ID (SA) |
| --- | --- |
| Owner | S05 |
| Approving reviewer | S01 |
## Target Date
2026-11-06 — proposed by the author: the branch protection blocks pull requests now, and the change is small; the Business Case sets no deadline. S01 confirms the date when accepting the plan.
## Tasks
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
| --- | --- | --- | --- | --- |
| 1 | Rename in code and configuration | Done. Replaced `TirSystem/github-action` in the workflows that fetch their scripts, `tools/build_wiki.py`, the tests, the comment fixtures and `AGENTS.md`, and rebuilt the wiki pages that depend on the source URL; `tailscale/github-action`, a different repository, is untouched. Pull request 218 made the same change in the live files at the same time; the merge into the branch resolved to one result (674 tests pass, wiki check clean). | No | |
| 2 | Check the old name on the instance | In a test repository run a workflow that calls `TirSystem/github-action/.gitea/workflows/...@v2` and one that checks the repository out at `v2`, and record whether the redirect holds; check the GitHub push mirror and the metadata sync. The result decides the version of the release (criterion 4). | No | |
| 3 | Fix the required checks | Done by S01 or S03: the required check `TirSystem/github-action: Sync GitHub mirror metadata / sync-metadata (push)` is gone; on 2026-10-27 the protection of `main` showed status checks off (`enable_status_check` false, no contexts). The AI did not change branch protection. What remains is a decision: switch status checks back on with only `Validate workflows / validate (pull_request)`, so the offline tests gate the merge again. | No | |
| 4 | Record the rename and the rest of the documents | Mention the rename once in the Project Plan (done in the planning assumption) and list the Business Case, Stakeholder Analysis, use cases, use case diagram and user stories (16 places) for S01 to decide, because they name the project as it was. README, guides and the wiki pages were renamed by pull request 218 and need nothing more. Milestones, ADRs, review records and the changelog stay as written. | No | |
| 5 | Update the callers | Scan the four organizations for `uses: TirSystem/github-action/` and `repository: TirSystem/github-action`, and change each in a pull request per repository; include the framework (`sqa-qc-framework`, its `AGENTS.md` table and templates), which is released first. | No | |
| 6 | Verify | After the changes read back: the searches of criteria 1 and 2, the first run of every changed caller, the next metadata sync. Record the results in this milestone. | No | |
| 7 | Release | Changelog entry that names the rename; version as decided in task 2; release through the release workflow; the moving major tags are unchanged. | No | |
---
[BC-001]: ../business-case.md
[MIL-014]: ./mil-014-wiki-publishing-scoped-again.md
[ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.md
[RC-087]: ../sqa/reviews/rc-087-mil-015.md
[851b24c]: https://git.tirsystem.com/TirSystem/git-workflows/commit/851b24c63a8cd8a054cb380c1396a20de0686161
[RC-088]: ../sqa/reviews/rc-088-mil-015-update.md
[081a17d]: https://git.tirsystem.com/TirSystem/git-workflows/commit/081a17d07f4c7d7145cdc50984c669dfb798b48d
docs/project-plan.md
+20 -5
View File
@@ -4,19 +4,19 @@
| Key | Value | | Key | Value |
| --- | --- | | --- | --- |
| ID | PP-001 | | ID | PP-001 |
| CrossReference | [BC-001], [SA-001], [ADR-0002], [US-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010], [MIL-011], [MIL-012], [MIL-013] | | CrossReference | [BC-001], [SA-001], [ADR-0002], [US-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010], [MIL-011], [MIL-012], [MIL-013], [MIL-014], [MIL-015] |
## Version History ## Version History
| Date | Status | Author | Reviewer | Change | Commit | | Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- | --- |
| 2026-10-19 | Deprecated | Jens Tirsvad Nielsen | S01 | Added MIL-012 (VPN actions for deployment); reviewed (RC-080), accepted by the author in chat as stand-in for S01 | [c5d5941] | | 2026-10-27 | Deprecated | Jens Tirsvad Nielsen | S01 | Added MIL-015 (rename the repository references to git-workflows; the repository was called github-action); reviewed (RC-087), accepted by the author in chat as stand-in for S01 | [851b24c] |
| 2026-10-19 | Accepted | Jens Tirsvad Nielsen | S01 | Added MIL-013 (source code comments are in English); reviewed (RC-083), accepted by the author in chat as stand-in for S01 | [e35b1c5] | | 2026-10-27 | Accepted | Jens Tirsvad Nielsen | S01 | Updated MIL-015 to pull request 218 and the removed required check; reviewed (RC-088), accepted by the author in chat as stand-in for S01 | [081a17d] |
--- ---
## Purpose ## Purpose
This plan schedules thirteen milestones that move the repository from one This plan schedules fifteen milestones that move the repository from one
workflow with known defects to a documented, versioned collection of shared workflow with known defects to a documented, versioned collection of shared
workflows. The Business Case sets no deadline, so the dates are the plan's own; they were confirmed on 2026-10-10 by S01, standing in for S05 (ADR-0002). workflows. The Business Case sets no deadline, so the dates are the plan's own; they were confirmed on 2026-10-10 by S01, standing in for S05 (ADR-0002).
@@ -25,6 +25,8 @@ workflows. The Business Case sets no deadline, so the dates are the plan's own;
- Week 1 starts 2026-10-05; phases are two weeks long; the last decision is 2026-12-26; MIL-007 follows in January 2027 (2027-01-04 to 2027-01-16, confirmed on 2026-10-11 by S01). MIL-008 amends the shared wiki publishing of MIL-006 and runs in parallel with the October and November windows: its work started on 2026-10-13 and its decision date is its own Target Date, 2026-11-15. MIL-009 follows MIL-008 and runs from 2026-11-16 to its proposed Target Date, 2026-11-30, confirmed by S01 in chat on 2026-10-14. MIL-010 (code metrics and coverage badges) follows MIL-007 in January 2027, from 2027-01-18 to its Target Date, 2027-01-30, accepted by the user in chat on 2026-10-14. - Week 1 starts 2026-10-05; phases are two weeks long; the last decision is 2026-12-26; MIL-007 follows in January 2027 (2027-01-04 to 2027-01-16, confirmed on 2026-10-11 by S01). MIL-008 amends the shared wiki publishing of MIL-006 and runs in parallel with the October and November windows: its work started on 2026-10-13 and its decision date is its own Target Date, 2026-11-15. MIL-009 follows MIL-008 and runs from 2026-11-16 to its proposed Target Date, 2026-11-30, confirmed by S01 in chat on 2026-10-14. MIL-010 (code metrics and coverage badges) follows MIL-007 in January 2027, from 2027-01-18 to its Target Date, 2027-01-30, accepted by the user in chat on 2026-10-14.
- MIL-012 (VPN actions for deployment) runs from 2026-10-26 to its Target Date, 2026-11-06, proposed by the author and accepted by S01 in chat on 2026-10-19; it overlaps MIL-002 and MIL-003, which do not touch the runners' network. - MIL-012 (VPN actions for deployment) runs from 2026-10-26 to its Target Date, 2026-11-06, proposed by the author and accepted by S01 in chat on 2026-10-19; it overlaps MIL-002 and MIL-003, which do not touch the runners' network.
- MIL-013 (source code comments are in English) runs from 2026-11-09 to its Target Date, 2026-11-20, proposed by the author and accepted by S01 in chat on 2026-10-19; it overlaps MIL-009, whose work is on wiki callers and does not touch the runners or the reviewer of the check. - MIL-013 (source code comments are in English) runs from 2026-11-09 to its Target Date, 2026-11-20, proposed by the author and accepted by S01 in chat on 2026-10-19; it overlaps MIL-009, whose work is on wiki callers and does not touch the runners or the reviewer of the check.
- MIL-014 (publish wiki pages as a scoped workflow) runs from 2026-11-23 to its Target Date, 2026-11-27, proposed by the author; it follows MIL-013 so that release 3.0.0 carries one breaking change, and it reverses part of ADR-0009. S01 confirms the dates when accepting it.
- MIL-015 (rename the repository references to git-workflows) runs from 2026-10-28 to its Target Date, 2026-11-06, proposed by the author because the branch protection of `main` required a check named after the old repository name; it overlaps MIL-012. Pull request 218 renamed the live files and the check was removed on 2026-10-27, so the milestone keeps the callers, the check of the old name on the instance, the 16 project documents for S01 and the release. Its documentation task follows the merge of MIL-014. The repository was called `github-action` until its rename; the milestones, ADRs and review records written under that name are not rewritten.
- Work on a milestone starts only after its `MIL-*` document is `Accepted`. - Work on a milestone starts only after its `MIL-*` document is `Accepted`.
- Dates were confirmed on 2026-10-10 by S01, standing in for S05 (ADR-0002). - Dates were confirmed on 2026-10-10 by S01, standing in for S05 (ADR-0002).
@@ -45,6 +47,8 @@ workflows. The Business Case sets no deadline, so the dates are the plan's own;
| Fix the defaults of the code metrics workflow | [MIL-011] | 2026-10-14 to 2026-10-23 | 2026-10-23 | S05 | None (technical tasks) | Patch release 2.1.1: the default `tools-ref` of every reusable workflow names a tag that holds its scripts, a test for it, guides and wiki at `@v2`, the framework Badges page without the workaround | Not created yet (the sync creates it when MIL-011 is Accepted) | | Fix the defaults of the code metrics workflow | [MIL-011] | 2026-10-14 to 2026-10-23 | 2026-10-23 | S05 | None (technical tasks) | Patch release 2.1.1: the default `tools-ref` of every reusable workflow names a tag that holds its scripts, a test for it, guides and wiki at `@v2`, the framework Badges page without the workaround | Not created yet (the sync creates it when MIL-011 is Accepted) |
| VPN actions for deployment | [MIL-012] | 2026-10-26 to 2026-11-06 | 2026-11-06 | S05 | None (technical tasks) | Release 2.2.0: composite actions `connect-wireguard` and `connect-tailscale` verified on a runner of the instance, with guides, wiki in three languages and the framework templates pinned to the release | Not created yet (the sync creates it when MIL-012 is Accepted) | | VPN actions for deployment | [MIL-012] | 2026-10-26 to 2026-11-06 | 2026-11-06 | S05 | None (technical tasks) | Release 2.2.0: composite actions `connect-wireguard` and `connect-tailscale` verified on a runner of the instance, with guides, wiki in three languages and the framework templates pinned to the release | Not created yet (the sync creates it when MIL-012 is Accepted) |
| Source code comments are in English | [MIL-013] | 2026-11-09 to 2026-11-20 | 2026-11-20 | S05 | None (technical tasks) | Release 2.3.0: reusable workflow `english-comments.yml` that fails a pull request with a non-English comment and tells the author, with its ADR, tests, guides and wiki, and the rule proposed in the framework | Not created yet (the sync creates it when MIL-013 is Accepted) | | Source code comments are in English | [MIL-013] | 2026-11-09 to 2026-11-20 | 2026-11-20 | S05 | None (technical tasks) | Release 2.3.0: reusable workflow `english-comments.yml` that fails a pull request with a non-English comment and tells the author, with its ADR, tests, guides and wiki, and the rule proposed in the framework | Not created yet (the sync creates it when MIL-013 is Accepted) |
| Publish wiki pages as a scoped workflow | [MIL-014] | 2026-11-23 to 2026-11-27 | 2026-11-27 | S05 | None (technical tasks) | Release 3.0.0: scoped publish-wiki-pages workflow opted into by the docs/wiki folder, reusable workflow and the seven callers removed, ADR-0009 superseded | Not created yet (the sync runs after acceptance) |
| Rename the repository references to git-workflows | [MIL-015] | 2026-10-28 to 2026-11-06 | 2026-11-06 | S05 | None (technical tasks) | Code, configuration and user documentation name TirSystem/git-workflows, callers updated, required checks of main producible, released | Not created yet (the sync runs after acceptance) |
```plantuml ```plantuml
@startgantt @startgantt
@@ -75,6 +79,10 @@ Project starts 2026-10-05
[MIL-012 Go/No-Go] happens 2026-11-06 [MIL-012 Go/No-Go] happens 2026-11-06
[MIL-013 English comments] starts 2026-11-09 and ends 2026-11-20 [MIL-013 English comments] starts 2026-11-09 and ends 2026-11-20
[MIL-013 Go/No-Go] happens 2026-11-20 [MIL-013 Go/No-Go] happens 2026-11-20
[MIL-014 Scoped wiki] starts 2026-11-23 and ends 2026-11-27
[MIL-014 Go/No-Go] happens 2026-11-27
[MIL-015 Rename] starts 2026-10-28 and ends 2026-11-06
[MIL-015 Go/No-Go] happens 2026-11-06
@endgantt @endgantt
``` ```
@@ -94,6 +102,8 @@ Project starts 2026-10-05
| A shared workflow for code metrics and coverage badges | [MIL-010], [MIL-011] | | A shared workflow for code metrics and coverage badges | [MIL-010], [MIL-011] |
| Shared composite actions that connect a deployment job to a private network through WireGuard or Tailscale | [MIL-012] | | Shared composite actions that connect a deployment job to a private network through WireGuard or Tailscale | [MIL-012] |
| A shared workflow that checks that comments in source code are in English and tells the author | [MIL-013] | | A shared workflow that checks that comments in source code are in English and tells the author | [MIL-013] |
| The wiki publisher as a scoped workflow again, opt-in by the docs/wiki folder, without callers | [MIL-014] |
| The references to the repository name (workflows, documentation, callers) follow its rename to git-workflows | [MIL-015] |
## Dependencies ## Dependencies
@@ -105,6 +115,7 @@ MIL-001 → MIL-002 → MIL-003 → MIL-004
MIL-003 + MIL-004 → MIL-010 → MIL-011 MIL-003 + MIL-004 → MIL-010 → MIL-011
MIL-004 + MIL-011 → MIL-012 MIL-004 + MIL-011 → MIL-012
MIL-004 + MIL-010 + MIL-011 → MIL-013 MIL-004 + MIL-010 + MIL-011 → MIL-013
MIL-009 + MIL-013 → MIL-014
``` ```
A No-Go moves every later window by the rework time of the failed milestone. A No-Go moves every later window by the rework time of the failed milestone.
@@ -120,11 +131,11 @@ A No-Go moves every later window by the rework time of the failed milestone.
| The token of a run cannot push to a `badges` branch, or the SVG does not render on the mirror (MIL-010) | The delivery of the badges changes shape | MIL-010 task 3 verifies it first; fall back to a badge file in a path of the default branch or to a run artifact. | | The token of a run cannot push to a `badges` branch, or the SVG does not render on the mirror (MIL-010) | The delivery of the badges changes shape | MIL-010 task 3 verifies it first; fall back to a badge file in a path of the default branch or to a run artifact. |
| The runner cannot give a job `NET_ADMIN` and `/dev/net/tun`, or `tailscaled` does not survive to the next step (MIL-012) | The actions need another shape (a different start of the daemon, or userspace mode only) | MIL-012 tasks 2 to 4 verify it first on a runner of the instance; the release waits for criteria 2 and 3. | | The runner cannot give a job `NET_ADMIN` and `/dev/net/tun`, or `tailscaled` does not survive to the next step (MIL-012) | The actions need another shape (a different start of the daemon, or userspace mode only) | MIL-012 tasks 2 to 4 verify it first on a runner of the instance; the release waits for criteria 2 and 3. |
| The check calls a correct comment non-English, or misses a Danish or Malay one (MIL-013) | Authors lose trust in the check, or it is turned off | MIL-013 tasks 1 and 2 measure the method on a corpus before anything is built, and the exception marker and the allowed-words file (criterion 4) take care of the rest. | | The check calls a correct comment non-English, or misses a Danish or Malay one (MIL-013) | Authors lose trust in the check, or it is turned off | MIL-013 tasks 1 and 2 measure the method on a corpus before anything is built, and the exception marker and the allowed-words file (criterion 4) take care of the rest. |
| A repository with a `docs/wiki/` folder starts publishing a wiki its owner did not want, or its first scoped run fails (MIL-014) | An unwanted wiki is written with the organization token, or a wiki stops updating | MIL-014 tasks 2 and 6 list every repository with the folder before the release and read each wiki back after its first run; the reusable workflow stays at `v2` for a repository that needs it. |
| Security review by S05 is a bottleneck | Milestone decisions slip | Keep milestones small and plan review time before each decision date. | | Security review by S05 is a bottleneck | Milestone decisions slip | Keep milestones small and plan review time before each decision date. |
## Open Issues ## Open Issues
- No QC checklist exists for the Project Plan.
- The P1 candidates are written as brief use cases (UC-001 to UC-004) with a use case diagram (UCD-001) and user stories (US-001). The P2 and P3 candidates have no use case document yet. - The P1 candidates are written as brief use cases (UC-001 to UC-004) with a use case diagram (UCD-001) and user stories (US-001). The P2 and P3 candidates have no use case document yet.
## Appendix: Use Case Candidates and Prioritisation ## Appendix: Use Case Candidates and Prioritisation
@@ -298,6 +309,8 @@ no tests, no release process.
[MIL-011]: ./milestones/mil-011-code-metrics-default-tools-ref.md [MIL-011]: ./milestones/mil-011-code-metrics-default-tools-ref.md
[MIL-012]: ./milestones/mil-012-vpn-actions-for-deployment.md [MIL-012]: ./milestones/mil-012-vpn-actions-for-deployment.md
[MIL-013]: ./milestones/mil-013-english-comments-check.md [MIL-013]: ./milestones/mil-013-english-comments-check.md
[MIL-014]: ./milestones/mil-014-wiki-publishing-scoped-again.md
[MIL-015]: ./milestones/mil-015-rename-to-git-workflows.md
[Milestone MIL-001]: https://git.tirsystem.com/TirSystem/github-action/milestone/18 [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-002]: https://git.tirsystem.com/TirSystem/github-action/milestone/19
[Milestone MIL-003]: https://git.tirsystem.com/TirSystem/github-action/milestone/20 [Milestone MIL-003]: https://git.tirsystem.com/TirSystem/github-action/milestone/20
@@ -308,3 +321,5 @@ no tests, no release process.
[Milestone MIL-008]: https://git.tirsystem.com/TirSystem/github-action/milestone/152 [Milestone MIL-008]: https://git.tirsystem.com/TirSystem/github-action/milestone/152
[c5d5941]: https://git.tirsystem.com/TirSystem/github-action/commit/c5d59418698316866807388bf61dcb6166d9fa8b [c5d5941]: https://git.tirsystem.com/TirSystem/github-action/commit/c5d59418698316866807388bf61dcb6166d9fa8b
[e35b1c5]: https://git.tirsystem.com/TirSystem/github-action/commit/e35b1c56748a50430503f5518602469f93262357 [e35b1c5]: https://git.tirsystem.com/TirSystem/github-action/commit/e35b1c56748a50430503f5518602469f93262357
[851b24c]: https://git.tirsystem.com/TirSystem/git-workflows/commit/851b24c63a8cd8a054cb380c1396a20de0686161
[081a17d]: https://git.tirsystem.com/TirSystem/git-workflows/commit/081a17d07f4c7d7145cdc50984c669dfb798b48d
docs/sqa/reviews/rc-086-adr-0013-mil-014-pp-001.md
+96
View File
@@ -0,0 +1,96 @@
# Review Record: ADR-0013, MIL-014 and PP-001 (MIL-014)
## Metadata
| Key | Value |
| --- | --- |
| ID | RC-086 |
| CrossReference | [ADR-0013], [MIL-014], [PP-001], [QC-ADR-001], [QC-MIL-001], [QC-PP-001] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-27 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version; accepted by the author in chat on 2026-10-27 as stand-in for S01, after the corrections listed under Overall Verdict | [2f19cd0] |
---
## Artifact Under Review
- Instance reviewed: [MIL-014]; also [ADR-0013], and a delta of [PP-001] for the added milestone
- Checklists used: [QC-ADR-001], [QC-MIL-001], [QC-PP-001]
- Scope: full review of ADR-0013 and MIL-014; delta re-review of PP-001 (criteria 2, 3, 4, 5, 8, 10, 11, 12, 13, 14 and 15, the ones the added milestone touches), earlier record [RC-083]
- Language and domain: n/a (technical types)
- Language reviewer: none
- Mode: supervised, not independent (the author, Jens Tirsvad Nielsen, accepted the plan and its dates in chat on 2026-10-27 and stands in for S01; the AI prepared the evidence)
## Checklist Results
ADR-0013 against [QC-ADR-001]:
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 1 | The ID matches the filename number and is unique and sequential | Pass | `ADR-0013` in `adr-0013-wiki-publishing-scoped-workflow.md`; the registry's next ADR is 0014. |
| 2 | Context states the problem, the forces and the options evaluated | Pass | The callers repeat the same trigger and secret; the folder is already the framework convention; three options. |
| 3 | At least two options were considered | Pass | Keep the reusable workflow; scoped with the folder as opt-in; scoped with a marker. |
| 4 | Decision is unhedged, in one or two sentences, and matches an evaluated option | Pass | The first read found three sentences; the decision is now one sentence and matches option 2. The rules that follow it are a list. |
| 5 | Consequences list Positive and Negative outcomes | Pass | Two positive, five negative. |
| 6 | Quality-attribute impacts are named | Pass | Security (every repository with the folder can write its wiki with the organization token), compatibility (breaking change, `v2` kept), maintainability (one workflow instead of one plus seven callers). |
| 7 | Affected Artifacts are links and are in CrossReference | Pass | MIL-014, ADR-0009, ADR-0004 are in both. |
| 8 | Status changes are new Version History rows | Pass | One row; nothing rewritten. |
| 9 | A superseded ADR names its successor, and the successor links back | N-A | ADR-0013 names ADR-0009 as replaced in part; the row `Superseded by ADR-0013` in ADR-0009 is task 1 of MIL-014, done after this acceptance. |
| 10 | Written in the language of the domain, no unexplained abbreviations | Pass | |
| 11 | Status values are from the allowed set | Pass | `Accepted`. |
MIL-014 against [QC-MIL-001]:
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 1 | A concrete deliverable is defined for every gate | Pass | The scoped workflow, the removals, the two ADR states, the seven callers dropped, the framework template retired, release 3.0.0 with `v3`. |
| 2 | Explicit Go/No-Go criteria | Pass | Nine criteria, each checkable (a run, a scan, a read-back through the API, a tag). |
| 3 | Dependencies are mapped | Pass | MIL-009, MIL-013 and the framework release; the instance delivery of the file is made a check in task 2. |
| 4 | Traceable to a Business Case objective | Pass | O2 and O3 of [BC-001], as in MIL-009. |
| 5 | Owner and approving reviewer | Pass | S05 and S01, both in [SA-001]. |
| 6 | Target date consistent with the constraints | Pass | 2026-11-27, accepted by the author in chat on 2026-10-27; the Business Case sets no deadline. It follows MIL-013 (2026-11-20). |
PP-001 delta against [QC-PP-001]:
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 2 | Every gateway is listed once with document, decision date and owner | Pass | Schedule row: [MIL-014], 2026-11-27, S05. |
| 3 | Decision dates agree with the `MIL-*` document | Pass | 2026-11-27 in the plan, the Gantt and the Target Date of MIL-014. |
| 4 | Every in-scope item has a gateway | Pass | Scope row "The wiki publisher as a scoped workflow again, opt-in by the docs/wiki folder, without callers". |
| 5 | Dependencies are stated, acyclic and in schedule order | Pass | `MIL-009 + MIL-013 -> MIL-014`; MIL-014 is decided after both. |
| 8 | Assumptions are listed with their source | Pass | A planning assumption names the dates, that the author proposed them and the reversal of ADR-0009. |
| 10 | Open issues are current | Pass | The first read found the entry "No QC checklist exists for the Project Plan", stale since [QC-PP-001] exists (framework v0.17.0); removed. |
| 11 | The plan deliverable matches the `MIL-*` deliverable | Pass | Both say release 3.0.0, the scoped workflow, the removal of the reusable workflow and the seven callers, ADR-0009 superseded. |
| 12 | Gateways name their user stories or say why not | Pass | "None (technical tasks)". |
| 13 | Schedule view and dependency view agree | Pass | Table, Gantt bar and dependency line all carry MIL-014. |
| 14 | Each gateway links to its tracker milestone or is marked not synced | Pass | "Not created yet (the sync runs after acceptance)"; the dry run of `sync-project.sh --milestone MIL-014` lists one Milestone and seven Issues. |
| 15 | The plan is a singleton and changes are in Version History | Pass | New row; the two latest are kept. |
The Purpose of the plan said "thirteen" milestones; the first read changed it to "fourteen". A plan risk for the new milestone was added (a repository starting to publish a wiki its owner did not want, or a failed first run).
## Overall Verdict
Go. Corrections made in the first read: the decision of ADR-0013 shortened to one sentence; the claim that callers set nothing but defaults replaced by the fact that a caller may set `prune` (and the loss of pruning added as a negative consequence); "four weeks earlier" corrected to two; the stale open issue and the milestone count of the plan. The author accepted the plan and the dates in chat on 2026-10-27 as stand-in for S01; this is not an independent review.
## Action Items
| Action | Owner | Due |
| --- | --- | --- |
| Confirm this record by S01 when an independent reading is possible. The author confirmed it again in chat on 2026-10-27; that is the same stand-in, so the item stays open | S01 | 2026-11-06 |
| Mark ADR-0009 `Superseded by ADR-0013` with a review record (MIL-014 task 1); until then ADR-0009 and ADR-0013 both read `Accepted` | S05 | Before the pull request merges |
| Verify that a scoped workflow with a `paths:` filter fires on this instance, that the organization secret reaches it, and how the file reaches the instance (MIL-014 task 2) | S03 | 2026-11-23 |
| Decide for each repository with `docs/wiki/` whether it publishes (`027-sandbox`, `028-pomodoro`) before task 5 | S01 | 2026-11-23 |
---
[ADR-0013]: ../../adr/adr-0013-wiki-publishing-scoped-workflow.md
[MIL-014]: ../../milestones/mil-014-wiki-publishing-scoped-again.md
[PP-001]: ../../project-plan.md
[BC-001]: ../../business-case.md
[SA-001]: ../../stakeholder-analysis.md
[RC-083]: ./rc-083-mil-013-plan.md
[QC-ADR-001]: ../../../framework/qc/artifacts/qc-adr.md
[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
[QC-PP-001]: ../../../framework/qc/artifacts/qc-project-plan.md
[2f19cd0]: https://git.tirsystem.com/TirSystem/git-workflows/commit/2f19cd0adaddf1aea03d7a16bc10a81dd41ad740
docs/sqa/reviews/rc-087-mil-015.md
+75
View File
@@ -0,0 +1,75 @@
# Review Record: MIL-015 and PP-001 (MIL-015)
## Metadata
| Key | Value |
| --- | --- |
| ID | RC-087 |
| CrossReference | [MIL-015], [PP-001], [BC-001], [QC-MIL-001], [QC-PP-001] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-27 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version; accepted by the author in chat on 2026-10-27 as stand-in for S01, after the corrections listed under Overall Verdict | [851b24c] |
---
## Artifact Under Review
- Instance reviewed: [MIL-015]; delta of [PP-001] for the added milestone
- Checklists used: [QC-MIL-001] for the milestone; [QC-PP-001] for the plan
- Scope: full review of MIL-015; delta re-review of PP-001 (criteria 2, 3, 4, 5, 8, 10, 11, 12, 13, 14 and 15), earlier record [RC-086]
- Language and domain: n/a (technical type)
- Language reviewer: none
- Mode: supervised, not independent (the author, Jens Tirsvad Nielsen, accepted the plan and its dates in chat on 2026-10-27 and stands in for S01; the AI prepared the evidence)
## Checklist Results
MIL-015 against [QC-MIL-001]:
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 1 | A concrete deliverable is defined for every gate | Pass | Code, configuration and user documentation naming `TirSystem/git-workflows`, history left as written, producible required checks, updated callers, a release. |
| 2 | Explicit Go/No-Go criteria | Pass | Eight criteria, each checkable by a search, a test, a run, a scan or a tag read-back. |
| 3 | Dependencies are mapped | Pass | The pull request of MIL-014 (documentation task only) and ADR-0006 for the version. The first read made explicit that MIL-015 is decided before MIL-014 and does not depend on its decision. |
| 4 | Traceable to a Business Case objective | Pass | O2 (a defined way to reach consumers) and O4 (versioned for consumers) of [BC-001]. |
| 5 | Owner and approving reviewer | Pass | S05 and S01, both in [SA-001]. |
| 6 | Target date consistent with the constraints | Pass | 2026-11-06, accepted by the author in chat on 2026-10-27; the Business Case sets no deadline. |
PP-001 delta against [QC-PP-001]:
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 2 | Every gateway is listed once with document, decision date and owner | Pass | Schedule row [MIL-015], 2026-11-06, S05. |
| 3 | Decision dates agree with the `MIL-*` document | Pass | 2026-11-06 in the plan, the Gantt bar and the Target Date. |
| 4 | Every in-scope item has a gateway | Pass | Scope row "The references to the repository name ... follow its rename to git-workflows". |
| 5 | Dependencies are acyclic and in schedule order | Pass | The first read found a plan line `MIL-014 -> MIL-015` that would put MIL-015 (2026-11-06) before its predecessor MIL-014 (2026-11-27); removed, because the dependency is on the pull request only. |
| 8 | Assumptions are listed with their source | Pass | A planning assumption names the dates, the reason (branch protection) and that history is not rewritten. |
| 10 | Open issues are current | Pass | No open issue contradicts the new row. |
| 11 | The plan deliverable matches the `MIL-*` deliverable | Pass | Both name code, configuration and documentation, callers, producible checks and a release. |
| 12 | Gateways name their user stories or say why not | Pass | "None (technical tasks)". |
| 13 | Schedule view and dependency view agree | Pass | Table, Gantt bar and scope row carry MIL-015; the dependency list has no line for it, as intended. |
| 14 | Each gateway links to its tracker milestone or is marked not synced | Pass | "Not created yet"; the dry run of `sync-project.sh --milestone MIL-015` lists one Milestone and seven Issues. |
| 15 | The plan is a singleton and changes are in Version History | Pass | New row; the two latest are kept. |
## Overall Verdict
Go. Corrections made in the first read: the counts of the Purpose (the 369 places are 41 + 128 + 184 + 16; the 16 in the Business Case, use cases and user stories were missing and are now a decision for S01 in task 4); the claim that the old name "exists only through a redirect" is now "may exist ... (task 2 checks it)", because it is not verified; and the false dependency line in the plan. The author accepted the plan and the dates in chat on 2026-10-27 as stand-in for S01; this is not an independent review.
## Action Items
| Action | Owner | Due |
| --- | --- | --- |
| Confirm this record by S01 when an independent reading is possible. The author confirmed it again in chat on 2026-10-27; that is the same stand-in, so the item stays open | S01 | 2026-11-06 |
| Remove the required check `TirSystem/github-action: Sync GitHub mirror metadata / sync-metadata (push)` from the protection of `main` (task 3); the AI does not change branch protection | S01 | 2026-10-30 |
| Decide whether the Business Case, Stakeholder Analysis, use cases, use case diagram and user stories change the name (16 places) | S01 | 2026-11-06 |
---
[MIL-015]: ../../milestones/mil-015-rename-to-git-workflows.md
[PP-001]: ../../project-plan.md
[BC-001]: ../../business-case.md
[SA-001]: ../../stakeholder-analysis.md
[RC-086]: ./rc-086-adr-0013-mil-014-pp-001.md
[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
[QC-PP-001]: ../../../framework/qc/artifacts/qc-project-plan.md
[851b24c]: https://git.tirsystem.com/TirSystem/git-workflows/commit/851b24c63a8cd8a054cb380c1396a20de0686161
docs/sqa/reviews/rc-088-mil-015-update.md
+77
View File
@@ -0,0 +1,77 @@
# Review Record: MIL-015 after pull request 218 and PP-001 (MIL-015)
## Metadata
| Key | Value |
| --- | --- |
| ID | RC-088 |
| CrossReference | [MIL-015], [PP-001], [RC-087], [QC-MIL-001], [QC-PP-001] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-27 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version; accepted by the author in chat on 2026-10-27 as stand-in for S01 | [081a17d] |
---
## Artifact Under Review
- Instance reviewed: [MIL-015]; delta of [PP-001] for the changed row and assumption
- Checklists used: [QC-MIL-001] for the milestone; [QC-PP-001] for the plan
- Scope: delta re-review of MIL-015 (purpose, deliverable, criterion 5, tasks 1, 3 and 4; criteria 1 to 6 of the checklist re-read) and of PP-001 (criteria 3, 8, 10, 11, 13 and 15), reason: pull request 218 renamed the live files and the required check of `main` was removed after RC-087; earlier record [RC-087]
- Language and domain: n/a (technical type)
- Language reviewer: none
- Mode: supervised, not independent (the author, Jens Tirsvad Nielsen, asked in chat on 2026-10-27 for the update and the review and stands in for S01; the AI prepared the evidence)
## Checklist Results
MIL-015 against [QC-MIL-001]:
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 1 | A concrete deliverable is defined for every gate | Pass | The deliverable now says what is done (live files, by task 1 and pull request 218) and what is not (history stays, status checks are off, callers, a release). |
| 2 | Explicit Go/No-Go criteria | Pass | Eight criteria. Criterion 5 now reads: status checks off, or every required context produced by a run of this repository, read back through the API; the old wording ("passed or not required") could not be read back. |
| 3 | Dependencies are mapped | Pass | Unchanged: the pull request of MIL-014 and ADR-0006. The documentation task that waited for it is replaced by a record-only task. |
| 4 | Traceable to a Business Case objective | Pass | O2 and O4 of [BC-001], unchanged. |
| 5 | Owner and approving reviewer | Pass | S05 and S01. |
| 6 | Target date consistent with the constraints | Pass | 2026-11-06 unchanged; fewer tasks remain. |
Facts the update rests on, each read on 2026-10-27:
| Claim | Evidence |
| --- | --- |
| Pull request 218 renamed the live files | Merged into `main` as `8327038`; `git grep github-action` in code, configuration, README, guides and wiki pages now finds only `tailscale/github-action` (another repository) and one changelog line. |
| The required check is gone | `GET .../branch_protections/main`: `enable_status_check` false, `status_check_contexts` null, `required_approvals` 0. |
| What remains | 194 places in 114 history files, 16 in 12 project documents. |
PP-001 delta against [QC-PP-001]:
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 3 | Decision dates agree with the `MIL-*` document | Pass | 2026-11-06 in both. |
| 8 | Assumptions are listed with their source | Pass | The MIL-015 assumption now records that pull request 218 and the removed check changed the scope, and what remains. |
| 10 | Open issues are current | Pass | No open issue contradicts the row. |
| 11 | The plan deliverable matches the `MIL-*` deliverable | Pass | The plan row (code, configuration and documentation name the new repository, callers updated, producible checks, released) still matches. |
| 13 | Schedule view and dependency view agree | Pass | Unchanged. |
| 15 | The plan is a singleton and changes are in Version History | Pass | New row; the two latest are kept. |
## Overall Verdict
Go. The update is smaller than the plan accepted in RC-087: tasks 1 and 3 are done and task 4 shrinks to a record and a list for S01. The first read found one weakness, now fixed: switching status checks off removed the gate for the offline tests too, so the protection is weaker than before the rename; this is an action item, not a fault in the milestone. The author accepted the update in chat on 2026-10-27 as stand-in for S01; this is not an independent review.
## Action Items
| Action | Owner | Due |
| --- | --- | --- |
| Confirm this record by S01 when an independent reading is possible | S01 | 2026-11-06 |
| Decide whether to switch status checks on `main` back on with only `Validate workflows / validate (pull_request)`; today no check gates the merge | S01 | 2026-11-06 |
| Decide whether the Business Case, Stakeholder Analysis, use cases, use case diagram and user stories change the name (16 places) | S01 | 2026-11-06 |
---
[MIL-015]: ../../milestones/mil-015-rename-to-git-workflows.md
[PP-001]: ../../project-plan.md
[BC-001]: ../../business-case.md
[RC-087]: ./rc-087-mil-015.md
[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
[QC-PP-001]: ../../../framework/qc/artifacts/qc-project-plan.md
[081a17d]: https://git.tirsystem.com/TirSystem/git-workflows/commit/081a17d07f4c7d7145cdc50984c669dfb798b48d
docs/sqa/traceability-matrix.md
+19 -7
View File
@@ -4,13 +4,13 @@
| Key | Value | | Key | Value |
| --- | --- | | --- | --- |
| ID | TM-001 | | ID | TM-001 |
| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010], [MIL-011], [MIL-012], [MIL-013], [ADR-0011], [ADR-0012], [UC-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], [RC-061], [RC-062], [RC-063], [RC-064], [RC-065], [RC-066], [RC-067], [RC-068], [RC-069], [RC-070], [RC-071], [RC-072], [RC-073], [RC-074], [RC-075], [RC-076], [RC-077], [RC-078], [RC-079], [RC-080], [RC-081], [RC-082], [RC-083], [RC-084], [RC-085], [ADR-0007], [ADR-0008], [ADR-0009], [ADR-0010], [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], [MIL-009], [MIL-010], [MIL-011], [MIL-012], [MIL-013], [MIL-014], [MIL-015], [ADR-0011], [ADR-0012], [ADR-0013], [UC-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], [RC-061], [RC-062], [RC-063], [RC-064], [RC-065], [RC-066], [RC-067], [RC-068], [RC-069], [RC-070], [RC-071], [RC-072], [RC-073], [RC-074], [RC-075], [RC-076], [RC-077], [RC-078], [RC-079], [RC-080], [RC-081], [RC-082], [RC-083], [RC-084], [RC-085], [ADR-0007], [ADR-0008], [ADR-0009], [ADR-0010], [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 ## Version History
| Date | Status | Author | Reviewer | Change | Commit | | Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- | --- |
| 2026-10-19 | Proposed | Jens Tirsvad Nielsen | S01 | Added MIL-013 (English comments check), RC-083 and RC-084 (its plan and objective O7) | [e35b1c5] | | 2026-10-27 | Proposed | Jens Tirsvad Nielsen | S01 | Added MIL-015 (rename to git-workflows) and RC-087 (its review) | [851b24c] |
| 2026-10-21 | Proposed | Jens Tirsvad Nielsen | S01 | Added ADR-0012 and RC-085 (MIL-013 results of the trial) | [88f852a] | | 2026-10-27 | Proposed | Jens Tirsvad Nielsen | S01 | Added RC-088 (MIL-015 updated to pull request 218) | [081a17d] |
--- ---
@@ -25,8 +25,8 @@ updated whenever an artifact instance is created or reviewed.
| Artifact Instance | Type | Upstream (Backward Link) | Downstream (Forward Link) | Last Reviewed (RC-ID) | | Artifact Instance | Type | Upstream (Backward Link) | Downstream (Forward Link) | Last Reviewed (RC-ID) |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
| [SA-001] | SA | - | [BC-001], [UCD-001] | [RC-004] | | [SA-001] | SA | - | [BC-001], [UCD-001] | [RC-004] |
| [BC-001] | BC | [SA-001] | [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-012], [MIL-013] | [RC-001], [RC-008], [RC-067], [RC-081], [RC-084] | | [BC-001] | BC | [SA-001] | [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-012], [MIL-013], [MIL-014], [MIL-015] | [RC-001], [RC-008], [RC-067], [RC-081], [RC-084] |
| [PP-001] | PP | [BC-001], [SA-001] | [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010], [MIL-011], [MIL-012], [MIL-013], [US-001] | [RC-002], [RC-009], [RC-015], [RC-017], [RC-025], [RC-032], [RC-053], [RC-062], [RC-064], [RC-068], [RC-080], [RC-083] | | [PP-001] | PP | [BC-001], [SA-001] | [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010], [MIL-011], [MIL-012], [MIL-013], [MIL-014], [MIL-015], [US-001] | [RC-002], [RC-009], [RC-015], [RC-017], [RC-025], [RC-032], [RC-053], [RC-062], [RC-064], [RC-068], [RC-080], [RC-083], [RC-086], [RC-087], [RC-088] |
| [MIL-001] | MIL | [BC-001], [PP-001] | [MIL-002] | [RC-003], [RC-026] | | [MIL-001] | MIL | [BC-001], [PP-001] | [MIL-002] | [RC-003], [RC-026] |
| [MIL-002] | MIL | [BC-001], [PP-001], [MIL-001] | [MIL-003], [MIL-005] | [RC-005], [RC-027] | | [MIL-002] | MIL | [BC-001], [PP-001], [MIL-001] | [MIL-003], [MIL-005] | [RC-005], [RC-027] |
| [MIL-003] | MIL | [BC-001], [PP-001], [MIL-002] | [MIL-004] | [RC-006], [RC-028], [RC-033], [RC-039] | | [MIL-003] | MIL | [BC-001], [PP-001], [MIL-002] | [MIL-004] | [RC-006], [RC-028], [RC-033], [RC-039] |
@@ -34,6 +34,7 @@ updated whenever an artifact instance is created or reviewed.
| [ADR-0010] | ADR | [MIL-010], [UC-008], [US-001], [ADR-0005], [ADR-0006] | - | [RC-072], [RC-073] | | [ADR-0010] | ADR | [MIL-010], [UC-008], [US-001], [ADR-0005], [ADR-0006] | - | [RC-072], [RC-073] |
| [ADR-0011] | ADR | [MIL-012], [ADR-0005], [ADR-0006] | - | - | | [ADR-0011] | ADR | [MIL-012], [ADR-0005], [ADR-0006] | - | - |
| [ADR-0012] | ADR | [MIL-013], [ADR-0005], [ADR-0010] | - | - | | [ADR-0012] | ADR | [MIL-013], [ADR-0005], [ADR-0010] | - | - |
| [ADR-0013] | ADR | [MIL-014], [ADR-0009], [ADR-0004] | - | [RC-086] |
| [RC-001] | RC | [BC-001] | - | - | | [RC-001] | RC | [BC-001] | - | - |
| [RC-002] | RC | [PP-001] | - | - | | [RC-002] | RC | [PP-001] | - | - |
| [RC-003] | RC | [MIL-001] | - | - | | [RC-003] | RC | [MIL-001] | - | - |
@@ -49,6 +50,8 @@ updated whenever an artifact instance is created or reviewed.
| [MIL-011] | MIL | [BC-001], [PP-001], [MIL-010], [ADR-0006], [ADR-0010] | [MIL-012] | [RC-076], [RC-077], [RC-078], [RC-079] | | [MIL-011] | MIL | [BC-001], [PP-001], [MIL-010], [ADR-0006], [ADR-0010] | [MIL-012] | [RC-076], [RC-077], [RC-078], [RC-079] |
| [MIL-012] | MIL | [BC-001], [PP-001], [MIL-004], [MIL-011], [ADR-0006], [ADR-0011] | - | [RC-080], [RC-082] | | [MIL-012] | MIL | [BC-001], [PP-001], [MIL-004], [MIL-011], [ADR-0006], [ADR-0011] | - | [RC-080], [RC-082] |
| [MIL-013] | MIL | [BC-001], [PP-001], [MIL-004], [MIL-010], [MIL-011], [ADR-0005], [ADR-0006], [ADR-0010] | - | [RC-083], [RC-085] | | [MIL-013] | MIL | [BC-001], [PP-001], [MIL-004], [MIL-010], [MIL-011], [ADR-0005], [ADR-0006], [ADR-0010] | - | [RC-083], [RC-085] |
| [MIL-014] | MIL | [BC-001], [PP-001], [MIL-009], [MIL-013], [ADR-0004], [ADR-0009], [ADR-0013] | - | [RC-086] |
| [MIL-015] | MIL | [BC-001], [PP-001], [MIL-014], [ADR-0006] | - | [RC-087], [RC-088] |
| [RC-007] | RC | [MIL-004] | - | - | | [RC-007] | RC | [MIL-004] | - | - |
| [RC-008] | RC | [BC-001] | - | - | | [RC-008] | RC | [BC-001] | - | - |
| [RC-009] | RC | [PP-001] | - | - | | [RC-009] | RC | [PP-001] | - | - |
@@ -147,6 +150,9 @@ updated whenever an artifact instance is created or reviewed.
| [RC-083] | RC | [MIL-013], [PP-001] | - | - | | [RC-083] | RC | [MIL-013], [PP-001] | - | - |
| [RC-084] | RC | [BC-001] | - | - | | [RC-084] | RC | [BC-001] | - | - |
| [RC-085] | RC | [MIL-013] | - | - | | [RC-085] | RC | [MIL-013] | - | - |
| [RC-086] | RC | [ADR-0013], [MIL-014], [PP-001] | - | - |
| [RC-087] | RC | [MIL-015], [PP-001] | - | - |
| [RC-088] | RC | [MIL-015], [PP-001] | - | - |
## Coverage Notes ## Coverage Notes
@@ -176,6 +182,12 @@ updated whenever an artifact instance is created or reviewed.
[ADR-0010]: ../adr/adr-0010-code-metrics-badges-contract.md [ADR-0010]: ../adr/adr-0010-code-metrics-badges-contract.md
[ADR-0011]: ../adr/adr-0011-vpn-composite-actions.md [ADR-0011]: ../adr/adr-0011-vpn-composite-actions.md
[ADR-0012]: ../adr/adr-0012-english-comment-detection.md [ADR-0012]: ../adr/adr-0012-english-comment-detection.md
[ADR-0013]: ../adr/adr-0013-wiki-publishing-scoped-workflow.md
[MIL-014]: ../milestones/mil-014-wiki-publishing-scoped-again.md
[RC-086]: ./reviews/rc-086-adr-0013-mil-014-pp-001.md
[MIL-015]: ../milestones/mil-015-rename-to-git-workflows.md
[RC-087]: ./reviews/rc-087-mil-015.md
[RC-088]: ./reviews/rc-088-mil-015-update.md
[RC-001]: ./reviews/rc-001-business-case.md [RC-001]: ./reviews/rc-001-business-case.md
[RC-002]: ./reviews/rc-002-project-plan.md [RC-002]: ./reviews/rc-002-project-plan.md
[RC-003]: ./reviews/rc-003-mil-001.md [RC-003]: ./reviews/rc-003-mil-001.md
@@ -281,5 +293,5 @@ updated whenever an artifact instance is created or reviewed.
[UC-005]: ../uc-005/uc.md [UC-005]: ../uc-005/uc.md
[ADR-0005]: ../adr/adr-0005-quality-check-contract.md [ADR-0005]: ../adr/adr-0005-quality-check-contract.md
[3d7a9df]: https://git.tirsystem.com/TirSystem/github-action/commit/3d7a9df3a3a4712dcc5214a71b0569d90122bf4e [3d7a9df]: https://git.tirsystem.com/TirSystem/github-action/commit/3d7a9df3a3a4712dcc5214a71b0569d90122bf4e
[e35b1c5]: https://git.tirsystem.com/TirSystem/github-action/commit/e35b1c56748a50430503f5518602469f93262357 [851b24c]: https://git.tirsystem.com/TirSystem/git-workflows/commit/851b24c63a8cd8a054cb380c1396a20de0686161
[88f852a]: https://git.tirsystem.com/TirSystem/github-action/commit/88f852af9398468b91e88fe0190ce5c35dcf0fa2 [081a17d]: https://git.tirsystem.com/TirSystem/git-workflows/commit/081a17d07f4c7d7145cdc50984c669dfb798b48d
docs/wiki/Capabilities.da.md
+2 -2
View File
@@ -1,4 +1,4 @@
<!-- translation of Capabilities.md, source sha256 b09c3b44caec --> <!-- translation of Capabilities.md, source sha256 2f30825f19a1 -->
> Dette er en oversættelse af [`Capabilities`](Capabilities). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres. > Dette er en oversættelse af [`Capabilities`](Capabilities). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
@@ -13,7 +13,7 @@ Rækker, der siger Implementeret eller Vejledninger er skrevet, findes i dag. Re
| Synkronisering af repositorymetadata (Gitea til GitHub-spejl) | Implementeret i `.gitea/scoped_workflows/`, med offline-tests og et valideringsworkflow | | Synkronisering af repositorymetadata (Gitea til GitHub-spejl) | Implementeret i `.gitea/scoped_workflows/`, med offline-tests og et valideringsworkflow |
| Konfiguration og validering af workflow-credentials | Implementeret for synkroniseringsworkflowet: en forhåndskontrol tjekker begge tokens før enhver ændring ([vejledning](Credentials.da)) | | Konfiguration og validering af workflow-credentials | Implementeret for synkroniseringsworkflowet: en forhåndskontrol tjekker begge tokens før enhver ændring ([vejledning](Credentials.da)) |
| Tilslutning af et repository, administration af runners, fejlfinding | Vejledninger er skrevet ([tilslutning](Onboarding.da), [fejlfinding](Troubleshooting.da)); scoped levering til alle fire organisationers repositories er verificeret (MIL-002) | | Tilslutning af et repository, administration af runners, fejlfinding | Vejledninger er skrevet ([tilslutning](Onboarding.da), [fejlfinding](Troubleshooting.da)); scoped levering til alle fire organisationers repositories er verificeret (MIL-002) |
| Publicering af et repositorys wiki fra `docs/wiki/` gennem et kaldt workflow | Implementeret som det genbrugelige workflow `.gitea/workflows/publish-wiki-pages.yml`, med offline-tests; kaldt af hvert repository, der publicerer en wiki, og dette repositorys egen wiki er i `docs/wiki/` (MIL-008, MIL-009) | | Publicering af et repositorys wiki fra `docs/wiki/` gennem et kaldt workflow | Implementeret som det scoped workflow `.gitea/scoped_workflows/publish-wiki-pages.yml`, med offline-tests; det kører i hvert repository med en `docs/wiki/`-mappe, og dette repositorys egen wiki er i `docs/wiki/` (MIL-008, MIL-009) |
| Fælles kvalitetskontrol (Python og shell) | Implementeret som det genbrugelige workflow `.gitea/workflows/quality-checks.yml`, med offline-tests og et forsøg i en anden organisation; taget i brug i RepoFoundry ([vejledning](QualityChecksPythonShell.da)) | | Fælles kvalitetskontrol (Python og shell) | Implementeret som det genbrugelige workflow `.gitea/workflows/quality-checks.yml`, med offline-tests og et forsøg i en anden organisation; taget i brug i RepoFoundry ([vejledning](QualityChecksPythonShell.da)) |
| Fælles kvalitetskontrol (C og C++, C#) | Implementeret som de genbrugelige workflows `.gitea/workflows/quality-checks-cpp.yml` og `.gitea/workflows/quality-checks-csharp.yml` med præcise værktøjsversioner og offline-tests; endnu ikke brugt i et andet repository (MIL-007) ([vejledning til C og C++](QualityChecksCpp.da), [vejledning til C#](QualityChecksCSharp.da)) | | Fælles kvalitetskontrol (C og C++, C#) | Implementeret som de genbrugelige workflows `.gitea/workflows/quality-checks-cpp.yml` og `.gitea/workflows/quality-checks-csharp.yml` med præcise værktøjsversioner og offline-tests; endnu ikke brugt i et andet repository (MIL-007) ([vejledning til C og C++](QualityChecksCpp.da), [vejledning til C#](QualityChecksCSharp.da)) |
| Kodemålinger og dækningsbadges | Implementeret og udgivet i 2.1.0 som det genbrugelige workflow `.gitea/workflows/code-metrics.yml` med en tæller, en Cobertura-læser, en SVG-renderer og offline-tests; afprøvet i et kasserepository, endnu ikke brugt i et projektrepository (MIL-010) ([vejledning](CodeMetrics.da)) | | Kodemålinger og dækningsbadges | Implementeret og udgivet i 2.1.0 som det genbrugelige workflow `.gitea/workflows/code-metrics.yml` med en tæller, en Cobertura-læser, en SVG-renderer og offline-tests; afprøvet i et kasserepository, endnu ikke brugt i et projektrepository (MIL-010) ([vejledning](CodeMetrics.da)) |
docs/wiki/Capabilities.md
+1 -1
View File
@@ -13,7 +13,7 @@ Rows that say Implemented or Guides written exist today. The rest is planned and
| Synchronize repository metadata (Gitea to GitHub mirror) | Implemented in `.gitea/scoped_workflows/`, with offline tests and a validation workflow | | Synchronize repository metadata (Gitea to GitHub mirror) | Implemented in `.gitea/scoped_workflows/`, with offline tests and a validation workflow |
| Configure and validate workflow credentials | Implemented for the sync workflow: preflight checks both tokens before any change ([guide](Credentials)) | | Configure and validate workflow credentials | Implemented for the sync workflow: preflight checks both tokens before any change ([guide](Credentials)) |
| Onboard a repository, manage runners, diagnose failures | Guides written ([onboarding](Onboarding), [troubleshooting](Troubleshooting)); scoped delivery to the repositories of all four organizations verified (MIL-002) | | Onboard a repository, manage runners, diagnose failures | Guides written ([onboarding](Onboarding), [troubleshooting](Troubleshooting)); scoped delivery to the repositories of all four organizations verified (MIL-002) |
| Publish a repository wiki from `docs/wiki/` through a called workflow | Implemented as the reusable workflow `.gitea/workflows/publish-wiki-pages.yml`, with offline tests; called by every repository that publishes a wiki, and this repository's own wiki is in `docs/wiki/` (MIL-008, MIL-009) | | Publish a repository wiki from `docs/wiki/` through a called workflow | Implemented as the scoped workflow `.gitea/scoped_workflows/publish-wiki-pages.yml`, with offline tests; it runs in every repository that has a `docs/wiki/` folder, and this repository's own wiki is in `docs/wiki/` (MIL-008, MIL-009) |
| Shared quality checks (Python and shell) | Implemented as the reusable workflow `.gitea/workflows/quality-checks.yml`, with offline tests and a trial in a second organization; adopted in RepoFoundry ([guide](QualityChecksPythonShell)) | | Shared quality checks (Python and shell) | Implemented as the reusable workflow `.gitea/workflows/quality-checks.yml`, with offline tests and a trial in a second organization; adopted in RepoFoundry ([guide](QualityChecksPythonShell)) |
| Shared quality checks (C and C++, C#) | Implemented as the reusable workflows `.gitea/workflows/quality-checks-cpp.yml` and `.gitea/workflows/quality-checks-csharp.yml` with exact tool versions and offline tests; not yet used in another repository (MIL-007) ([C and C++ guide](QualityChecksCpp), [C# guide](QualityChecksCSharp)) | | Shared quality checks (C and C++, C#) | Implemented as the reusable workflows `.gitea/workflows/quality-checks-cpp.yml` and `.gitea/workflows/quality-checks-csharp.yml` with exact tool versions and offline tests; not yet used in another repository (MIL-007) ([C and C++ guide](QualityChecksCpp), [C# guide](QualityChecksCSharp)) |
| Code metrics and coverage badges | Implemented and released in 2.1.0 as the reusable workflow `.gitea/workflows/code-metrics.yml` with a counter, a Cobertura reader, an SVG renderer and offline tests; tried in a throwaway repository, not yet used in a project repository (MIL-010) ([guide](CodeMetrics)) | | Code metrics and coverage badges | Implemented and released in 2.1.0 as the reusable workflow `.gitea/workflows/code-metrics.yml` with a counter, a Cobertura reader, an SVG renderer and offline tests; tried in a throwaway repository, not yet used in a project repository (MIL-010) ([guide](CodeMetrics)) |
docs/wiki/Capabilities.ms.md
+2 -2
View File
@@ -1,4 +1,4 @@
<!-- translation of Capabilities.md, source sha256 b09c3b44caec --> <!-- translation of Capabilities.md, source sha256 2f30825f19a1 -->
> Ini ialah terjemahan [`Capabilities`](Capabilities). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya. > Ini ialah terjemahan [`Capabilities`](Capabilities). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
@@ -13,7 +13,7 @@ Baris yang menyatakan Dilaksanakan atau Panduan telah ditulis wujud hari ini. Se
| Menyegerakkan metadata repositori (Gitea ke cermin GitHub) | Dilaksanakan dalam `.gitea/scoped_workflows/`, dengan ujian luar talian dan aliran kerja pengesahan | | Menyegerakkan metadata repositori (Gitea ke cermin GitHub) | Dilaksanakan dalam `.gitea/scoped_workflows/`, dengan ujian luar talian dan aliran kerja pengesahan |
| Mengkonfigur dan mengesahkan kelayakan (credentials) aliran kerja | Dilaksanakan untuk aliran kerja penyegerakan: semakan awal (preflight) memeriksa kedua-dua token sebelum sebarang perubahan ([panduan](Credentials.ms)) | | Mengkonfigur dan mengesahkan kelayakan (credentials) aliran kerja | Dilaksanakan untuk aliran kerja penyegerakan: semakan awal (preflight) memeriksa kedua-dua token sebelum sebarang perubahan ([panduan](Credentials.ms)) |
| Menyertakan repositori, mengurus runner, mendiagnosis kegagalan | Panduan telah ditulis ([menyertakan repositori](Onboarding.ms), [diagnosis](Troubleshooting.ms)); penghantaran scoped ke repositori keempat-empat organisasi telah disahkan (MIL-002) | | Menyertakan repositori, mengurus runner, mendiagnosis kegagalan | Panduan telah ditulis ([menyertakan repositori](Onboarding.ms), [diagnosis](Troubleshooting.ms)); penghantaran scoped ke repositori keempat-empat organisasi telah disahkan (MIL-002) |
| Menerbitkan wiki repositori daripada `docs/wiki/` melalui aliran kerja yang dipanggil | Dilaksanakan sebagai aliran kerja boleh guna semula `.gitea/workflows/publish-wiki-pages.yml`, dengan ujian luar talian; dipanggil oleh setiap repositori yang menerbitkan wiki, dan wiki repositori ini sendiri ada dalam `docs/wiki/` (MIL-008, MIL-009) | | Menerbitkan wiki repositori daripada `docs/wiki/` melalui aliran kerja yang dipanggil | Dilaksanakan sebagai aliran kerja scoped `.gitea/scoped_workflows/publish-wiki-pages.yml`, dengan ujian luar talian; ia berjalan dalam setiap repositori yang mempunyai folder `docs/wiki/`, dan wiki repositori ini sendiri ada dalam `docs/wiki/` (MIL-008, MIL-009) |
| Semakan kualiti bersama (Python dan shell) | Dilaksanakan sebagai aliran kerja boleh guna semula `.gitea/workflows/quality-checks.yml`, dengan ujian luar talian dan percubaan dalam organisasi kedua; digunakan dalam RepoFoundry ([panduan](QualityChecksPythonShell.ms)) | | Semakan kualiti bersama (Python dan shell) | Dilaksanakan sebagai aliran kerja boleh guna semula `.gitea/workflows/quality-checks.yml`, dengan ujian luar talian dan percubaan dalam organisasi kedua; digunakan dalam RepoFoundry ([panduan](QualityChecksPythonShell.ms)) |
| Semakan kualiti bersama (C dan C++, C#) | Dilaksanakan sebagai aliran kerja boleh guna semula `.gitea/workflows/quality-checks-cpp.yml` dan `.gitea/workflows/quality-checks-csharp.yml` dengan versi alat yang tepat dan ujian luar talian; belum digunakan dalam repositori lain (MIL-007) ([panduan C dan C++](QualityChecksCpp.ms), [panduan C#](QualityChecksCSharp.ms)) | | Semakan kualiti bersama (C dan C++, C#) | Dilaksanakan sebagai aliran kerja boleh guna semula `.gitea/workflows/quality-checks-cpp.yml` dan `.gitea/workflows/quality-checks-csharp.yml` dengan versi alat yang tepat dan ujian luar talian; belum digunakan dalam repositori lain (MIL-007) ([panduan C dan C++](QualityChecksCpp.ms), [panduan C#](QualityChecksCSharp.ms)) |
| Metrik kod dan lencana liputan | Dilaksanakan dan diterbitkan dalam 2.1.0 sebagai aliran kerja boleh guna semula `.gitea/workflows/code-metrics.yml` dengan pengira, pembaca Cobertura, pemaparan SVG dan ujian luar talian; dicuba dalam repositori sekali pakai, belum digunakan dalam repositori projek (MIL-010) ([panduan](CodeMetrics.ms)) | | Metrik kod dan lencana liputan | Dilaksanakan dan diterbitkan dalam 2.1.0 sebagai aliran kerja boleh guna semula `.gitea/workflows/code-metrics.yml` dengan pengira, pembaca Cobertura, pemaparan SVG dan ujian luar talian; dicuba dalam repositori sekali pakai, belum digunakan dalam repositori projek (MIL-010) ([panduan](CodeMetrics.ms)) |
docs/wiki/Credentials.da.md
+6 -6
View File
@@ -1,4 +1,4 @@
<!-- translation of Credentials.md, source sha256 2e92f2344756 --> <!-- translation of Credentials.md, source sha256 0e3225fcefe0 -->
> Dette er en oversættelse af [`Credentials`](Credentials). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres. > Dette er en oversættelse af [`Credentials`](Credentials). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
@@ -56,17 +56,17 @@ Ved succes står der i loggen `Preflight passed: Gitea and GitHub accepted the c
## Secret til publicering af wiki ## Secret til publicering af wiki
Workflowet **Publish wiki pages** kopierer `docs/wiki/` til Gitea-wikien i et repository, der kalder det (se [onboarding.md](Onboarding.da)). Det bruger sin egen secret, så synkroniseringstokenet forbliver skrivebeskyttet. Kalderen sender secreten i `secrets:`; den nedarves ikke. Workflowet **Publish wiki pages** kopierer `docs/wiki/` til Gitea-wikien i et repository, der har en `docs/wiki/`-mappe (se [onboarding.md](Onboarding.da)). Det bruger sin egen secret, så synkroniseringstokenet forbliver skrivebeskyttet.
| Secret | Indhold | Bruges til | | Secret | Indhold | Bruges til |
| --- | --- | --- | | --- | --- | --- |
| `TOKEN_FOR_GITEA_WIKI` | Gitea-tokenet, intet andet | At skrive wikisiderne for de repositories i en organisation, der melder sig til | | `TOKEN_FOR_GITEA_WIKI` | Gitea-tokenet, intet andet | At skrive wikisiderne for de repositories i en organisation, der har en `docs/wiki/`-mappe |
- Gem den som en secret i organisationen for hvert repository, der publicerer. Der er ingen reserve til `TOKEN_FOR_GITEA`: et repository, der kalder workflowet og ikke har secreten, fejler med en konfigurationsfejl, og et repository, der ikke kalder det, behøver den ikke. - Gem den som en secret i organisationen for hvert repository, der publicerer. Der er ingen reserve til `TOKEN_FOR_GITEA`: et repository med en `docs/wiki/`-mappe og uden secreten fejler med en konfigurationsfejl, og et repository uden mappen behøver den ikke.
- Tokenet skal have scope `write:repository`, og dets bruger skal have skriveadgang til repositories. Gitea har intet scope kun til wikien, så opret tokenet til en dedikeret bruger. S05 godkender scopet, og S03 gemmer secreten. - Tokenet skal have scope `write:repository`, og dets bruger skal have skriveadgang til repositories. Gitea har intet scope kun til wikien, så opret tokenet til en dedikeret bruger. S05 godkender scopet, og S03 gemmer secreten.
- Kald, der foretages: `GET /repos/{owner}/{repo}`, `GET /repos/{owner}/{repo}/wiki/pages`, `GET`, `POST` og `PATCH /repos/{owner}/{repo}/wiki/...` og, for en side, der ikke længere findes i `docs/wiki/`, `DELETE /repos/{owner}/{repo}/wiki/page/{name}`. - Kald, der foretages: `GET /repos/{owner}/{repo}`, `GET /repos/{owner}/{repo}/wiki/pages`, `GET`, `POST` og `PATCH /repos/{owner}/{repo}/wiki/...` og, for en side, der ikke længere findes i `docs/wiki/`, `DELETE /repos/{owner}/{repo}/wiki/page/{name}` (kun når sletning er slået til, hvilket det scoped workflow ikke gør).
- Wikien skal være aktiveret i repositoryets indstillinger. Workflowet nægter at køre, hvis den ikke er det. - Wikien skal være aktiveret i repositoryets indstillinger. Workflowet nægter at køre, hvis den ikke er det.
- Sider, der findes i `docs/wiki/`, overskrives altid fra den, så en ændring i Gitea's weboverflade går tabt ved næste publicering. Sider, der kun findes i wikien, fjernes kun, når kaldet sætter `prune: "true"`. - Sider, der findes i `docs/wiki/`, overskrives altid fra den, så en ændring i Gitea's weboverflade går tabt ved næste publicering. Sider, der kun findes i wikien, beholdes.
## Udskiftning af et token ## Udskiftning af et token
docs/wiki/Credentials.md
+8 -9
View File
@@ -89,29 +89,28 @@ is ever printed.
## Wiki publishing secret ## Wiki publishing secret
The workflow **Publish wiki pages** copies `docs/wiki/` to the Gitea wiki of a The workflow **Publish wiki pages** copies `docs/wiki/` to the Gitea wiki of a
repository that calls it (see [onboarding.md](Onboarding)). It uses its own repository that has a `docs/wiki/` folder (see [onboarding.md](Onboarding)).
secret, so the metadata sync token stays read-only. The caller passes the It uses its own secret, so the metadata sync token stays read-only.
secret in `secrets:`; it is not inherited.
| Secret | Content | Used for | | Secret | Content | Used for |
| --- | --- | --- | | --- | --- | --- |
| `TOKEN_FOR_GITEA_WIKI` | The Gitea token, nothing else | Writing the wiki pages of the repositories of an organization that opt in | | `TOKEN_FOR_GITEA_WIKI` | The Gitea token, nothing else | Writing the wiki pages of the repositories of an organization that have a `docs/wiki/` folder |
- Store it as a secret of the organization of each repository that publishes. - Store it as a secret of the organization of each repository that publishes.
There is no fallback to `TOKEN_FOR_GITEA`: a repository that calls the There is no fallback to `TOKEN_FOR_GITEA`: a repository with a
workflow and has no such secret fails with a configuration error, and a `docs/wiki/` folder and no such secret fails with a configuration error, and a
repository that does not call it does not need it. repository without the folder does not need it.
- The token needs scope `write:repository`, and its user needs write access to - The token needs scope `write:repository`, and its user needs write access to
the repositories. Gitea has no wiki-only scope, so create the token for a the repositories. Gitea has no wiki-only scope, so create the token for a
dedicated user. S05 approves the scope and S03 stores the secret. dedicated user. S05 approves the scope and S03 stores the secret.
- Calls made: `GET /repos/{owner}/{repo}`, `GET /repos/{owner}/{repo}/wiki/pages`, - Calls made: `GET /repos/{owner}/{repo}`, `GET /repos/{owner}/{repo}/wiki/pages`,
`GET`, `POST` and `PATCH /repos/{owner}/{repo}/wiki/...` and, for a page that `GET`, `POST` and `PATCH /repos/{owner}/{repo}/wiki/...` and, for a page that
no longer exists in `docs/wiki/`, `DELETE /repos/{owner}/{repo}/wiki/page/{name}`. no longer exists in `docs/wiki/`, `DELETE /repos/{owner}/{repo}/wiki/page/{name}` (only when pruning is switched on, which the scoped workflow does not do).
- The wiki must be enabled in the repository settings. The workflow refuses to - The wiki must be enabled in the repository settings. The workflow refuses to
run when it is not. run when it is not.
- Pages that are in `docs/wiki/` are always overwritten from it, so a change - Pages that are in `docs/wiki/` are always overwritten from it, so a change
made in the Gitea web UI is lost on the next publish. Pages that are only in made in the Gitea web UI is lost on the next publish. Pages that are only in
the wiki are removed only when the call sets `prune: "true"`. the wiki are kept.
## Rotating a token ## Rotating a token
docs/wiki/Credentials.ms.md
+6 -6
View File
@@ -1,4 +1,4 @@
<!-- translation of Credentials.md, source sha256 2e92f2344756 --> <!-- translation of Credentials.md, source sha256 0e3225fcefe0 -->
> Ini ialah terjemahan [`Credentials`](Credentials). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya. > Ini ialah terjemahan [`Credentials`](Credentials). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
@@ -56,17 +56,17 @@ Apabila berjaya, log menyatakan `Preflight passed: Gitea and GitHub accepted the
## Secret untuk menerbitkan wiki ## Secret untuk menerbitkan wiki
Aliran kerja **Publish wiki pages** menyalin `docs/wiki/` ke wiki Gitea bagi repositori yang memanggilnya (lihat [onboarding.md](Onboarding.ms)). Ia menggunakan secret sendiri, supaya token penyegerakan metadata kekal baca sahaja. Pemanggil menghantar secret dalam `secrets:`; ia tidak diwarisi. Aliran kerja **Publish wiki pages** menyalin `docs/wiki/` ke wiki Gitea bagi repositori yang mempunyai folder `docs/wiki/` (lihat [onboarding.md](Onboarding.ms)). Ia menggunakan secret sendiri, supaya token penyegerakan metadata kekal baca sahaja.
| Secret | Kandungan | Digunakan untuk | | Secret | Kandungan | Digunakan untuk |
| --- | --- | --- | | --- | --- | --- |
| `TOKEN_FOR_GITEA_WIKI` | Token Gitea, tiada yang lain | Menulis halaman wiki bagi repositori dalam organisasi yang memilih menyertainya | | `TOKEN_FOR_GITEA_WIKI` | Token Gitea, tiada yang lain | Menulis halaman wiki bagi repositori dalam organisasi yang mempunyai folder `docs/wiki/` |
- Simpan sebagai secret organisasi bagi setiap repositori yang menerbitkan. Tiada sandaran kepada `TOKEN_FOR_GITEA`: repositori yang memanggil aliran kerja dan tidak mempunyai secret itu gagal dengan ralat konfigurasi, dan repositori yang tidak memanggilnya tidak memerlukannya. - Simpan sebagai secret organisasi bagi setiap repositori yang menerbitkan. Tiada sandaran kepada `TOKEN_FOR_GITEA`: repositori yang mempunyai folder `docs/wiki/` tanpa secret itu gagal dengan ralat konfigurasi, dan repositori tanpa folder itu tidak memerlukannya.
- Token mesti mempunyai skop `write:repository`, dan penggunanya mesti mempunyai akses tulis kepada repositori. Gitea tidak mempunyai skop untuk wiki sahaja, jadi cipta token untuk pengguna khusus. S05 meluluskan skop dan S03 menyimpan secret. - Token mesti mempunyai skop `write:repository`, dan penggunanya mesti mempunyai akses tulis kepada repositori. Gitea tidak mempunyai skop untuk wiki sahaja, jadi cipta token untuk pengguna khusus. S05 meluluskan skop dan S03 menyimpan secret.
- Panggilan yang dibuat: `GET /repos/{owner}/{repo}`, `GET /repos/{owner}/{repo}/wiki/pages`, `GET`, `POST` dan `PATCH /repos/{owner}/{repo}/wiki/...` dan, bagi halaman yang tidak lagi wujud dalam `docs/wiki/`, `DELETE /repos/{owner}/{repo}/wiki/page/{name}`. - Panggilan yang dibuat: `GET /repos/{owner}/{repo}`, `GET /repos/{owner}/{repo}/wiki/pages`, `GET`, `POST` dan `PATCH /repos/{owner}/{repo}/wiki/...` dan, bagi halaman yang tidak lagi wujud dalam `docs/wiki/`, `DELETE /repos/{owner}/{repo}/wiki/page/{name}` (hanya apabila pemadaman dihidupkan, yang tidak dilakukan oleh aliran kerja scoped).
- Wiki mesti diaktifkan dalam tetapan repositori. Aliran kerja enggan berjalan jika ia tidak diaktifkan. - Wiki mesti diaktifkan dalam tetapan repositori. Aliran kerja enggan berjalan jika ia tidak diaktifkan.
- Halaman yang ada dalam `docs/wiki/` sentiasa ditimpa daripadanya, jadi perubahan yang dibuat dalam antara muka web Gitea hilang pada penerbitan seterusnya. Halaman yang hanya ada dalam wiki dibuang hanya apabila panggilan menetapkan `prune: "true"`. - Halaman yang ada dalam `docs/wiki/` sentiasa ditimpa daripadanya, jadi perubahan yang dibuat dalam antara muka web Gitea hilang pada penerbitan seterusnya. Halaman yang hanya ada dalam wiki dikekalkan.
## Menukar token ## Menukar token
docs/wiki/Home.da.md
+21 -62
View File
@@ -1,4 +1,4 @@
<!-- translation of Home.md, source sha256 f726872da8b9 --> <!-- translation of Home.md, source sha256 3bb705987743 -->
> Dette er en oversættelse af [`Home`](Home). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres. > Dette er en oversættelse af [`Home`](Home). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
@@ -13,23 +13,22 @@ En samling af genbrugelige Gitea Actions-workflows til DevOps-professionelle og
Dette repository er den centrale samling af genbrugelig automatisering til TirSystems repositories. Det primære repository ligger på `git.tirsystem.com` (Gitea) og spejles med push til GitHub. Dette repository er den centrale samling af genbrugelig automatisering til TirSystems repositories. Det primære repository ligger på `git.tirsystem.com` (Gitea) og spejles med push til GitHub.
Det indeholder elleve workflows: synkronisering af metadata til GitHub-spejlet, publicering af wiki (kaldt af hvert repository), fælles kvalitetskontrol for Python og shell, for C og C++ og for C#, kodemålinger og dækningsbadges, en kontrol af, at kommentarer er på engelsk, et udgivelsesworkflow, publicering af accepterede milepæle og repositoryets egen validering. De er listet med formål og diagram under [Workflows](#workflows). Det indeholder ti workflows: synkronisering af metadata til GitHub-spejlet, publicering af wiki (scoped, for hvert repository med en `docs/wiki/`-mappe), fælles kvalitetskontrol for Python og shell, for C og C++ og for C#, kodemålinger og dækningsbadges, en kontrol af, at kommentarer er på engelsk, et udgivelsesworkflow, publicering af accepterede milepæle og repositoryets egen validering. De er listet med formål og diagram under [Workflows](#workflows).
## Workflows ## Workflows
Der er elleve workflows i dette repository. Et **scoped** workflow leveres af instansen til alle repositories i TirSystem-organisationerne og kræver intet i repositoryet; et **genbrugeligt** workflow kaldes fra et repository med `uses:`; de øvrige kører kun her. Diagrammerne er PlantUML-kildekode og er på engelsk. Der er ti workflows i dette repository. Et **scoped** workflow leveres af instansen til alle repositories i TirSystem-organisationerne og kræver intet i repositoryet; et **genbrugeligt** workflow kaldes fra et repository med `uses:`; de øvrige kører kun her. Diagrammerne er PlantUML-kildekode og er på engelsk.
| Workflow | Fil | Type | Starter ved | Formål | | Workflow | Fil | Type | Starter ved | Formål |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
| Sync GitHub mirror metadata | [`sync-github-metadata.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/scoped_workflows/sync-github-metadata.yml) | Scoped | push til `main`, manuelt, dagligt kl. 03:17 UTC | Kopierer beskrivelsen og emnerne for et Gitea-repository til dets GitHub push-spejl | | Sync GitHub mirror metadata | [`sync-github-metadata.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/scoped_workflows/sync-github-metadata.yml) | Scoped | push til `main`, manuelt, dagligt kl. 03:17 UTC | Kopierer beskrivelsen og emnerne for et Gitea-repository til dets GitHub push-spejl |
| Publish wiki pages | [`publish-wiki-pages.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/publish-wiki-pages.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Publicerer siderne i `docs/wiki/` (eller den mappe, `wiki_dir` angiver) til wikien i det kaldende repository | | Publish wiki pages | [`publish-wiki-pages.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/scoped_workflows/publish-wiki-pages.yml) | Scoped | push til `main`, der ændrer `docs/wiki/**`, manuelt | Publicerer siderne i `docs/wiki/` til repositoryets wiki; springes over, hvor mappen ikke findes |
| Quality checks | [`quality-checks.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Kører ruff, mypy, shellcheck og shfmt på de sporede filer og ændrer intet | | Quality checks | [`quality-checks.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Kører ruff, mypy, shellcheck og shfmt på de sporede filer og ændrer intet |
| Quality checks C++ | [`quality-checks-cpp.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks-cpp.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Kører clang-format og clang-tidy i præcise versioner på de sporede C- og C++-filer og ændrer intet | | Quality checks C++ | [`quality-checks-cpp.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks-cpp.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Kører clang-format og clang-tidy i præcise versioner på de sporede C- og C++-filer og ændrer intet |
| Quality checks C# | [`quality-checks-csharp.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks-csharp.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Kører `dotnet format` og `dotnet build` på et præcist .NET SDK 10 eller nyere og ændrer intet | | Quality checks C# | [`quality-checks-csharp.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks-csharp.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Kører `dotnet format` og `dotnet build` på et præcist .NET SDK 10 eller nyere og ændrer intet |
| Code metrics | [`code-metrics.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/code-metrics.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Tæller kodefilerne og kodelinjerne (uden kommentar- og tomme linjer), læser en Cobertura-dækningsrapport og committer tre SVG-badges til en `badges`-gren | | Code metrics | [`code-metrics.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/code-metrics.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Tæller kodefilerne og kodelinjerne (uden kommentar- og tomme linjer), læser en Cobertura-dækningsrapport og committer tre SVG-badges til en `badges`-gren |
| English comments | [`english-comments.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/english-comments.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository, på en pull request | Bedømmer sproget i de kommentarer og docstrings, en pull request tilføjer, lader kørslen fejle, når én ikke er engelsk, og skriver én kommentar på pull requesten, der nævner forfatteren | | English comments | [`english-comments.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/english-comments.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository, på en pull request | Bedømmer sproget i de kommentarer og docstrings, en pull request tilføjer, lader kørslen fejle, når én ikke er engelsk, og skriver én kommentar på pull requesten, der nævner forfatteren |
| Publish own wiki | [`publish-own-wiki.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/publish-own-wiki.yml) | Kun dette repository | push til `main`, der ændrer `docs/wiki/**`, manuelt | Kalder det genbrugelige workflow Publish wiki pages for dette repositorys wiki |
| Release | [`release.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/release.yml) | Kun dette repository | manuelt | Opretter versionstagget, udgivelsessiden og major-tagget efter kontrollerne | | Release | [`release.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/release.yml) | Kun dette repository | manuelt | Opretter versionstagget, udgivelsessiden og major-tagget efter kontrollerne |
| Publicering af accepterede milepæle | [`sync-milestones.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/sync-milestones.yml) | Kun dette repository | push til `main`, der ændrer `docs/milestones/**` eller `docs/sqa/reviews/**`, manuelt (tørkørsel som standard) | Opretter eller opdaterer Gitea-milepælen og issues for hver milepæl, der er Accepted med en Go-gennemgang | | Publicering af accepterede milepæle | [`sync-milestones.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/sync-milestones.yml) | Kun dette repository | push til `main`, der ændrer `docs/milestones/**` eller `docs/sqa/reviews/**`, manuelt (tørkørsel som standard) | Opretter eller opdaterer Gitea-milepælen og issues for hver milepæl, der er Accepted med en Go-gennemgang |
| Validate workflows | [`validate-workflows.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/validate-workflows.yml) | Kun dette repository | pull request, push til `main`, manuelt | Læser hvert workflow som YAML og kører offline-testene | | Validate workflows | [`validate-workflows.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/validate-workflows.yml) | Kun dette repository | pull request, push til `main`, manuelt | Læser hvert workflow som YAML og kører offline-testene |
@@ -371,88 +370,48 @@ deactivate Workflow
### Publicering af wiki-sider ### Publicering af wiki-sider
Et genbrugeligt workflow (ADR-0009). Et repository kalder det fra sit eget workflow, så selve kaldet er tilmeldingen, og der behøves ingen markørfil. Det publicerer Markdown-siderne i `wiki_dir` (standard `docs/wiki`) til wikien i det kaldende repository og sletter kun sider, der ikke findes i mappen, når `prune` er `true`. Et scoped workflow: instansen kører det i hvert repository i organisationen, så der behøves hverken et kald eller en markørfil. Et repository tilmelder sig ved at have en `docs/wiki`-mappe; hvor der ingen er, slutter kørslen uden at gøre noget. Det publicerer Markdown-siderne i `docs/wiki` til repositoryets wiki og beholder de wiki-sider, der ikke findes i mappen. Det kræver organisationens secret `TOKEN_FOR_GITEA_WIKI`.
```yaml
on:
push:
branches: [ main ]
paths: [ "docs/wiki/**" ]
jobs:
wiki:
uses: TirSystem/git-workflows/.gitea/workflows/publish-wiki-pages.yml@v1
secrets:
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
```
#### Workflow #### Workflow
```plantuml ```plantuml
@startuml @startuml
title Publish docs/wiki to the wiki of the calling repository title Publish docs/wiki to the wiki of the repository
autonumber autonumber
actor "Calling repository\nuses: ...publish-wiki-pages.yml@v1" as Caller actor "Push to main that changes docs/wiki/**,\nor manual trigger" as Trigger
participant "Gitea Actions\npublish-wiki-pages" as Workflow participant "Gitea Actions\npublish-wiki-pages" as Workflow
participant "shared-scripts\n(tools/publish_wiki.py at tools-ref)" as Script participant "shared-scripts\n(tools/publish_wiki.py at v2)" as Script
participant "Gitea wiki API" as Wiki participant "Gitea wiki API" as Wiki
Caller -> Workflow: Call with wiki_dir, prune and the secret Trigger -> Workflow: Start workflow
activate Workflow activate Workflow
Workflow -> Script: Check out the repository and the script, run it Workflow -> Workflow: Check out the repository
activate Script
alt wiki_dir does not exist, or has no Markdown pages alt docs/wiki does not exist
Script --> Workflow: Fail with [configuration]\n(an empty folder never deletes pages) Workflow --> Trigger: Nothing to publish
else else
Script -> Script: Read prune and TOKEN_FOR_GITEA_WIKI Workflow -> Script: Fetch the script, run it
activate Script
alt docs/wiki has no Markdown pages
Script --> Workflow: Fail with [configuration]\n(an empty folder never deletes pages)
else
Script -> Script: Read TOKEN_FOR_GITEA_WIKI
Script -> Wiki: GET repository (preflight) Script -> Wiki: GET repository (preflight)
Wiki --> Script: Wiki is enabled, token accepted Wiki --> Script: Wiki is enabled, token accepted
Script -> Wiki: GET pages Script -> Wiki: GET pages
Wiki --> Script: Existing pages Wiki --> Script: Existing pages
Script -> Wiki: Create new pages, update changed pages Script -> Wiki: Create new pages, update changed pages
opt prune is true Script --> Workflow: Log created and updated counts
Script -> Wiki: Delete pages that are not in wiki_dir
end end
Script --> Workflow: Log created, updated and deleted counts deactivate Script
Workflow --> Trigger: Workflow result
end end
deactivate Script
Workflow --> Caller: Workflow result
deactivate Workflow deactivate Workflow
@enduml @enduml
``` ```
### Publicering af egen wiki
Dette repositorys wiki er `docs/wiki/`. Workflowet kalder det genbrugelige workflow ovenfor med dets lokale sti, med `prune` sat til `true`, så wikien altid er lig med mappen, og `tools-ref` sat til `main`, så scriptet fra samme commit kører. Det er den kalder, et projekt kopierer fra frameworkets `templates/ci/publish-wiki.yml`.
#### Workflow
```plantuml
@startuml
title Publish the wiki of this repository (docs/wiki)
autonumber
actor "Push to main that changes docs/wiki/**,\nor manual trigger" as Trigger
participant "Gitea Actions\npublish-own-wiki" as Caller
participant "Gitea Actions\npublish-wiki-pages\n(called by its local path)" as Workflow
participant "Gitea wiki API" as Wiki
Trigger -> Caller: Start workflow
activate Caller
Caller -> Workflow: Call with wiki_dir docs/wiki, prune true,\ntools-ref main and TOKEN_FOR_GITEA_WIKI
activate Workflow
Workflow -> Wiki: Create, update and delete pages\nso the wiki equals docs/wiki
Wiki --> Workflow: Done
Workflow --> Caller: Workflow result
deactivate Workflow
Caller --> Trigger: Workflow result
deactivate Caller
@enduml
```
### Publicering af accepterede milepæle ### Publicering af accepterede milepæle
Permanent tilladelse til at publicere: ved et push til `main`, der ændrer milepælene eller deres gennemgange, oprettes eller opdateres hver milepæl, hvis seneste række i Version History er Accepted, og hvis seneste gennemgang er en Go, på Gitea med sine opgaver som issues. Intet lukkes eller slettes. En manuel kørsel er en tørkørsel, medmindre `dry_run` slås fra. Det bruger secret'en `TOKEN_FOR_GITEA` og `--accepted-only`-reglen i det monterede framework (v0.5.0 eller nyere). Permanent tilladelse til at publicere: ved et push til `main`, der ændrer milepælene eller deres gennemgange, oprettes eller opdateres hver milepæl, hvis seneste række i Version History er Accepted, og hvis seneste gennemgang er en Go, på Gitea med sine opgaver som issues. Intet lukkes eller slettes. En manuel kørsel er en tørkørsel, medmindre `dry_run` slås fra. Det bruger secret'en `TOKEN_FOR_GITEA` og `--accepted-only`-reglen i det monterede framework (v0.5.0 eller nyere).
docs/wiki/Home.md
+25 -62
View File
@@ -13,25 +13,24 @@ A collection of reusable Gitea Actions workflows for DevOps professionals and so
This repository is the central collection of reusable automation for TirSystem repositories. The primary repository lives at `git.tirsystem.com` (Gitea) and is push-mirrored to GitHub. This repository is the central collection of reusable automation for TirSystem repositories. The primary repository lives at `git.tirsystem.com` (Gitea) and is push-mirrored to GitHub.
It contains eleven workflows: metadata sync to the GitHub mirror, wiki publishing (called by each repository), shared quality checks for Python and shell, for C and C++ and for C#, code metrics and coverage badges, a check that comments are in English, a release workflow, the publishing of accepted milestones and the repository's own validation. They are listed with their purpose and a diagram under [Workflows](#workflows). It contains ten workflows: metadata sync to the GitHub mirror, wiki publishing (scoped, for every repository with a `docs/wiki/` folder), shared quality checks for Python and shell, for C and C++ and for C#, code metrics and coverage badges, a check that comments are in English, a release workflow, the publishing of accepted milestones and the repository's own validation. They are listed with their purpose and a diagram under [Workflows](#workflows).
## Workflows ## Workflows
When a repository should use each workflow in its SQA and QC is set out in the [adoption rules](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/guides/adoption-rules.md). When a repository should use each workflow in its SQA and QC is set out in the [adoption rules](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/guides/adoption-rules.md).
Eleven workflows live in this repository. A **scoped** workflow is delivered by the instance to every repository of the TirSystem organizations and needs nothing in the repository; a **reusable** workflow is called by a repository with `uses:`; the others run only here. The diagrams are PlantUML source. Ten workflows live in this repository. A **scoped** workflow is delivered by the instance to every repository of the TirSystem organizations and needs nothing in the repository; a **reusable** workflow is called by a repository with `uses:`; the others run only here. The diagrams are PlantUML source.
| Workflow | File | Kind | Starts on | Purpose | | Workflow | File | Kind | Starts on | Purpose |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
| Sync GitHub mirror metadata | [`sync-github-metadata.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/scoped_workflows/sync-github-metadata.yml) | Scoped | push to `main`, manual, daily 03:17 UTC | Copies the description and topics of a Gitea repository to its GitHub push mirror | | Sync GitHub mirror metadata | [`sync-github-metadata.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/scoped_workflows/sync-github-metadata.yml) | Scoped | push to `main`, manual, daily 03:17 UTC | Copies the description and topics of a Gitea repository to its GitHub push mirror |
| Publish wiki pages | [`publish-wiki-pages.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/publish-wiki-pages.yml) | Reusable (`workflow_call`) | a call from another repository | Publishes the pages in `docs/wiki/` (or the folder named by `wiki_dir`) to the wiki of the calling repository | | Publish wiki pages | [`publish-wiki-pages.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/scoped_workflows/publish-wiki-pages.yml) | Scoped | push to `main` that changes `docs/wiki/**`, manual | Publishes the pages in `docs/wiki/` to the wiki of the repository; skipped where the folder does not exist |
| Quality checks | [`quality-checks.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks.yml) | Reusable (`workflow_call`) | a call from another repository | Runs ruff, mypy, shellcheck and shfmt on the tracked files and changes nothing | | Quality checks | [`quality-checks.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks.yml) | Reusable (`workflow_call`) | a call from another repository | Runs ruff, mypy, shellcheck and shfmt on the tracked files and changes nothing |
| Quality checks C++ | [`quality-checks-cpp.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks-cpp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs clang-format and clang-tidy at exact versions on the tracked C and C++ files and changes nothing | | Quality checks C++ | [`quality-checks-cpp.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks-cpp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs clang-format and clang-tidy at exact versions on the tracked C and C++ files and changes nothing |
| Quality checks C# | [`quality-checks-csharp.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks-csharp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs `dotnet format` and `dotnet build` on an exact .NET SDK 10 or later and changes nothing | | Quality checks C# | [`quality-checks-csharp.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks-csharp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs `dotnet format` and `dotnet build` on an exact .NET SDK 10 or later and changes nothing |
| Code metrics | [`code-metrics.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/code-metrics.yml) | Reusable (`workflow_call`) | a call from another repository | Counts the code files and the lines of code (without comment and blank lines), reads a Cobertura coverage report and commits three SVG badges to a `badges` branch | | Code metrics | [`code-metrics.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/code-metrics.yml) | Reusable (`workflow_call`) | a call from another repository | Counts the code files and the lines of code (without comment and blank lines), reads a Cobertura coverage report and commits three SVG badges to a `badges` branch |
| English comments | [`english-comments.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/english-comments.yml) | Reusable (`workflow_call`) | a call from another repository, on a pull request | Judges the language of the comments and docstrings a pull request adds, fails the run when one is not English and writes one comment on the pull request that mentions the author | | English comments | [`english-comments.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/english-comments.yml) | Reusable (`workflow_call`) | a call from another repository, on a pull request | Judges the language of the comments and docstrings a pull request adds, fails the run when one is not English and writes one comment on the pull request that mentions the author |
| Publish own wiki | [`publish-own-wiki.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/publish-own-wiki.yml) | This repository only | push to `main` that changes `docs/wiki/**`, manual | Calls the reusable Publish wiki pages workflow for the wiki of this repository |
| Release | [`release.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/release.yml) | This repository only | manual | Creates the version tag, the release page and the major tag after the checks | | Release | [`release.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/release.yml) | This repository only | manual | Creates the version tag, the release page and the major tag after the checks |
| Publish accepted milestones | [`sync-milestones.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/sync-milestones.yml) | This repository only | push to `main` that changes `docs/milestones/**` or `docs/sqa/reviews/**`, manual (dry run by default) | Creates or updates the Gitea milestone and issues of every milestone that is Accepted with a Go review | | Publish accepted milestones | [`sync-milestones.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/sync-milestones.yml) | This repository only | push to `main` that changes `docs/milestones/**` or `docs/sqa/reviews/**`, manual (dry run by default) | Creates or updates the Gitea milestone and issues of every milestone that is Accepted with a Go review |
| Validate workflows | [`validate-workflows.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/validate-workflows.yml) | This repository only | pull request, push to `main`, manual | Parses every workflow and runs the offline tests | | Validate workflows | [`validate-workflows.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/validate-workflows.yml) | This repository only | pull request, push to `main`, manual | Parses every workflow and runs the offline tests |
@@ -373,88 +372,52 @@ deactivate Workflow
### Publish wiki pages ### Publish wiki pages
A reusable workflow (ADR-0009). A repository calls it from its own workflow, so the call is the opt-in and no marker file is needed. It publishes the Markdown pages of `wiki_dir` (default `docs/wiki`) to the wiki of the calling repository, and deletes pages that are not in the folder only when `prune` is `true`. A scoped workflow: the instance runs it in every repository of the organization, so no call and no marker file is needed. A repository opts in by having a `docs/wiki` folder; where there is none, the run ends without doing anything. It publishes the Markdown pages of `docs/wiki` to the wiki of the repository and keeps the wiki pages that are not in the folder. It needs the organization secret `TOKEN_FOR_GITEA_WIKI`.
```yaml
on:
push:
branches: [ main ]
paths: [ "docs/wiki/**" ]
jobs:
wiki:
uses: TirSystem/git-workflows/.gitea/workflows/publish-wiki-pages.yml@v1
secrets:
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
```
#### Workflow #### Workflow
```plantuml ```plantuml
@startuml @startuml
title Publish docs/wiki to the wiki of the calling repository title Publish docs/wiki to the wiki of the repository
autonumber autonumber
actor "Calling repository\nuses: ...publish-wiki-pages.yml@v1" as Caller actor "Push to main that changes docs/wiki/**,
participant "Gitea Actions\npublish-wiki-pages" as Workflow or manual trigger" as Trigger
participant "shared-scripts\n(tools/publish_wiki.py at tools-ref)" as Script participant "Gitea Actions
publish-wiki-pages" as Workflow
participant "shared-scripts
(tools/publish_wiki.py at v2)" as Script
participant "Gitea wiki API" as Wiki participant "Gitea wiki API" as Wiki
Caller -> Workflow: Call with wiki_dir, prune and the secret Trigger -> Workflow: Start workflow
activate Workflow activate Workflow
Workflow -> Script: Check out the repository and the script, run it Workflow -> Workflow: Check out the repository
activate Script
alt wiki_dir does not exist, or has no Markdown pages alt docs/wiki does not exist
Script --> Workflow: Fail with [configuration]\n(an empty folder never deletes pages) Workflow --> Trigger: Nothing to publish
else else
Script -> Script: Read prune and TOKEN_FOR_GITEA_WIKI Workflow -> Script: Fetch the script, run it
activate Script
alt docs/wiki has no Markdown pages
Script --> Workflow: Fail with [configuration]
(an empty folder never deletes pages)
else
Script -> Script: Read TOKEN_FOR_GITEA_WIKI
Script -> Wiki: GET repository (preflight) Script -> Wiki: GET repository (preflight)
Wiki --> Script: Wiki is enabled, token accepted Wiki --> Script: Wiki is enabled, token accepted
Script -> Wiki: GET pages Script -> Wiki: GET pages
Wiki --> Script: Existing pages Wiki --> Script: Existing pages
Script -> Wiki: Create new pages, update changed pages Script -> Wiki: Create new pages, update changed pages
opt prune is true Script --> Workflow: Log created and updated counts
Script -> Wiki: Delete pages that are not in wiki_dir
end end
Script --> Workflow: Log created, updated and deleted counts deactivate Script
Workflow --> Trigger: Workflow result
end end
deactivate Script
Workflow --> Caller: Workflow result
deactivate Workflow deactivate Workflow
@enduml @enduml
``` ```
### Publish own wiki
The wiki of this repository is `docs/wiki/`. This workflow calls the reusable workflow above by its local path, with `prune` set to `true` so the wiki always equals the folder and `tools-ref` set to `main` so that the script of the same commit runs. It is the caller that a project copies from the framework's `templates/ci/publish-wiki.yml`.
#### Workflow
```plantuml
@startuml
title Publish the wiki of this repository (docs/wiki)
autonumber
actor "Push to main that changes docs/wiki/**,\nor manual trigger" as Trigger
participant "Gitea Actions\npublish-own-wiki" as Caller
participant "Gitea Actions\npublish-wiki-pages\n(called by its local path)" as Workflow
participant "Gitea wiki API" as Wiki
Trigger -> Caller: Start workflow
activate Caller
Caller -> Workflow: Call with wiki_dir docs/wiki, prune true,\ntools-ref main and TOKEN_FOR_GITEA_WIKI
activate Workflow
Workflow -> Wiki: Create, update and delete pages\nso the wiki equals docs/wiki
Wiki --> Workflow: Done
Workflow --> Caller: Workflow result
deactivate Workflow
Caller --> Trigger: Workflow result
deactivate Caller
@enduml
```
### Publish accepted milestones ### Publish accepted milestones
Standing authorization to publish: on a push to `main` that changes the milestones or their reviews, every milestone whose latest Version History row is Accepted and whose latest review is a Go is created or updated on Gitea with its tasks as issues. Nothing is closed or deleted. A manual run is a dry run unless `dry_run` is switched off. It uses the secret `TOKEN_FOR_GITEA` and the `--accepted-only` rule of the mounted framework (v0.5.0 or later). Standing authorization to publish: on a push to `main` that changes the milestones or their reviews, every milestone whose latest Version History row is Accepted and whose latest review is a Go is created or updated on Gitea with its tasks as issues. Nothing is closed or deleted. A manual run is a dry run unless `dry_run` is switched off. It uses the secret `TOKEN_FOR_GITEA` and the `--accepted-only` rule of the mounted framework (v0.5.0 or later).
docs/wiki/Home.ms.md
+21 -62
View File
@@ -1,4 +1,4 @@
<!-- translation of Home.md, source sha256 f726872da8b9 --> <!-- translation of Home.md, source sha256 3bb705987743 -->
> Ini ialah terjemahan [`Home`](Home). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya. > Ini ialah terjemahan [`Home`](Home). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
@@ -13,23 +13,22 @@ Koleksi aliran kerja (workflow) Gitea Actions yang boleh digunakan semula untuk
Repositori ini ialah koleksi pusat bagi automasi yang boleh digunakan semula untuk repositori TirSystem. Repositori utama berada di `git.tirsystem.com` (Gitea) dan dicerminkan dengan push ke GitHub. Repositori ini ialah koleksi pusat bagi automasi yang boleh digunakan semula untuk repositori TirSystem. Repositori utama berada di `git.tirsystem.com` (Gitea) dan dicerminkan dengan push ke GitHub.
Ia mengandungi sebelas aliran kerja: penyegerakan metadata ke cermin GitHub, penerbitan wiki (dipanggil oleh setiap repositori), semakan kualiti bersama untuk Python dan shell, untuk C dan C++ serta untuk C#, metrik kod dan lencana liputan, semakan bahawa komen ditulis dalam bahasa Inggeris, aliran kerja keluaran, penerbitan pencapaian (milestone) yang diterima dan pengesahan repositori sendiri. Ia disenaraikan dengan tujuan dan rajah di bawah [Aliran kerja](#aliran-kerja). Ia mengandungi sepuluh aliran kerja: penyegerakan metadata ke cermin GitHub, penerbitan wiki (scoped, untuk setiap repositori yang mempunyai folder `docs/wiki/`), semakan kualiti bersama untuk Python dan shell, untuk C dan C++ serta untuk C#, metrik kod dan lencana liputan, semakan bahawa komen ditulis dalam bahasa Inggeris, aliran kerja keluaran, penerbitan pencapaian (milestone) yang diterima dan pengesahan repositori sendiri. Ia disenaraikan dengan tujuan dan rajah di bawah [Aliran kerja](#aliran-kerja).
## Aliran kerja ## Aliran kerja
Terdapat sebelas aliran kerja dalam repositori ini. Aliran kerja **scoped** dihantar oleh instans ke setiap repositori organisasi TirSystem dan tidak memerlukan apa-apa dalam repositori; aliran kerja **boleh guna semula** dipanggil oleh sebuah repositori dengan `uses:`; yang lain hanya berjalan di sini. Rajah ialah kod sumber PlantUML dan dalam bahasa Inggeris. Terdapat sepuluh aliran kerja dalam repositori ini. Aliran kerja **scoped** dihantar oleh instans ke setiap repositori organisasi TirSystem dan tidak memerlukan apa-apa dalam repositori; aliran kerja **boleh guna semula** dipanggil oleh sebuah repositori dengan `uses:`; yang lain hanya berjalan di sini. Rajah ialah kod sumber PlantUML dan dalam bahasa Inggeris.
| Aliran kerja | Fail | Jenis | Bermula apabila | Tujuan | | Aliran kerja | Fail | Jenis | Bermula apabila | Tujuan |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
| Sync GitHub mirror metadata | [`sync-github-metadata.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/scoped_workflows/sync-github-metadata.yml) | Scoped | push ke `main`, manual, setiap hari 03:17 UTC | Menyalin penerangan dan topik repositori Gitea ke push mirror GitHub-nya | | Sync GitHub mirror metadata | [`sync-github-metadata.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/scoped_workflows/sync-github-metadata.yml) | Scoped | push ke `main`, manual, setiap hari 03:17 UTC | Menyalin penerangan dan topik repositori Gitea ke push mirror GitHub-nya |
| Publish wiki pages | [`publish-wiki-pages.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/publish-wiki-pages.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Menerbitkan halaman dalam `docs/wiki/` (atau folder yang dinamakan oleh `wiki_dir`) ke wiki repositori pemanggil | | Publish wiki pages | [`publish-wiki-pages.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/scoped_workflows/publish-wiki-pages.yml) | Scoped | push ke `main` yang mengubah `docs/wiki/**`, manual | Menerbitkan halaman dalam `docs/wiki/` ke wiki repositori; dilangkau jika folder itu tiada |
| Quality checks | [`quality-checks.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Menjalankan ruff, mypy, shellcheck dan shfmt pada fail yang dijejaki dan tidak mengubah apa-apa | | Quality checks | [`quality-checks.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Menjalankan ruff, mypy, shellcheck dan shfmt pada fail yang dijejaki dan tidak mengubah apa-apa |
| Quality checks C++ | [`quality-checks-cpp.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks-cpp.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Menjalankan clang-format dan clang-tidy pada versi tepat pada fail C dan C++ yang dijejaki dan tidak mengubah apa-apa | | Quality checks C++ | [`quality-checks-cpp.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks-cpp.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Menjalankan clang-format dan clang-tidy pada versi tepat pada fail C dan C++ yang dijejaki dan tidak mengubah apa-apa |
| Quality checks C# | [`quality-checks-csharp.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks-csharp.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Menjalankan `dotnet format` dan `dotnet build` pada .NET SDK 10 atau lebih baharu yang tepat dan tidak mengubah apa-apa | | Quality checks C# | [`quality-checks-csharp.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/quality-checks-csharp.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Menjalankan `dotnet format` dan `dotnet build` pada .NET SDK 10 atau lebih baharu yang tepat dan tidak mengubah apa-apa |
| Code metrics | [`code-metrics.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/code-metrics.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Mengira fail kod dan baris kod (tanpa baris komen dan baris kosong), membaca laporan liputan Cobertura dan melakukan commit tiga lencana SVG ke cabang `badges` | | Code metrics | [`code-metrics.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/code-metrics.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Mengira fail kod dan baris kod (tanpa baris komen dan baris kosong), membaca laporan liputan Cobertura dan melakukan commit tiga lencana SVG ke cabang `badges` |
| English comments | [`english-comments.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/english-comments.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain, pada pull request | Menilai bahasa komen dan docstring yang ditambah oleh pull request, menggagalkan larian apabila ada yang bukan bahasa Inggeris dan menulis satu komen pada pull request yang menyebut penulisnya | | English comments | [`english-comments.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/english-comments.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain, pada pull request | Menilai bahasa komen dan docstring yang ditambah oleh pull request, menggagalkan larian apabila ada yang bukan bahasa Inggeris dan menulis satu komen pada pull request yang menyebut penulisnya |
| Publish own wiki | [`publish-own-wiki.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/publish-own-wiki.yml) | Repositori ini sahaja | push ke `main` yang mengubah `docs/wiki/**`, manual | Memanggil aliran kerja boleh guna semula Publish wiki pages untuk wiki repositori ini |
| Release | [`release.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/release.yml) | Repositori ini sahaja | manual | Mencipta tag versi, halaman keluaran dan tag major selepas semakan | | Release | [`release.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/release.yml) | Repositori ini sahaja | manual | Mencipta tag versi, halaman keluaran dan tag major selepas semakan |
| Menerbitkan milestone yang diterima | [`sync-milestones.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/sync-milestones.yml) | Repositori ini sahaja | push ke `main` yang mengubah `docs/milestones/**` atau `docs/sqa/reviews/**`, manual (larian percubaan secara lalai) | Mencipta atau mengemas kini milestone Gitea dan isu bagi setiap milestone yang Accepted dengan semakan Go | | Menerbitkan milestone yang diterima | [`sync-milestones.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/sync-milestones.yml) | Repositori ini sahaja | push ke `main` yang mengubah `docs/milestones/**` atau `docs/sqa/reviews/**`, manual (larian percubaan secara lalai) | Mencipta atau mengemas kini milestone Gitea dan isu bagi setiap milestone yang Accepted dengan semakan Go |
| Validate workflows | [`validate-workflows.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/validate-workflows.yml) | Repositori ini sahaja | pull request, push ke `main`, manual | Menghurai setiap aliran kerja sebagai YAML dan menjalankan ujian luar talian | | Validate workflows | [`validate-workflows.yml`](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/.gitea/workflows/validate-workflows.yml) | Repositori ini sahaja | pull request, push ke `main`, manual | Menghurai setiap aliran kerja sebagai YAML dan menjalankan ujian luar talian |
@@ -371,88 +370,48 @@ deactivate Workflow
### Menerbitkan halaman wiki ### Menerbitkan halaman wiki
Aliran kerja boleh guna semula (ADR-0009). Sesebuah repositori memanggilnya daripada aliran kerjanya sendiri, jadi panggilan itu ialah pilihan menyertai dan tiada fail penanda diperlukan. Ia menerbitkan halaman Markdown dalam `wiki_dir` (lalai `docs/wiki`) ke wiki repositori pemanggil, dan memadam halaman yang tiada dalam folder hanya apabila `prune` ialah `true`. Aliran kerja scoped: instans menjalankannya dalam setiap repositori organisasi, jadi tiada panggilan atau fail penanda diperlukan. Sebuah repositori mengikut serta dengan mempunyai folder `docs/wiki`; jika tiada, larian tamat tanpa berbuat apa-apa. Ia menerbitkan halaman Markdown dalam `docs/wiki` ke wiki repositori dan mengekalkan halaman wiki yang tiada dalam folder itu. Ia memerlukan secret organisasi `TOKEN_FOR_GITEA_WIKI`.
```yaml
on:
push:
branches: [ main ]
paths: [ "docs/wiki/**" ]
jobs:
wiki:
uses: TirSystem/git-workflows/.gitea/workflows/publish-wiki-pages.yml@v1
secrets:
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
```
#### Aliran kerja #### Aliran kerja
```plantuml ```plantuml
@startuml @startuml
title Publish docs/wiki to the wiki of the calling repository title Publish docs/wiki to the wiki of the repository
autonumber autonumber
actor "Calling repository\nuses: ...publish-wiki-pages.yml@v1" as Caller actor "Push to main that changes docs/wiki/**,\nor manual trigger" as Trigger
participant "Gitea Actions\npublish-wiki-pages" as Workflow participant "Gitea Actions\npublish-wiki-pages" as Workflow
participant "shared-scripts\n(tools/publish_wiki.py at tools-ref)" as Script participant "shared-scripts\n(tools/publish_wiki.py at v2)" as Script
participant "Gitea wiki API" as Wiki participant "Gitea wiki API" as Wiki
Caller -> Workflow: Call with wiki_dir, prune and the secret Trigger -> Workflow: Start workflow
activate Workflow activate Workflow
Workflow -> Script: Check out the repository and the script, run it Workflow -> Workflow: Check out the repository
activate Script
alt wiki_dir does not exist, or has no Markdown pages alt docs/wiki does not exist
Script --> Workflow: Fail with [configuration]\n(an empty folder never deletes pages) Workflow --> Trigger: Nothing to publish
else else
Script -> Script: Read prune and TOKEN_FOR_GITEA_WIKI Workflow -> Script: Fetch the script, run it
activate Script
alt docs/wiki has no Markdown pages
Script --> Workflow: Fail with [configuration]\n(an empty folder never deletes pages)
else
Script -> Script: Read TOKEN_FOR_GITEA_WIKI
Script -> Wiki: GET repository (preflight) Script -> Wiki: GET repository (preflight)
Wiki --> Script: Wiki is enabled, token accepted Wiki --> Script: Wiki is enabled, token accepted
Script -> Wiki: GET pages Script -> Wiki: GET pages
Wiki --> Script: Existing pages Wiki --> Script: Existing pages
Script -> Wiki: Create new pages, update changed pages Script -> Wiki: Create new pages, update changed pages
opt prune is true Script --> Workflow: Log created and updated counts
Script -> Wiki: Delete pages that are not in wiki_dir
end end
Script --> Workflow: Log created, updated and deleted counts deactivate Script
Workflow --> Trigger: Workflow result
end end
deactivate Script
Workflow --> Caller: Workflow result
deactivate Workflow deactivate Workflow
@enduml @enduml
``` ```
### Menerbitkan wiki sendiri
Wiki repositori ini ialah `docs/wiki/`. Aliran kerja ini memanggil aliran kerja boleh guna semula di atas melalui laluan tempatannya, dengan `prune` ditetapkan kepada `true` supaya wiki sentiasa sama dengan folder dan `tools-ref` ditetapkan kepada `main` supaya skrip daripada commit yang sama dijalankan. Ia ialah pemanggil yang disalin oleh projek daripada `templates/ci/publish-wiki.yml` framework.
#### Aliran kerja
```plantuml
@startuml
title Publish the wiki of this repository (docs/wiki)
autonumber
actor "Push to main that changes docs/wiki/**,\nor manual trigger" as Trigger
participant "Gitea Actions\npublish-own-wiki" as Caller
participant "Gitea Actions\npublish-wiki-pages\n(called by its local path)" as Workflow
participant "Gitea wiki API" as Wiki
Trigger -> Caller: Start workflow
activate Caller
Caller -> Workflow: Call with wiki_dir docs/wiki, prune true,\ntools-ref main and TOKEN_FOR_GITEA_WIKI
activate Workflow
Workflow -> Wiki: Create, update and delete pages\nso the wiki equals docs/wiki
Wiki --> Workflow: Done
Workflow --> Caller: Workflow result
deactivate Workflow
Caller --> Trigger: Workflow result
deactivate Caller
@enduml
```
### Menerbitkan milestone yang diterima ### Menerbitkan milestone yang diterima
Kebenaran tetap untuk menerbitkan: pada push ke `main` yang mengubah milestone atau semakannya, setiap milestone yang baris terkini Version History-nya Accepted dan semakan terkininya Go dicipta atau dikemas kini di Gitea dengan tugasnya sebagai isu. Tiada apa-apa ditutup atau dipadam. Larian manual ialah larian percubaan kecuali `dry_run` dimatikan. Ia menggunakan secret `TOKEN_FOR_GITEA` dan peraturan `--accepted-only` framework yang dipasang (v0.5.0 atau lebih baharu). Kebenaran tetap untuk menerbitkan: pada push ke `main` yang mengubah milestone atau semakannya, setiap milestone yang baris terkini Version History-nya Accepted dan semakan terkininya Go dicipta atau dikemas kini di Gitea dengan tugasnya sebagai isu. Tiada apa-apa ditutup atau dipadam. Larian manual ialah larian percubaan kecuali `dry_run` dimatikan. Ia menggunakan secret `TOKEN_FOR_GITEA` dan peraturan `--accepted-only` framework yang dipasang (v0.5.0 atau lebih baharu).
docs/wiki/Onboarding.da.md
+4 -21
View File
@@ -1,4 +1,4 @@
<!-- translation of Onboarding.md, source sha256 7416464e6e83 --> <!-- translation of Onboarding.md, source sha256 1073637428ce -->
> Dette er en oversættelse af [`Onboarding`](Onboarding). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres. > Dette er en oversættelse af [`Onboarding`](Onboarding). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
@@ -32,29 +32,12 @@ Leveringen er automatisk, så et repository behøver ingen kopi af workflowet. S
## Publicér en wiki (valgfrit) ## Publicér en wiki (valgfrit)
Det genbrugelige workflow **Publish wiki pages** kopierer Markdown-siderne i `docs/wiki/` til repositoryets wiki, når en ændring af `docs/wiki/` flettes til `main`. Repositoryet kalder det, så der skrives intet, hvor der ikke findes et kald. Wikien findes som minimum på engelsk og på produktejerens sprog. Det scoped workflow **Publish wiki pages** kopierer Markdown-siderne i `docs/wiki/` til repositoryets wiki, når en ændring af `docs/wiki/` flettes til `main`. Instansen leverer det til alle repositories, så der er intet at kalde eller kopiere; et repository uden en `docs/wiki/`-mappe springes over. Sider, der er i wikien men ikke i mappen, beholdes. Wikien findes som minimum på engelsk og på produktejerens sprog.
1. Aktivér wikien i repositoryets indstillinger. 1. Aktivér wikien i repositoryets indstillinger.
2. Tilføj Markdown-sider til `docs/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)`. 2. Tilføj Markdown-sider til `docs/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 et workflow, for eksempel `.gitea/workflows/publish-wiki.yml`, der kalder det genbrugelige workflow: 3. Gem `TOKEN_FOR_GITEA_WIKI` som en secret i repositoryets organisation med det scope, der står i [credentials.md](Credentials.da).
4. Flet ændringen til `main`. Loggen skal slutte med `Published <n> page(s) to the wiki of <owner>/<repo>`.
```yaml
on:
push:
branches: [ main ]
paths: [ "docs/wiki/**" ]
jobs:
wiki:
uses: TirSystem/git-workflows/.gitea/workflows/publish-wiki-pages.yml@v1
with:
prune: "true"
secrets:
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
```
`wiki_dir` er som standard `docs/wiki`. `prune: "true"` sletter også wiki-sider, der ikke findes i mappen, så wikien altid er lig med mappen; standarden `false` beholder dem.
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 <n> page(s) to the wiki of <owner>/<repo>`.
## Runners ## Runners
docs/wiki/Onboarding.md
+6 -24
View File
@@ -51,38 +51,20 @@ Delivery is automatic, so a repository needs no copy of the workflow. Secrets ar
## Publish a wiki (optional) ## Publish a wiki (optional)
The reusable workflow **Publish wiki pages** copies the Markdown pages in The scoped workflow **Publish wiki pages** copies the Markdown pages in
`docs/wiki/` to the repository wiki when a change to `docs/wiki/` is merged to `docs/wiki/` to the repository wiki when a change to `docs/wiki/` is merged to
`main`. The repository calls it, so nothing is written where no call exists. `main`. It is delivered by the instance to every repository, so there is nothing
to call or copy; a repository without a `docs/wiki/` folder is skipped. Pages
that are in the wiki but not in the folder are kept.
The wiki has English and the product owner's language as a minimum. The wiki has English and the product owner's language as a minimum.
1. Enable the wiki in the repository settings. 1. Enable the wiki in the repository settings.
2. Add Markdown pages to `docs/wiki/`. The file name is the page name: `Home.md` 2. Add Markdown pages to `docs/wiki/`. The file name is the page name: `Home.md`
is the home page. A hyphen in the name is a space in the page name: is 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/git-workflows/src/branch/main/guides/Home-da)`. `Home-da.md` is the page "Home da", and a link to it is `[Dansk](https://git.tirsystem.com/TirSystem/git-workflows/src/branch/main/guides/Home-da)`.
3. Add a workflow, for example `.gitea/workflows/publish-wiki.yml`, that calls 3. Store `TOKEN_FOR_GITEA_WIKI` as a secret of the repository's organization,
the reusable workflow:
```yaml
on:
push:
branches: [ main ]
paths: [ "docs/wiki/**" ]
jobs:
wiki:
uses: TirSystem/git-workflows/.gitea/workflows/publish-wiki-pages.yml@v1
with:
prune: "true"
secrets:
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
```
`wiki_dir` defaults to `docs/wiki`. `prune: "true"` also deletes wiki pages
that are not in the folder, so the wiki always equals the folder; the
default `false` keeps them.
4. Store `TOKEN_FOR_GITEA_WIKI` as a secret of the repository's organization,
using the scope in [credentials.md](Credentials). using the scope in [credentials.md](Credentials).
5. Merge the change to `main`. The log must end with `Published <n> page(s) to 4. Merge the change to `main`. The log must end with `Published <n> page(s) to
the wiki of <owner>/<repo>`. the wiki of <owner>/<repo>`.
## Runners ## Runners
docs/wiki/Onboarding.ms.md
+4 -21
View File
@@ -1,4 +1,4 @@
<!-- translation of Onboarding.md, source sha256 7416464e6e83 --> <!-- translation of Onboarding.md, source sha256 1073637428ce -->
> Ini ialah terjemahan [`Onboarding`](Onboarding). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya. > Ini ialah terjemahan [`Onboarding`](Onboarding). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
@@ -32,29 +32,12 @@ Penghantaran adalah automatik, jadi repositori tidak memerlukan salinan aliran k
## Menerbitkan wiki (pilihan) ## Menerbitkan wiki (pilihan)
Aliran kerja boleh guna semula **Publish wiki pages** menyalin halaman Markdown dalam `docs/wiki/` ke wiki repositori apabila perubahan pada `docs/wiki/` digabungkan ke `main`. Repositori memanggilnya, jadi tiada apa-apa ditulis di tempat yang tiada panggilan. Wiki ada dalam bahasa Inggeris dan bahasa pemilik produk sekurang-kurangnya. Aliran kerja scoped **Publish wiki pages** menyalin halaman Markdown dalam `docs/wiki/` ke wiki repositori apabila perubahan pada `docs/wiki/` digabungkan ke `main`. Instans menghantarnya ke semua repositori, jadi tiada apa-apa untuk dipanggil atau disalin; repositori tanpa folder `docs/wiki/` dilangkau. Halaman yang ada dalam wiki tetapi tiada dalam folder dikekalkan. Wiki ada dalam bahasa Inggeris dan bahasa pemilik produk sekurang-kurangnya.
1. Aktifkan wiki dalam tetapan repositori. 1. Aktifkan wiki dalam tetapan repositori.
2. Tambah halaman Markdown ke `docs/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)`. 2. Tambah halaman Markdown ke `docs/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 aliran kerja, contohnya `.gitea/workflows/publish-wiki.yml`, yang memanggil aliran kerja boleh guna semula: 3. Simpan `TOKEN_FOR_GITEA_WIKI` sebagai secret organisasi repositori, dengan skop yang tertera dalam [credentials.md](Credentials.ms).
4. Gabungkan perubahan ke `main`. Log mesti berakhir dengan `Published <n> page(s) to the wiki of <owner>/<repo>`.
```yaml
on:
push:
branches: [ main ]
paths: [ "docs/wiki/**" ]
jobs:
wiki:
uses: TirSystem/git-workflows/.gitea/workflows/publish-wiki-pages.yml@v1
with:
prune: "true"
secrets:
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
```
`wiki_dir` lalai ialah `docs/wiki`. `prune: "true"` turut memadam halaman wiki yang tiada dalam folder itu, supaya wiki sentiasa sama dengan folder; lalai `false` mengekalkannya.
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 <n> page(s) to the wiki of <owner>/<repo>`.
## Runners ## Runners
docs/wiki/Troubleshooting.da.md
+3 -5
View File
@@ -1,4 +1,4 @@
<!-- translation of Troubleshooting.md, source sha256 8d1373b72756 --> <!-- translation of Troubleshooting.md, source sha256 e4128e7f821c -->
> Dette er en oversættelse af [`Troubleshooting`](Troubleshooting). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres. > Dette er en oversættelse af [`Troubleshooting`](Troubleshooting). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
@@ -30,9 +30,7 @@ Kategorien fortæller, hvor du skal kigge. En fejl uden for scriptet (jobbet sta
| `TOKEN_FOR_GITEA is missing or empty.` | configuration | Tilføj secreten | | `TOKEN_FOR_GITEA is missing or empty.` | configuration | Tilføj secreten |
| `Could not determine the Gitea source repository.` | configuration | Kørslen har intet repositorynavn; meld det som en defekt | | `Could not determine the Gitea source repository.` | configuration | Kørslen har intet repositorynavn; meld det som en defekt |
| `Expected at most one GitHub push mirror ... found N` | configuration | Behold ét GitHub push-spejl | | `Expected at most one GitHub push mirror ... found N` | configuration | Behold ét GitHub push-spejl |
| `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Kun wiki-publicering: repositoryet kalder workflowet, men dets organisation har ingen sådan secret, eller kaldet sender den ikke; gem den og send den i `secrets:` (se [credentials.md](Credentials.da)) | | `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Kun wiki-publicering: repositoryet har en `docs/wiki/`-mappe, men dets organisation har ingen sådan secret; gem den som en organisations-secret (se [credentials.md](Credentials.da)) |
| `The prune input must be 'true' or 'false'` | configuration | Kun wiki-publicering: sæt `prune` i kaldet til `"true"` eller `"false"` |
| `The wiki folder ... does not exist` | configuration | Kun wiki-publicering: sæt `wiki_dir` i kaldet til mappen med siderne (standard `docs/wiki`) |
| `... HTTP 403 ...` ved publicering af wikien | permissions | Kun wiki-publicering: tokenet skal have `write:repository` og skriveadgang til dette repository | | `... HTTP 403 ...` ved publicering af wikien | permissions | Kun wiki-publicering: tokenet skal have `write:repository` og skriveadgang til dette repository |
| `The wiki is not enabled on <repo>` | configuration | Kun wiki-publicering: aktivér wikien i repositoryets indstillinger | | `The wiki is not enabled on <repo>` | configuration | Kun wiki-publicering: aktivér wikien i repositoryets indstillinger |
| `The wiki source directory ... has no Markdown pages` | configuration | Kun wiki-publicering: mappen har ingen Markdown-sider; intet blev ændret | | `The wiki source directory ... has no Markdown pages` | configuration | Kun wiki-publicering: mappen har ingen Markdown-sider; intet blev ændret |
@@ -52,7 +50,7 @@ Kategorien fortæller, hvor du skal kigge. En fejl uden for scriptet (jobbet sta
`WARNING: Gitea returned an invalid push mirror list; GitHub metadata was not synced.` Kørslen lykkes, men intet blev synkroniseret. Kontroller, at Gitea-versionen understøtter push mirror-API'et, og kør igen. `WARNING: Gitea returned an invalid push mirror list; GitHub metadata was not synced.` Kørslen lykkes, men intet blev synkroniseret. Kontroller, at Gitea-versionen understøtter push mirror-API'et, og kør igen.
`<n> page(s) are in the wiki but not in <folder>/ and were kept; set the prune input to true to delete them.` Kørslen lykkes. Sider, der kun findes i wikien, lades i fred, medmindre kaldet sætter `prune: "true"`. `<n> page(s) are in the wiki but not in <folder>/ and were kept ...` Kørslen lykkes. Sider, der kun findes i wikien, lades altid i fred.
## Runner-problemer ## Runner-problemer
docs/wiki/Troubleshooting.md
+3 -6
View File
@@ -32,9 +32,7 @@ never starts, or stops before the step) is a **runner** problem.
| `TOKEN_FOR_GITEA is missing or empty.` | configuration | Add the secret | | `TOKEN_FOR_GITEA is missing or empty.` | configuration | Add the secret |
| `Could not determine the Gitea source repository.` | configuration | The run has no repository name; report as a defect | | `Could not determine the Gitea source repository.` | configuration | The run has no repository name; report as a defect |
| `Expected at most one GitHub push mirror ... found N` | configuration | Keep one GitHub push mirror | | `Expected at most one GitHub push mirror ... found N` | configuration | Keep one GitHub push mirror |
| `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Wiki publishing only: the repository calls the workflow but its organization has no such secret, or the call does not pass it; store it and pass it in `secrets:` (see [credentials.md](Credentials)) | | `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Wiki publishing only: the repository has a `docs/wiki/` folder but its organization has no such secret; store it as an organization secret (see [credentials.md](Credentials)) |
| `The prune input must be 'true' or 'false'` | configuration | Wiki publishing only: set `prune` in the call to `"true"` or `"false"` |
| `The wiki folder ... does not exist` | configuration | Wiki publishing only: set `wiki_dir` in the call to the folder with the pages (default `docs/wiki`) |
| `... HTTP 403 ...` while publishing the wiki | permissions | Wiki publishing only: the token needs `write:repository` and write access to this repository | | `... HTTP 403 ...` while publishing the wiki | permissions | Wiki publishing only: the token needs `write:repository` and write access to this repository |
| `The wiki is not enabled on <repo>` | configuration | Wiki publishing only: enable the wiki in the repository settings | | `The wiki is not enabled on <repo>` | configuration | Wiki publishing only: enable the wiki in the repository settings |
| `The wiki source directory ... has no Markdown pages` | configuration | Wiki publishing only: the folder has no Markdown pages; nothing was changed | | `The wiki source directory ... has no Markdown pages` | configuration | Wiki publishing only: the folder has no Markdown pages; nothing was changed |
@@ -59,9 +57,8 @@ settings.
synced.` The run succeeds but nothing was synced. Check that the Gitea synced.` The run succeeds but nothing was synced. Check that the Gitea
version supports the push mirror API and re-run. version supports the push mirror API and re-run.
`<n> page(s) are in the wiki but not in <folder>/ and were kept; set the prune `<n> page(s) are in the wiki but not in <folder>/ and were kept ...` The run
input to true to delete them.` The run succeeds. Pages that exist only in the succeeds. Pages that exist only in the wiki are always left alone.
wiki are left alone unless the call sets `prune: "true"`.
## Runner problems ## Runner problems
docs/wiki/Troubleshooting.ms.md
+3 -5
View File
@@ -1,4 +1,4 @@
<!-- translation of Troubleshooting.md, source sha256 8d1373b72756 --> <!-- translation of Troubleshooting.md, source sha256 e4128e7f821c -->
> Ini ialah terjemahan [`Troubleshooting`](Troubleshooting). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya. > Ini ialah terjemahan [`Troubleshooting`](Troubleshooting). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
@@ -30,9 +30,7 @@ Kategori menunjukkan di mana perlu dilihat. Kegagalan di luar skrip (kerja tidak
| `TOKEN_FOR_GITEA is missing or empty.` | configuration | Tambah secret | | `TOKEN_FOR_GITEA is missing or empty.` | configuration | Tambah secret |
| `Could not determine the Gitea source repository.` | configuration | Larian tiada nama repositori; laporkan sebagai kecacatan | | `Could not determine the Gitea source repository.` | configuration | Larian tiada nama repositori; laporkan sebagai kecacatan |
| `Expected at most one GitHub push mirror ... found N` | configuration | Kekalkan satu push mirror GitHub | | `Expected at most one GitHub push mirror ... found N` | configuration | Kekalkan satu push mirror GitHub |
| `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Penerbitan wiki sahaja: repositori memanggil aliran kerja tetapi organisasinya tiada secret itu, atau panggilan tidak menghantarnya; simpannya dan hantar dalam `secrets:` (lihat [credentials.md](Credentials.ms)) | | `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Penerbitan wiki sahaja: repositori mempunyai folder `docs/wiki/` tetapi organisasinya tiada secret itu; simpannya sebagai secret organisasi (lihat [credentials.md](Credentials.ms)) |
| `The prune input must be 'true' or 'false'` | configuration | Penerbitan wiki sahaja: tetapkan `prune` dalam panggilan kepada `"true"` atau `"false"` |
| `The wiki folder ... does not exist` | configuration | Penerbitan wiki sahaja: tetapkan `wiki_dir` dalam panggilan kepada folder yang mengandungi halaman (lalai `docs/wiki`) |
| `... HTTP 403 ...` semasa menerbitkan wiki | permissions | Penerbitan wiki sahaja: token memerlukan `write:repository` dan akses tulis kepada repositori ini | | `... HTTP 403 ...` semasa menerbitkan wiki | permissions | Penerbitan wiki sahaja: token memerlukan `write:repository` dan akses tulis kepada repositori ini |
| `The wiki is not enabled on <repo>` | configuration | Penerbitan wiki sahaja: aktifkan wiki dalam tetapan repositori | | `The wiki is not enabled on <repo>` | configuration | Penerbitan wiki sahaja: aktifkan wiki dalam tetapan repositori |
| `The wiki source directory ... has no Markdown pages` | configuration | Penerbitan wiki sahaja: folder itu tiada halaman Markdown; tiada apa-apa diubah | | `The wiki source directory ... has no Markdown pages` | configuration | Penerbitan wiki sahaja: folder itu tiada halaman Markdown; tiada apa-apa diubah |
@@ -52,7 +50,7 @@ Kategori menunjukkan di mana perlu dilihat. Kegagalan di luar skrip (kerja tidak
`WARNING: Gitea returned an invalid push mirror list; GitHub metadata was not synced.` Larian berjaya tetapi tiada apa-apa disegerakkan. Semak bahawa versi Gitea menyokong API push mirror dan jalankan semula. `WARNING: Gitea returned an invalid push mirror list; GitHub metadata was not synced.` Larian berjaya tetapi tiada apa-apa disegerakkan. Semak bahawa versi Gitea menyokong API push mirror dan jalankan semula.
`<n> page(s) are in the wiki but not in <folder>/ and were kept; set the prune input to true to delete them.` Larian berjaya. Halaman yang hanya ada dalam wiki dibiarkan melainkan panggilan menetapkan `prune: "true"`. `<n> page(s) are in the wiki but not in <folder>/ and were kept ...` Larian berjaya. Halaman yang hanya ada dalam wiki sentiasa dibiarkan.
## Masalah runner ## Masalah runner
docs/wiki/Upgrading.da.md
+2 -2
View File
@@ -1,4 +1,4 @@
<!-- translation of Upgrading.md, source sha256 21362a6fcbd7 --> <!-- translation of Upgrading.md, source sha256 bc88ef4f6d7c -->
> Dette er en oversættelse af [`Upgrading`](Upgrading). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres. > Dette er en oversættelse af [`Upgrading`](Upgrading). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
@@ -20,7 +20,7 @@ En udgivelse, der bryder kompatibiliteten, får en ny major-version (`v2`), så
Kvalitetskontrol-workflowene (`quality-checks.yml`, `quality-checks-cpp.yml` og `quality-checks-csharp.yml`) og kodemålings-workflowet (`code-metrics.yml`) henter deres scripts ved deres input `tools-ref`, som som standard er det aktuelle major-tag (`v2`). For at fastlåse et helt skal du kalde det ved et præcist tag og sætte `tools-ref` til samme tag; ellers følger scriptet major-tagget. Kvalitetskontrol-workflowene (`quality-checks.yml`, `quality-checks-cpp.yml` og `quality-checks-csharp.yml`) og kodemålings-workflowet (`code-metrics.yml`) henter deres scripts ved deres input `tools-ref`, som som standard er det aktuelle major-tag (`v2`). For at fastlåse et helt skal du kalde det ved et præcist tag og sætte `tools-ref` til samme tag; ellers følger scriptet major-tagget.
Det scoped workflow **Sync GitHub mirror metadata** leveres af instansen og står ikke i dine `uses:`-linjer; du kan ikke fastlåse det, men det henter sit script ved major-tagget. Publicering af wiki er et genbrugeligt workflow, du kalder (`publish-wiki-pages.yml`); det scoped workflow **Publish wiki** og dets markør `wiki/.publish` blev fjernet i 2.0.0, så et repository, der stadig har markøren, publicerer ikke mere, før det kalder det genbrugelige workflow (se introduktionsguiden). De scoped workflows **Sync GitHub mirror metadata** og **Publish wiki pages** leveres af instansen og står ikke i dine `uses:`-linjer; du kan ikke fastlåse dem, men de henter deres scripts ved major-tagget. Et repository, der kaldte `publish-wiki-pages.yml` med `uses:`, behøver ikke længere kaldet: fjern kaldeworkflowet, for det scoped workflow publicerer `docs/wiki/` af sig selv (det sletter ikke sider, der ikke er i mappen).
## Aflæsning af en changelog-post ## Aflæsning af en changelog-post
docs/wiki/Upgrading.md
+6 -7
View File
@@ -27,13 +27,12 @@ The quality-checks workflows (`quality-checks.yml`, `quality-checks-cpp.yml` and
fetch their scripts at their input `tools-ref`, which defaults to the current major tag (`v2`). To pin one completely, call it at an exact tag and set fetch their scripts at their input `tools-ref`, which defaults to the current major tag (`v2`). To pin one completely, call it at an exact tag and set
`tools-ref` to the same tag; otherwise the script follows the major tag. `tools-ref` to the same tag; otherwise the script follows the major tag.
The scoped workflow **Sync GitHub mirror metadata** is delivered by the The scoped workflows **Sync GitHub mirror metadata** and **Publish wiki pages**
instance and is not in your `uses:` lines; you cannot pin it, but it fetches its are delivered by the instance and are not in your `uses:` lines; you cannot pin
script at the major tag. Wiki publishing is a reusable workflow you call them, but they fetch their scripts at the major tag. A repository that called
(`publish-wiki-pages.yml`); the scoped **Publish wiki** workflow and its `publish-wiki-pages.yml` with `uses:` no longer needs the call: remove the
`wiki/.publish` marker were removed in 2.0.0, so a repository that still has the caller workflow, because the scoped workflow publishes `docs/wiki/` on its own
marker no longer publishes until it calls the reusable workflow (see the (it does not delete pages that are not in the folder).
onboarding guide).
## Reading a changelog entry ## Reading a changelog entry
docs/wiki/Upgrading.ms.md
+2 -2
View File
@@ -1,4 +1,4 @@
<!-- translation of Upgrading.md, source sha256 21362a6fcbd7 --> <!-- translation of Upgrading.md, source sha256 bc88ef4f6d7c -->
> Ini ialah terjemahan [`Upgrading`](Upgrading). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya. > Ini ialah terjemahan [`Upgrading`](Upgrading). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
@@ -20,7 +20,7 @@ Keluaran yang memecahkan keserasian mendapat versi major baharu (`v2`), jadi sal
Aliran kerja semakan kualiti (`quality-checks.yml`, `quality-checks-cpp.yml` dan `quality-checks-csharp.yml`) dan aliran kerja metrik kod (`code-metrics.yml`) mengambil skripnya pada inputnya `tools-ref`, yang lalai ialah tag major semasa (`v2`). Untuk menyematkan satu sepenuhnya, panggil pada tag tepat dan tetapkan `tools-ref` kepada tag yang sama; jika tidak, skrip mengikuti tag major. Aliran kerja semakan kualiti (`quality-checks.yml`, `quality-checks-cpp.yml` dan `quality-checks-csharp.yml`) dan aliran kerja metrik kod (`code-metrics.yml`) mengambil skripnya pada inputnya `tools-ref`, yang lalai ialah tag major semasa (`v2`). Untuk menyematkan satu sepenuhnya, panggil pada tag tepat dan tetapkan `tools-ref` kepada tag yang sama; jika tidak, skrip mengikuti tag major.
Aliran kerja scoped **Sync GitHub mirror metadata** dihantar oleh instans dan tidak terdapat dalam baris `uses:` anda; anda tidak boleh menyematkannya, tetapi ia mengambil skripnya pada tag major. Penerbitan wiki ialah aliran kerja boleh guna semula yang anda panggil (`publish-wiki-pages.yml`); aliran kerja scoped **Publish wiki** dan penanda `wiki/.publish` telah dibuang dalam 2.0.0, jadi repositori yang masih mempunyai penanda itu tidak lagi menerbitkan sehingga ia memanggil aliran kerja boleh guna semula (lihat panduan permulaan). Aliran kerja scoped **Sync GitHub mirror metadata** dan **Publish wiki pages** dihantar oleh instans dan tidak terdapat dalam baris `uses:` anda; anda tidak boleh menyematkannya, tetapi ia mengambil skripnya pada tag major. Repositori yang memanggil `publish-wiki-pages.yml` dengan `uses:` tidak lagi memerlukan panggilan itu: buang aliran kerja pemanggil, kerana aliran kerja scoped menerbitkan `docs/wiki/` sendiri (ia tidak memadam halaman yang tiada dalam folder).
## Membaca satu catatan changelog ## Membaca satu catatan changelog
framework
+1 -1
Submodule framework updated: ca18cb4215...922c8b9e59
guides/adoption-rules.md
+1 -1
View File
@@ -17,7 +17,7 @@ A new workflow is not finished until its row is in the table below
| Quality checks C# | The repository tracks C# files and can restore packages from the network. | It has none, or cannot reach the package source. | The same evidence for C#, on an exact .NET SDK. | | Quality checks C# | The repository tracks C# files and can restore packages from the network. | It has none, or cannot reach the package source. | The same evidence for C#, on an exact .NET SDK. |
| Code metrics | The repository has a test suite that writes a Cobertura report and its README or wiki shows size and coverage. | It has no tests, or no report is produced. | Coverage and size as badges, so a reviewer sees them without running anything. | | Code metrics | The repository has a test suite that writes a Cobertura report and its README or wiki shows size and coverage. | It has no tests, or no report is produced. | Coverage and size as badges, so a reviewer sees them without running anything. |
| English comments | The repository's code comments must be English (the project's language rule) and it takes pull requests. | The project's language rule allows other languages in comments. | Enforces the language rule on every pull request, with the author named. Mark it required to block the merge. | | English comments | The repository's code comments must be English (the project's language rule) and it takes pull requests. | The project's language rule allows other languages in comments. | Enforces the language rule on every pull request, with the author named. Mark it required to block the merge. |
| Publish wiki pages | The repository has a wiki and its pages are written as Markdown under `docs/wiki/` (or `wiki_dir`). | It has no wiki, or the wiki is edited by hand. | The wiki equals the reviewed files; a page change goes through a pull request and its review. | | Publish wiki pages | Scoped: nothing to do. A repository with a wiki and its pages written as Markdown under `docs/wiki/` is published; one without that folder is skipped. | It has the folder but does not want it published (disable the wiki or use another folder), or the wiki is edited by hand. | The wiki equals the reviewed files; a page change goes through a pull request and its review. |
| Release | Opt-in is not by call: it is for repositories that publish versioned releases pinned by others, and it is run only in this repository. | Not applicable to other repositories. | A tagged, checked release other repositories can pin. | | Release | Opt-in is not by call: it is for repositories that publish versioned releases pinned by others, and it is run only in this repository. | Not applicable to other repositories. | A tagged, checked release other repositories can pin. |
| Publish accepted milestones | Internal to this repository (it reads this repository's milestones and reviews). A project that keeps `docs/milestones/` and `docs/sqa/reviews/` uses the framework's `templates/ci/` copy. | The repository has no `MIL-*` documents. | Only a milestone that is Accepted with a Go review becomes an issue (the plan-first gate). | | Publish accepted milestones | Internal to this repository (it reads this repository's milestones and reviews). A project that keeps `docs/milestones/` and `docs/sqa/reviews/` uses the framework's `templates/ci/` copy. | The repository has no `MIL-*` documents. | Only a milestone that is Accepted with a Go review becomes an issue (the plan-first gate). |
| Validate workflows | Internal: it gates this repository's own pull requests. | Not applicable to other repositories. | Proof that every workflow parses and passes the offline tests. | | Validate workflows | Internal: it gates this repository's own pull requests. | Not applicable to other repositories. | Proof that every workflow parses and passes the offline tests. |
guides/credentials.md
+8 -9
View File
@@ -83,29 +83,28 @@ is ever printed.
## Wiki publishing secret ## Wiki publishing secret
The workflow **Publish wiki pages** copies `docs/wiki/` to the Gitea wiki of a The workflow **Publish wiki pages** copies `docs/wiki/` to the Gitea wiki of a
repository that calls it (see [onboarding.md](onboarding.md)). It uses its own repository that has a `docs/wiki/` folder (see [onboarding.md](onboarding.md)).
secret, so the metadata sync token stays read-only. The caller passes the It uses its own secret, so the metadata sync token stays read-only.
secret in `secrets:`; it is not inherited.
| Secret | Content | Used for | | Secret | Content | Used for |
| --- | --- | --- | | --- | --- | --- |
| `TOKEN_FOR_GITEA_WIKI` | The Gitea token, nothing else | Writing the wiki pages of the repositories of an organization that opt in | | `TOKEN_FOR_GITEA_WIKI` | The Gitea token, nothing else | Writing the wiki pages of the repositories of an organization that have a `docs/wiki/` folder |
- Store it as a secret of the organization of each repository that publishes. - Store it as a secret of the organization of each repository that publishes.
There is no fallback to `TOKEN_FOR_GITEA`: a repository that calls the There is no fallback to `TOKEN_FOR_GITEA`: a repository with a
workflow and has no such secret fails with a configuration error, and a `docs/wiki/` folder and no such secret fails with a configuration error, and a
repository that does not call it does not need it. repository without the folder does not need it.
- The token needs scope `write:repository`, and its user needs write access to - The token needs scope `write:repository`, and its user needs write access to
the repositories. Gitea has no wiki-only scope, so create the token for a the repositories. Gitea has no wiki-only scope, so create the token for a
dedicated user. S05 approves the scope and S03 stores the secret. dedicated user. S05 approves the scope and S03 stores the secret.
- Calls made: `GET /repos/{owner}/{repo}`, `GET /repos/{owner}/{repo}/wiki/pages`, - Calls made: `GET /repos/{owner}/{repo}`, `GET /repos/{owner}/{repo}/wiki/pages`,
`GET`, `POST` and `PATCH /repos/{owner}/{repo}/wiki/...` and, for a page that `GET`, `POST` and `PATCH /repos/{owner}/{repo}/wiki/...` and, for a page that
no longer exists in `docs/wiki/`, `DELETE /repos/{owner}/{repo}/wiki/page/{name}`. no longer exists in `docs/wiki/`, `DELETE /repos/{owner}/{repo}/wiki/page/{name}` (only when pruning is switched on, which the scoped workflow does not do).
- The wiki must be enabled in the repository settings. The workflow refuses to - The wiki must be enabled in the repository settings. The workflow refuses to
run when it is not. run when it is not.
- Pages that are in `docs/wiki/` are always overwritten from it, so a change - Pages that are in `docs/wiki/` are always overwritten from it, so a change
made in the Gitea web UI is lost on the next publish. Pages that are only in made in the Gitea web UI is lost on the next publish. Pages that are only in
the wiki are removed only when the call sets `prune: "true"`. the wiki are kept.
## Rotating a token ## Rotating a token
guides/onboarding.md
+6 -24
View File
@@ -45,38 +45,20 @@ Delivery is automatic, so a repository needs no copy of the workflow. Secrets ar
## Publish a wiki (optional) ## Publish a wiki (optional)
The reusable workflow **Publish wiki pages** copies the Markdown pages in The scoped workflow **Publish wiki pages** copies the Markdown pages in
`docs/wiki/` to the repository wiki when a change to `docs/wiki/` is merged to `docs/wiki/` to the repository wiki when a change to `docs/wiki/` is merged to
`main`. The repository calls it, so nothing is written where no call exists. `main`. It is delivered by the instance to every repository, so there is nothing
to call or copy; a repository without a `docs/wiki/` folder is skipped. Pages
that are in the wiki but not in the folder are kept.
The wiki has English and the product owner's language as a minimum. The wiki has English and the product owner's language as a minimum.
1. Enable the wiki in the repository settings. 1. Enable the wiki in the repository settings.
2. Add Markdown pages to `docs/wiki/`. The file name is the page name: `Home.md` 2. Add Markdown pages to `docs/wiki/`. The file name is the page name: `Home.md`
is the home page. A hyphen in the name is a space in the page name: is 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)`. `Home-da.md` is the page "Home da", and a link to it is `[Dansk](Home-da)`.
3. Add a workflow, for example `.gitea/workflows/publish-wiki.yml`, that calls 3. Store `TOKEN_FOR_GITEA_WIKI` as a secret of the repository's organization,
the reusable workflow:
```yaml
on:
push:
branches: [ main ]
paths: [ "docs/wiki/**" ]
jobs:
wiki:
uses: TirSystem/git-workflows/.gitea/workflows/publish-wiki-pages.yml@v1
with:
prune: "true"
secrets:
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
```
`wiki_dir` defaults to `docs/wiki`. `prune: "true"` also deletes wiki pages
that are not in the folder, so the wiki always equals the folder; the
default `false` keeps them.
4. Store `TOKEN_FOR_GITEA_WIKI` as a secret of the repository's organization,
using the scope in [credentials.md](credentials.md). using the scope in [credentials.md](credentials.md).
5. Merge the change to `main`. The log must end with `Published <n> page(s) to 4. Merge the change to `main`. The log must end with `Published <n> page(s) to
the wiki of <owner>/<repo>`. the wiki of <owner>/<repo>`.
## Runners ## Runners
guides/troubleshooting.md
+3 -6
View File
@@ -26,9 +26,7 @@ never starts, or stops before the step) is a **runner** problem.
| `TOKEN_FOR_GITEA is missing or empty.` | configuration | Add the secret | | `TOKEN_FOR_GITEA is missing or empty.` | configuration | Add the secret |
| `Could not determine the Gitea source repository.` | configuration | The run has no repository name; report as a defect | | `Could not determine the Gitea source repository.` | configuration | The run has no repository name; report as a defect |
| `Expected at most one GitHub push mirror ... found N` | configuration | Keep one GitHub push mirror | | `Expected at most one GitHub push mirror ... found N` | configuration | Keep one GitHub push mirror |
| `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Wiki publishing only: the repository calls the workflow but its organization has no such secret, or the call does not pass it; store it and pass it in `secrets:` (see [credentials.md](credentials.md)) | | `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Wiki publishing only: the repository has a `docs/wiki/` folder but its organization has no such secret; store it as an organization secret (see [credentials.md](credentials.md)) |
| `The prune input must be 'true' or 'false'` | configuration | Wiki publishing only: set `prune` in the call to `"true"` or `"false"` |
| `The wiki folder ... does not exist` | configuration | Wiki publishing only: set `wiki_dir` in the call to the folder with the pages (default `docs/wiki`) |
| `... HTTP 403 ...` while publishing the wiki | permissions | Wiki publishing only: the token needs `write:repository` and write access to this repository | | `... HTTP 403 ...` while publishing the wiki | permissions | Wiki publishing only: the token needs `write:repository` and write access to this repository |
| `The wiki is not enabled on <repo>` | configuration | Wiki publishing only: enable the wiki in the repository settings | | `The wiki is not enabled on <repo>` | configuration | Wiki publishing only: enable the wiki in the repository settings |
| `The wiki source directory ... has no Markdown pages` | configuration | Wiki publishing only: the folder has no Markdown pages; nothing was changed | | `The wiki source directory ... has no Markdown pages` | configuration | Wiki publishing only: the folder has no Markdown pages; nothing was changed |
@@ -53,9 +51,8 @@ settings.
synced.` The run succeeds but nothing was synced. Check that the Gitea synced.` The run succeeds but nothing was synced. Check that the Gitea
version supports the push mirror API and re-run. version supports the push mirror API and re-run.
`<n> page(s) are in the wiki but not in <folder>/ and were kept; set the prune `<n> page(s) are in the wiki but not in <folder>/ and were kept ...` The run
input to true to delete them.` The run succeeds. Pages that exist only in the succeeds. Pages that exist only in the wiki are always left alone.
wiki are left alone unless the call sets `prune: "true"`.
## Runner problems ## Runner problems
guides/upgrading.md
+6 -7
View File
@@ -21,13 +21,12 @@ The quality-checks workflows (`quality-checks.yml`, `quality-checks-cpp.yml` and
fetch their scripts at their input `tools-ref`, which defaults to the current major tag (`v2`). To pin one completely, call it at an exact tag and set fetch their scripts at their input `tools-ref`, which defaults to the current major tag (`v2`). To pin one completely, call it at an exact tag and set
`tools-ref` to the same tag; otherwise the script follows the major tag. `tools-ref` to the same tag; otherwise the script follows the major tag.
The scoped workflow **Sync GitHub mirror metadata** is delivered by the The scoped workflows **Sync GitHub mirror metadata** and **Publish wiki pages**
instance and is not in your `uses:` lines; you cannot pin it, but it fetches its are delivered by the instance and are not in your `uses:` lines; you cannot pin
script at the major tag. Wiki publishing is a reusable workflow you call them, but they fetch their scripts at the major tag. A repository that called
(`publish-wiki-pages.yml`); the scoped **Publish wiki** workflow and its `publish-wiki-pages.yml` with `uses:` no longer needs the call: remove the
`wiki/.publish` marker were removed in 2.0.0, so a repository that still has the caller workflow, because the scoped workflow publishes `docs/wiki/` on its own
marker no longer publishes until it calls the reusable workflow (see the (it does not delete pages that are not in the folder).
onboarding guide).
## Reading a changelog entry ## Reading a changelog entry
tests/fixtures/comments/english.tsv
Vendored
+14 -24
View File
@@ -3,7 +3,6 @@ en "string", "char" (a literal of one character) or "none" tools/count_loc.py
en (ADR-0008). The workflow checks out the calling repository, fetches this file tools/quality-checks-cpp.sh en (ADR-0008). The workflow checks out the calling repository, fetches this file tools/quality-checks-cpp.sh
en (MIL-004 task 6). The repository is public, so no token is needed. .gitea/scoped_workflows/sync-github-metadata.yml en (MIL-004 task 6). The repository is public, so no token is needed. .gitea/scoped_workflows/sync-github-metadata.yml
en (compile-commands-dir) are optional. .gitea/workflows/quality-checks-cpp.yml en (compile-commands-dir) are optional. .gitea/workflows/quality-checks-cpp.yml
en (tools/publish_wiki.py), fetched at tools-ref. .gitea/workflows/publish-wiki-pages.yml
en ----------------------------------------------------------------- helpers tests/test_quality_workflows_cpp_csharp.py en ----------------------------------------------------------------- helpers tests/test_quality_workflows_cpp_csharp.py
en --------------------------------------------------------------------- C# tests/test_quality_workflows_cpp_csharp.py en --------------------------------------------------------------------- C# tests/test_quality_workflows_cpp_csharp.py
en --------------------------------------------------------------------- C++ tests/test_quality_workflows_cpp_csharp.py en --------------------------------------------------------------------- C++ tests/test_quality_workflows_cpp_csharp.py
@@ -17,7 +16,7 @@ en A script run: the finished process and the tool calls the stubs logged. tests
en A source file or section needed for a page is missing. tools/build_wiki.py en A source file or section needed for a page is missing. tools/build_wiki.py
en A translation has the same code blocks, table rows and heading levels. tests/test_build_wiki.py en A translation has the same code blocks, table rows and heading levels. tests/test_build_wiki.py
en A wiki that already has pages named with spaces, as Gitea stores them. tests/test_publish_wiki.py en A wiki that already has pages named with spaces, as Gitea stores them. tests/test_publish_wiki.py
en ADR-0009, MIL-009: the scoped publish-wiki.yml and the marker are removed. tests/test_publish_wiki.py en ADR-0009: the marker file is removed. tests/test_publish_wiki.py
en An exact stable version of the .NET SDK, 10 or later (no channel, no range). tools/quality-checks-csharp.sh en An exact stable version of the .NET SDK, 10 or later (no channel, no range). tools/quality-checks-csharp.sh
en An input is invalid; the message is printed as a `[configuration]` failure. tools/badges.py en An input is invalid; the message is printed as a `[configuration]` failure. tools/badges.py
en Answers like the Gitea repository and wiki endpoints. tests/test_publish_wiki.py en Answers like the Gitea repository and wiki endpoints. tests/test_publish_wiki.py
@@ -60,7 +59,6 @@ en Leading emoji and symbols in README headings; removed so anchors stay stable.
en Link text of the sidebar: English, then one list per translation code. tools/build_wiki.py en Link text of the sidebar: English, then one list per translation code. tools/build_wiki.py
en Lint the shell scripts of the composite actions (MIL-012 task 6): shellcheck, tools/lint-action-scripts.sh en Lint the shell scripts of the composite actions (MIL-012 task 6): shellcheck, tools/lint-action-scripts.sh
en MIL-004 Go/No-Go criterion 5: every script is a file under tools/. tests/test_workflows.py en MIL-004 Go/No-Go criterion 5: every script is a file under tools/. tests/test_workflows.py
en Markdown pages of wiki_dir to the wiki of the calling repository, creating .gitea/workflows/publish-wiki-pages.yml
en Needs: bash, find, shellcheck, shfmt tools/lint-action-scripts.sh en Needs: bash, find, shellcheck, shfmt tools/lint-action-scripts.sh
en No translation follows an older version of its English page. tests/test_build_wiki.py en No translation follows an older version of its English page. tests/test_build_wiki.py
en Offline tests for the composite action actions/connect-tailscale. tests/test_connect_tailscale.py en Offline tests for the composite action actions/connect-tailscale. tests/test_connect_tailscale.py
@@ -82,7 +80,6 @@ en One `## [x]` section of the changelog. tools/changelog.py
en One generated wiki page. tools/build_wiki.py en One generated wiki page. tools/build_wiki.py
en Publish accepted milestones to the git host. .gitea/workflows/sync-milestones.yml en Publish accepted milestones to the git host. .gitea/workflows/sync-milestones.yml
en Publish the pages of a folder to the Gitea wiki of the repository. tools/publish_wiki.py en Publish the pages of a folder to the Gitea wiki of the repository. tools/publish_wiki.py
en Publishes the wiki of this repository from docs/wiki/ by calling the .gitea/workflows/publish-own-wiki.yml
en Publishing an empty directory would delete the whole wiki. tools/publish_wiki.py en Publishing an empty directory would delete the whole wiki. tools/publish_wiki.py
en PyYAML reads `on` as True tests/test_code_metrics.py en PyYAML reads `on` as True tests/test_code_metrics.py
en QC_DOTNET_INSTALL_SCRIPT, QC_DOTNET for tests). tools/quality-checks-csharp.sh en QC_DOTNET_INSTALL_SCRIPT, QC_DOTNET for tests). tools/quality-checks-csharp.sh
@@ -125,7 +122,6 @@ en Return the workflow files of this repository that a caller can use. tests/tes
en Return {page key: content} for every Markdown file in wiki_dir. tools/publish_wiki.py en Return {page key: content} for every Markdown file in wiki_dir. tools/publish_wiki.py
en Reusable workflow (ADR-0005). A repository calls it with .gitea/workflows/quality-checks.yml en Reusable workflow (ADR-0005). A repository calls it with .gitea/workflows/quality-checks.yml
en Reusable workflow (ADR-0008). A repository calls it with .gitea/workflows/quality-checks-cpp.yml en Reusable workflow (ADR-0008). A repository calls it with .gitea/workflows/quality-checks-cpp.yml
en Reusable workflow (ADR-0009, MIL-008). A repository calls it with .gitea/workflows/publish-wiki-pages.yml
en Reusable workflow (ADR-0010). A repository calls it with .gitea/workflows/code-metrics.yml en Reusable workflow (ADR-0010). A repository calls it with .gitea/workflows/code-metrics.yml
en Run a tool as `python tools/<name>` with only the given environment. tests/test_tool_entrypoints.py en Run a tool as `python tools/<name>` with only the given environment. tests/test_tool_entrypoints.py
en Run it once by hand from the Actions page with dry_run left on: it prints .gitea/workflows/sync-milestones.yml en Run it once by hand from the Actions page with dry_run left on: it prints .gitea/workflows/sync-milestones.yml
@@ -133,6 +129,7 @@ en Run the generator; return the process exit code. tools/build_wiki.py
en Run the script with a stub wg-quick that records its arguments. tests/test_connect_wireguard.py en Run the script with a stub wg-quick that records its arguments. tests/test_connect_wireguard.py
en SHELLCHECK_PY_VERSION, SHFMT_PY_VERSION, QC_VENV (and QC_BIN for tests). tools/quality-checks.sh en SHELLCHECK_PY_VERSION, SHFMT_PY_VERSION, QC_VENV (and QC_BIN for tests). tools/quality-checks.sh
en Scan one line; return (has_code, has_comment) and update the state. tools/count_loc.py en Scan one line; return (has_code, has_comment) and update the state. tools/count_loc.py
en Scoped workflow: it runs in every repository of an organization, so there is .gitea/scoped_workflows/publish-wiki-pages.yml
en Scoped workflow: it runs in every repository of an organization. The script .gitea/scoped_workflows/sync-github-metadata.yml en Scoped workflow: it runs in every repository of an organization. The script .gitea/scoped_workflows/sync-github-metadata.yml
en Secret: TOKEN_FOR_GITEA, the bare Gitea token of the organization (no JSON). .gitea/workflows/sync-milestones.yml en Secret: TOKEN_FOR_GITEA, the bare Gitea token of the organization (no JSON). .gitea/workflows/sync-milestones.yml
en Settings come from the environment, never from interpolated expressions: tools/code-metrics.sh en Settings come from the environment, never from interpolated expressions: tools/code-metrics.sh
@@ -145,7 +142,6 @@ en Steps of the reusable workflow .gitea/workflows/quality-checks-csharp.yml too
en Steps of the reusable workflow .gitea/workflows/quality-checks.yml (ADR-0005). tools/quality-checks.sh en Steps of the reusable workflow .gitea/workflows/quality-checks.yml (ADR-0005). tools/quality-checks.sh
en Strip heading emoji and rewrite links, leaving fenced code untouched. tools/build_wiki.py en Strip heading emoji and rewrite links, leaving fenced code untouched. tools/build_wiki.py
en Succeeds when one of the named files exists in the working directory or above tools/quality-checks-cpp.sh en Succeeds when one of the named files exists in the working directory or above tools/quality-checks-cpp.sh
en TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }} .gitea/workflows/publish-wiki-pages.yml
en TS_ARGS is split on spaces on purpose: it holds flags, never a secret actions/connect-tailscale/connect-tailscale.sh en TS_ARGS is split on spaces on purpose: it holds flags, never a secret actions/connect-tailscale/connect-tailscale.sh
en TS_AUTHKEY, TS_OAUTH_SECRET, TS_TAGS, TS_HOSTNAME, TS_VERSION, TS_USERSPACE, actions/connect-tailscale/connect-tailscale.sh en TS_AUTHKEY, TS_OAUTH_SECRET, TS_TAGS, TS_HOSTNAME, TS_VERSION, TS_USERSPACE, actions/connect-tailscale/connect-tailscale.sh
en TS_SHA256, TS_ARGS, TS_TIMEOUT, TS_HEALTH_CHECK_HOST. TS_TAILSCALE, actions/connect-tailscale/connect-tailscale.sh en TS_SHA256, TS_ARGS, TS_TIMEOUT, TS_HEALTH_CHECK_HOST. TS_TAILSCALE, actions/connect-tailscale/connect-tailscale.sh
@@ -154,16 +150,16 @@ en TS_WAIT_INTERVAL (seconds) name the commands, the work folder and the waits,
en The Home page names each workflow file of the repository and draws it. tests/test_build_wiki.py en The Home page names each workflow file of the repository and draws it. tests/test_build_wiki.py
en The `if __name__ == "__main__"` block: exit code 1 and ERROR: on stderr. tests/test_tool_entrypoints.py en The `if __name__ == "__main__"` block: exit code 1 and ERROR: on stderr. tests/test_tool_entrypoints.py
en The auth key is passed to tailscale in a file of mode 600, never on a command actions/connect-tailscale/connect-tailscale.sh en The auth key is passed to tailscale in a file of mode 600, never on a command actions/connect-tailscale/connect-tailscale.sh
en The caller file is the opt-in; there is no marker file. It publishes the .gitea/workflows/publish-wiki-pages.yml
en The comment and string rules of one language. tools/count_loc.py en The comment and string rules of one language. tools/count_loc.py
en The commit is the tip of the branch and its validation run is green. tools/release.py en The commit is the tip of the branch and its validation run is green. tools/release.py
en The default `tools-ref` of every reusable workflow names the current major. tests/test_tools_ref.py en The default `tools-ref` of every reusable workflow names the current major. tests/test_tools_ref.py
en The exclude patterns of the caller; a pattern without `/` matches a name anywhere. tools/count_loc.py en The exclude patterns of the caller; a pattern without `/` matches a name anywhere. tools/count_loc.py
en The page a link to a source file should point to. The README is the home page. tools/build_wiki.py en The page a link to a source file should point to. The README is the home page. tools/build_wiki.py
en The pages in wiki/ match what README.md and guides/ produce. tests/test_build_wiki.py en The pages in wiki/ match what README.md and guides/ produce. tests/test_build_wiki.py
en The reusable workflow sets WIKI_PRUNE: the caller is the opt-in (MIL-008). tests/test_publish_wiki.py en The scoped workflow sets WIKI_PRUNE: the docs/wiki folder is the opt-in. tests/test_publish_wiki.py
en The wiki of this repository equals docs/wiki/ (ADR-0009, MIL-008 task 4). tests/test_publish_wiki.py en The wiki of this repository equals docs/wiki/ (ADR-0009): the folder is the opt-in. tests/test_publish_wiki.py
en The workflow checks out the calling repository, fetches this file into tools/code-metrics.sh en The workflow checks out the calling repository, fetches this file into tools/code-metrics.sh
en TirSystem/git-workflows (tools/publish_wiki.py), fetched at v2. .gitea/scoped_workflows/publish-wiki-pages.yml
en Translate an exclude pattern: `*` stops at `/`, `**` crosses it, `?` is one character. tools/count_loc.py en Translate an exclude pattern: `*` stops at `/`, `**` crosses it, `?` is one character. tools/count_loc.py
en Translations (ADR-0001): `<Page>.<code>` written by hand in docs/wiki/. tools/build_wiki.py en Translations (ADR-0001): `<Page>.<code>` written by hand in docs/wiki/. tools/build_wiki.py
en True when the tag holds the file; True when the tag is not in this checkout. tests/test_tools_ref.py en True when the tag holds the file; True when the tag is not in this checkout. tests/test_tools_ref.py
@@ -196,12 +192,9 @@ en and `dotnet build` (warnings as errors) on an exact .NET SDK 10 or later, .gi
en and blank lines are not counted), reads an optional Cobertura XML coverage .gitea/workflows/code-metrics.yml en and blank lines are not counted), reads an optional Cobertura XML coverage .gitea/workflows/code-metrics.yml
en and nothing when none of them changed tools/code-metrics.sh en and nothing when none of them changed tools/code-metrics.sh
en and shfmt in the format .editorconfig sets (two spaces, indented case labels). tools/lint-action-scripts.sh en and shfmt in the format .editorconfig sets (two spaces, indented case labels). tools/lint-action-scripts.sh
en and updating pages, and deleting pages that are not in the folder only when .gitea/workflows/publish-wiki-pages.yml
en branches: [ main ] .gitea/workflows/publish-wiki-pages.yml
en branches: [main] .gitea/workflows/code-metrics.yml en branches: [main] .gitea/workflows/code-metrics.yml
en by default); WG_QUICK, WG_SUDO and WG_PING name the commands, for the tests. actions/connect-wireguard/connect-wireguard.sh en by default); WG_QUICK, WG_SUDO and WG_PING name the commands, for the tests. actions/connect-wireguard/connect-wireguard.sh
en by hand with the version to release; it creates the version tag, the release .gitea/workflows/release.yml en by hand with the version to release; it creates the version tag, the release .gitea/workflows/release.yml
en caller a project copies from framework/templates/ci/publish-wiki.yml, with .gitea/workflows/publish-own-wiki.yml
en changes no file and needs no secret. .gitea/workflows/quality-checks.yml en changes no file and needs no secret. .gitea/workflows/quality-checks.yml
en changes no file and needs no secret. The package restore needs the network. .gitea/workflows/quality-checks-csharp.yml en changes no file and needs no secret. The package restore needs the network. .gitea/workflows/quality-checks-csharp.yml
en clang-tidy at exact versions, changes no file and needs no secret. The .gitea/workflows/quality-checks-cpp.yml en clang-tidy at exact versions, changes no file and needs no secret. The .gitea/workflows/quality-checks-cpp.yml
@@ -222,16 +215,18 @@ en connect-wireguard.sh up write the configuration and bring the tunnel up actio
en contents: write .gitea/workflows/code-metrics.yml en contents: write .gitea/workflows/code-metrics.yml
en deleted. Each run updates the issues of every accepted milestone (the sync is .gitea/workflows/sync-milestones.yml en deleted. Each run updates the issues of every accepted milestone (the sync is .gitea/workflows/sync-milestones.yml
en directory under RUNNER_TEMP by default). tools/code-metrics.sh en directory under RUNNER_TEMP by default). tools/code-metrics.sh
en docs/wiki to the wiki of the repository, creating and updating pages and .gitea/scoped_workflows/publish-wiki-pages.yml
en env keeps the userspace variable through sudo; the file holds the key, so actions/connect-wireguard/connect-wireguard.sh en env keeps the userspace variable through sudo; the file holds the key, so actions/connect-wireguard/connect-wireguard.sh
en finding must fail the check, as a failing tool does for the other languages. tools/quality-checks-cpp.sh en finding must fail the check, as a failing tool does for the other languages. tools/quality-checks-cpp.sh
en for the tests. actions/connect-tailscale/connect-tailscale.sh en for the tests. actions/connect-tailscale/connect-tailscale.sh
en idempotent, but the host records the edit). .gitea/workflows/sync-milestones.yml en idempotent, but the host records the edit). .gitea/workflows/sync-milestones.yml
en installed it on 2026-10-11 at the request of S01. .gitea/workflows/sync-milestones.yml en installed it on 2026-10-11 at the request of S01. .gitea/workflows/sync-milestones.yml
en into shared-scripts/ and runs one command per step: tools/quality-checks-cpp.sh en into shared-scripts/ and runs one command per step: tools/quality-checks-cpp.sh
en is a file of TirSystem/github-action (tools/sync_github_metadata.py), fetched .gitea/scoped_workflows/sync-github-metadata.yml en is a file of TirSystem/git-workflows (tools/sync_github_metadata.py), fetched .gitea/scoped_workflows/sync-github-metadata.yml
en is created or updated as a Milestone with its tasks as Issues. A Proposed .gitea/workflows/sync-milestones.yml en is created or updated as a Milestone with its tasks as Issues. A Proposed .gitea/workflows/sync-milestones.yml
en it is removed when the interface does not come up actions/connect-wireguard/connect-wireguard.sh en it is removed when the interface does not come up actions/connect-wireguard/connect-wireguard.sh
en it, up to the top of the repository: clang-format and clang-tidy find their tools/quality-checks-cpp.sh en it, up to the top of the repository: clang-format and clang-tidy find their tools/quality-checks-cpp.sh
en keeping the pages that are not in the folder. The script is a file of .gitea/scoped_workflows/publish-wiki-pages.yml
en latest Version History row is Accepted and whose latest review record is a Go .gitea/workflows/sync-milestones.yml en latest Version History row is Accepted and whose latest review record is a Go .gitea/workflows/sync-milestones.yml
en line, and nothing else, so the rest of the log stays readable actions/connect-wireguard/connect-wireguard.sh en line, and nothing else, so the rest of the log stays readable actions/connect-wireguard/connect-wireguard.sh
en line. Every failure is printed as ::error::[category] message. actions/connect-tailscale/connect-tailscale.sh en line. Every failure is printed as ::error::[category] message. actions/connect-tailscale/connect-tailscale.sh
@@ -239,6 +234,7 @@ en metrics: .gitea/workflows/code-metrics.yml
en milestone, or one without a Go review, is skipped. Nothing is closed or .gitea/workflows/sync-milestones.yml en milestone, or one without a Go review, is skipped. Nothing is closed or .gitea/workflows/sync-milestones.yml
en name -> (source, code, comment, blank), counted by hand. tests/test_count_loc.py en name -> (source, code, comment, blank), counted by hand. tests/test_count_loc.py
en names that start with GITEA_ or GITHUB_. .gitea/workflows/sync-milestones.yml en names that start with GITEA_ or GITHUB_. .gitea/workflows/sync-milestones.yml
en no caller and no input. A repository opts in by having a docs/wiki folder; a .gitea/scoped_workflows/publish-wiki-pages.yml
en no final newline tests/test_count_loc.py en no final newline tests/test_count_loc.py
en often has no sudo. TS_SUDO overrides it (empty for none). actions/connect-tailscale/connect-tailscale.sh en often has no sudo. TS_SUDO overrides it (empty for none). actions/connect-tailscale/connect-tailscale.sh
en often has no sudo. WG_SUDO overrides it (empty for none). actions/connect-wireguard/connect-wireguard.sh en often has no sudo. WG_SUDO overrides it (empty for none). actions/connect-wireguard/connect-wireguard.sh
@@ -249,10 +245,8 @@ en only the probe ran: no second daemon, no up tests/test_connect_tailscale.py
en outside this repository, so it gets a copy of the repository's file tests/test_lint_action_scripts.py en outside this repository, so it gets a copy of the repository's file tests/test_lint_action_scripts.py
en page from the changelog entry and moves the major tag, and only when the .gitea/workflows/release.yml en page from the changelog entry and moves the major tag, and only when the .gitea/workflows/release.yml
en parsed YAML has no fixed shape tests/test_quality_workflows_cpp_csharp.py en parsed YAML has no fixed shape tests/test_quality_workflows_cpp_csharp.py
en paths: [ "docs/wiki/**" ] .gitea/workflows/publish-wiki-pages.yml
en permissions: .gitea/workflows/code-metrics.yml en permissions: .gitea/workflows/code-metrics.yml
en pretend the kernel has WireGuard and the tools are present tests/test_connect_wireguard.py en pretend the kernel has WireGuard and the tools are present tests/test_connect_wireguard.py
en prune is true. The script is a file of this repository .gitea/workflows/publish-wiki-pages.yml
en quality-checks-cpp.sh install install the exact clang tool versions into a venv tools/quality-checks-cpp.sh en quality-checks-cpp.sh install install the exact clang tool versions into a venv tools/quality-checks-cpp.sh
en quality-checks-cpp.sh run run clang-format and clang-tidy on the tracked files tools/quality-checks-cpp.sh en quality-checks-cpp.sh run run clang-format and clang-tidy on the tracked files tools/quality-checks-cpp.sh
en quality-checks-cpp.sh validate check the inputs, before anything is installed tools/quality-checks-cpp.sh en quality-checks-cpp.sh validate check the inputs, before anything is installed tools/quality-checks-cpp.sh
@@ -267,11 +261,10 @@ en real/a.py only, not link.py tests/test_count_loc.py
en render_config: the wg-quick configuration on stdout actions/connect-wireguard/connect-wireguard.sh en render_config: the wg-quick configuration on stdout actions/connect-wireguard/connect-wireguard.sh
en report (an artifact of an earlier job of the caller, or a file of the .gitea/workflows/code-metrics.yml en report (an artifact of an earlier job of the caller, or a file of the .gitea/workflows/code-metrics.yml
en repository needs a .clang-format; a .clang-tidy and a compile database .gitea/workflows/quality-checks-cpp.yml en repository needs a .clang-format; a .clang-tidy and a compile database .gitea/workflows/quality-checks-cpp.yml
en repository without one is skipped. It publishes the Markdown pages of .gitea/scoped_workflows/publish-wiki-pages.yml
en repository) and commits three SVG badges to a branch of the calling .gitea/workflows/code-metrics.yml en repository) and commits three SVG badges to a branch of the calling .gitea/workflows/code-metrics.yml
en repository, which is checked out as a submodule. Gitea does not accept secret .gitea/workflows/sync-milestones.yml en repository, which is checked out as a submodule. Gitea does not accept secret .gitea/workflows/sync-milestones.yml
en repository. .gitea/workflows/code-metrics.yml en repository. .gitea/workflows/code-metrics.yml
en reusable workflow of this repository (ADR-0009, MIL-008 task 4). It is the .gitea/workflows/publish-own-wiki.yml
en secrets: .gitea/workflows/publish-wiki-pages.yml
en shared-scripts/ and runs one command per step: tools/code-metrics.sh en shared-scripts/ and runs one command per step: tools/code-metrics.sh
en shellcheck disable=SC2206 actions/connect-tailscale/connect-tailscale.sh en shellcheck disable=SC2206 actions/connect-tailscale/connect-tailscale.sh
en shfmt reads .editorconfig from the folder upwards; a temporary folder is tests/test_lint_action_scripts.py en shfmt reads .editorconfig from the folder upwards; a temporary folder is tests/test_lint_action_scripts.py
@@ -284,15 +277,12 @@ en the plan and creates nothing. Turn dry_run off only for a real run. .gitea/wo
en the project gets the compiler diagnostics and the static analyzer. tools/quality-checks-cpp.sh en the project gets the compiler diagnostics and the static analyzer. tools/quality-checks-cpp.sh
en the stub records its arguments and, for `up`, the content of the key file tests/test_connect_tailscale.py en the stub records its arguments and, for `up`, the content of the key file tests/test_connect_tailscale.py
en the tools are in the virtual environment of the interpreter that runs the tests tests/test_lint_action_scripts.py en the tools are in the virtual environment of the interpreter that runs the tests tests/test_lint_action_scripts.py
en tools-ref is main so that the script that is run is the one of this commit. .gitea/workflows/publish-own-wiki.yml
en two differences: the reusable workflow is called by its local path, and .gitea/workflows/publish-own-wiki.yml
en type: ignore[index] tools/changelog.py en type: ignore[index] tools/changelog.py
en type: ignore[return-value] tools/changelog.py en type: ignore[return-value] tools/changelog.py
en uses: TirSystem/github-action/.gitea/workflows/code-metrics.yml@v2 .gitea/workflows/code-metrics.yml en uses: TirSystem/git-workflows/.gitea/workflows/code-metrics.yml@v2 .gitea/workflows/code-metrics.yml
en uses: TirSystem/github-action/.gitea/workflows/publish-wiki-pages.yml@v1 .gitea/workflows/publish-wiki-pages.yml en uses: TirSystem/git-workflows/.gitea/workflows/quality-checks-cpp.yml@v1 .gitea/workflows/quality-checks-cpp.yml
en uses: TirSystem/github-action/.gitea/workflows/quality-checks-cpp.yml@v1 .gitea/workflows/quality-checks-cpp.yml en uses: TirSystem/git-workflows/.gitea/workflows/quality-checks-csharp.yml@v1 .gitea/workflows/quality-checks-csharp.yml
en uses: TirSystem/github-action/.gitea/workflows/quality-checks-csharp.yml@v1 .gitea/workflows/quality-checks-csharp.yml en uses: TirSystem/git-workflows/.gitea/workflows/quality-checks.yml@v1 .gitea/workflows/quality-checks.yml
en uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1 .gitea/workflows/quality-checks.yml
en validate-workflows.yml measures tools/ and fails below the .coveragerc limit. tests/test_workflows.py en validate-workflows.yml measures tools/ and fails below the .coveragerc limit. tests/test_workflows.py
en validate-workflows.yml runs it on every pull request and push to main. tools/lint-action-scripts.sh en validate-workflows.yml runs it on every pull request and push to main. tools/lint-action-scripts.sh
en variables that must reach wg-quick through sudo, which resets the environment actions/connect-wireguard/connect-wireguard.sh en variables that must reach wg-quick through sudo, which resets the environment actions/connect-wireguard/connect-wireguard.sh
Can't render this file because it contains an unexpected character in line 2 and column 11.
tests/test_publish_wiki.py
+44 -38
View File
@@ -9,7 +9,7 @@ import yaml
from workflow_source import REPO_ROOT, load_publish_module from workflow_source import REPO_ROOT, load_publish_module
REUSABLE_WORKFLOW = REPO_ROOT / ".gitea" / "workflows" / "publish-wiki-pages.yml" SCOPED_WORKFLOW = REPO_ROOT / ".gitea" / "scoped_workflows" / "publish-wiki-pages.yml"
API = "https://git.example.test/api/v1" API = "https://git.example.test/api/v1"
REPO_URL = f"{API}/repos/TirSystem/repo" REPO_URL = f"{API}/repos/TirSystem/repo"
@@ -383,7 +383,7 @@ class TestRequestJson:
class TestExplicitPrune: class TestExplicitPrune:
"""The reusable workflow sets WIKI_PRUNE: the caller is the opt-in (MIL-008).""" """The scoped workflow sets WIKI_PRUNE: the docs/wiki folder is the opt-in."""
@pytest.fixture() @pytest.fixture()
def explicit(self, environment, monkeypatch): def explicit(self, environment, monkeypatch):
@@ -428,7 +428,7 @@ class TestExplicitPrune:
monkeypatch.setenv("WIKI_DIR", str(tmp_path / "docs" / "wiki")) monkeypatch.setenv("WIKI_DIR", str(tmp_path / "docs" / "wiki"))
gitea = FakeGitea(publish_wiki) gitea = FakeGitea(publish_wiki)
with pytest.raises(publish_wiki.WorkflowError, match="wiki_dir") as caught: with pytest.raises(publish_wiki.WorkflowError, match="WIKI_DIR") as caught:
run_main(publish_wiki, gitea) run_main(publish_wiki, gitea)
assert caught.value.category == "configuration" assert caught.value.category == "configuration"
@@ -460,59 +460,65 @@ class TestExplicitPrune:
assert gitea.calls == [] assert gitea.calls == []
class TestReusableWorkflow: class TestScopedWorkflow:
@pytest.fixture() @pytest.fixture()
def document(self): def document(self):
return yaml.safe_load(REUSABLE_WORKFLOW.read_text(encoding="utf-8")) return yaml.safe_load(SCOPED_WORKFLOW.read_text(encoding="utf-8"))
def test_is_called_and_has_no_other_trigger(self, document): @pytest.fixture()
assert list(document[True]) == ["workflow_call"] def steps(self, document):
return {step.get("id", step["name"]): step for step in document["jobs"]["publish-wiki"]["steps"]}
def test_the_folder_defaults_to_docs_wiki_and_nothing_is_pruned_by_default(self, document): def test_runs_on_a_push_to_main_and_by_hand_without_inputs(self, document):
inputs = document[True]["workflow_call"]["inputs"] triggers = document[True]
assert inputs["wiki_dir"]["default"] == "docs/wiki" assert list(triggers) == ["push", "workflow_dispatch"]
assert inputs["prune"]["default"] == "false" assert triggers["push"]["branches"] == ["main"]
assert not triggers["workflow_dispatch"]
def test_the_token_is_a_declared_secret_without_a_fallback(self, document): def test_a_push_runs_only_when_docs_wiki_changes(self, document):
text = REUSABLE_WORKFLOW.read_text(encoding="utf-8") assert document[True]["push"]["paths"] == ["docs/wiki/**"]
assert document[True]["workflow_call"]["secrets"]["TOKEN_FOR_GITEA_WIKI"]["required"]
def test_the_token_is_read_from_the_secret_without_a_fallback(self, document):
text = SCOPED_WORKFLOW.read_text(encoding="utf-8")
step = document["jobs"]["publish-wiki"]["steps"][-1]
assert step["env"]["WIKI_CREDENTIALS"] == "${{ secrets.TOKEN_FOR_GITEA_WIKI }}"
assert "secrets.TOKEN_FOR_GITEA }}" not in text assert "secrets.TOKEN_FOR_GITEA }}" not in text
assert "github.token" not in text assert "github.token" not in text
def test_job_has_read_only_permissions(self, document): def test_job_has_read_only_permissions(self, document):
assert document["jobs"]["publish-wiki"]["permissions"] == {"contents": "read"} assert document["jobs"]["publish-wiki"]["permissions"] == {"contents": "read"}
def test_the_inputs_reach_the_script_through_the_environment(self, document): def test_the_settings_reach_the_script_through_the_environment(self, document):
step = document["jobs"]["publish-wiki"]["steps"][-1] step = document["jobs"]["publish-wiki"]["steps"][-1]
assert step["env"]["WIKI_DIR"] == "${{ inputs.wiki_dir }}" assert step["env"]["WIKI_DIR"] == "docs/wiki"
assert step["env"]["WIKI_PRUNE"] == "${{ inputs.prune }}" assert step["env"]["WIKI_PRUNE"] == "false"
assert step["env"]["WIKI_CREDENTIALS"] == "${{ secrets.TOKEN_FOR_GITEA_WIKI }}"
assert step["run"] == "python3 shared-scripts/tools/publish_wiki.py" assert step["run"] == "python3 shared-scripts/tools/publish_wiki.py"
assert "inputs." not in step["run"] assert "inputs." not in step["run"]
def test_the_script_is_fetched_at_the_tools_ref(self, document): def test_the_script_is_fetched_at_v2(self, steps):
fetch = document["jobs"]["publish-wiki"]["steps"][1]["with"] fetch = steps["Fetch the shared script"]["with"]
assert fetch["repository"] == "TirSystem/git-workflows" assert fetch["repository"] == "TirSystem/git-workflows"
assert fetch["ref"] == "${{ inputs.tools-ref }}" assert fetch["ref"] == "v2"
def test_the_folder_check_decides_whether_the_fetch_and_publish_steps_run(self, steps):
assert steps["source"]["name"] == "Look for the wiki folder"
assert "-d docs/wiki" in steps["source"]["run"]
condition = "steps.source.outputs.found == 'true'"
assert steps["Fetch the shared script"]["if"] == condition
assert steps["Publish the pages to the wiki"]["if"] == condition
def test_the_scoped_workflow_is_gone_and_the_script_has_no_marker_path(): def test_this_repository_publishes_docs_wiki_through_the_scoped_workflow():
"""ADR-0009, MIL-009: the scoped publish-wiki.yml and the marker are removed.""" """The wiki of this repository equals docs/wiki/ (ADR-0009): the folder is the opt-in."""
assert not (REPO_ROOT / ".gitea" / "scoped_workflows" / "publish-wiki.yml").exists() assert SCOPED_WORKFLOW.is_file()
assert not (REPO_ROOT / ".gitea" / "workflows" / "publish-own-wiki.yml").exists()
assert not (REPO_ROOT / ".gitea" / "workflows" / "publish-wiki-pages.yml").exists()
assert not (REPO_ROOT / "wiki").exists()
assert (REPO_ROOT / "docs" / "wiki" / "Home.md").is_file()
def test_the_script_has_no_marker_path():
"""ADR-0009: the marker file is removed."""
source = (REPO_ROOT / "tools" / "publish_wiki.py").read_text(encoding="utf-8") source = (REPO_ROOT / "tools" / "publish_wiki.py").read_text(encoding="utf-8")
assert "MARKER_NAME" not in source assert "MARKER_NAME" not in source
assert "parse_marker" not in source assert "parse_marker" not in source
def test_this_repository_publishes_docs_wiki_through_the_reusable_workflow():
"""The wiki of this repository equals docs/wiki/ (ADR-0009, MIL-008 task 4)."""
assert not (REPO_ROOT / "wiki").exists()
assert (REPO_ROOT / "docs" / "wiki" / "Home.md").is_file()
caller = yaml.safe_load(
(REPO_ROOT / ".gitea" / "workflows" / "publish-own-wiki.yml").read_text(encoding="utf-8")
)
job = caller["jobs"]["wiki"]
assert job["uses"] == "./.gitea/workflows/publish-wiki-pages.yml"
assert job["with"]["wiki_dir"] == "docs/wiki"
assert job["with"]["prune"] == "true"
assert caller[True]["push"]["paths"] == ["docs/wiki/**"]
tools/publish_wiki.py
+5 -4
View File
@@ -1,8 +1,9 @@
"""Publish the pages of a folder to the Gitea wiki of the repository. """Publish the pages of a folder to the Gitea wiki of the repository.
Run by the reusable workflow publish-wiki-pages.yml, which a repository calls Run by the scoped workflow publish-wiki-pages.yml, which runs in every
(ADR-0009). The caller is the opt-in: the workflow sets WIKI_PRUNE and the repository of the organization. A repository opts in by having the docs/wiki
folder must exist. It reads its settings from the environment: folder; the workflow sets WIKI_PRUNE. It reads its settings from the
environment:
GITEA_API_URL Gitea API base, for example https://host/api/v1 GITEA_API_URL Gitea API base, for example https://host/api/v1
SOURCE_REPOSITORY owner/repo of the repository whose wiki is written SOURCE_REPOSITORY owner/repo of the repository whose wiki is written
@@ -244,7 +245,7 @@ def main():
raise WorkflowError( raise WorkflowError(
"configuration", "configuration",
f"The wiki folder {wiki_dir} does not exist in {owner}/{repo}; " f"The wiki folder {wiki_dir} does not exist in {owner}/{repo}; "
"set the wiki_dir input to the folder with the pages.", "create the folder with the pages, or set WIKI_DIR to it.",
) )
pages = read_pages(wiki_dir) pages = read_pages(wiki_dir)