Merge pull request 'MIL-009: remove the scoped publish-wiki workflow and the marker; ADR-0004 superseded' (#151) from mil-009-remove-scoped into main
Publish accepted milestones / publish (push) Successful in 44s
Validate workflows / validate (push) Successful in 23s
TirSystem/github-action: Sync GitHub mirror metadata / sync-metadata (push) Successful in 5s
Publish wiki / publish-wiki (push) Successful in 28s
Publish own wiki / wiki (push) Successful in 28s
Publish accepted milestones / publish (push) Successful in 44s
Validate workflows / validate (push) Successful in 23s
TirSystem/github-action: Sync GitHub mirror metadata / sync-metadata (push) Successful in 5s
Publish wiki / publish-wiki (push) Successful in 28s
Publish own wiki / wiki (push) Successful in 28s
This commit was merged in pull request #151.
This commit is contained in:
@@ -1,48 +0,0 @@
|
||||
name: Publish wiki
|
||||
|
||||
# DEPRECATED (ADR-0009, MIL-008): repositories publish their wiki by calling
|
||||
# the reusable workflow publish-wiki-pages.yml. This scoped workflow stays
|
||||
# until every repository that has wiki/.publish has migrated; it is then
|
||||
# removed in a later major release.
|
||||
|
||||
# Shared through scoped delivery: it runs in every repository of an
|
||||
# organization, but writes only where the repository has opted in with
|
||||
# wiki/.publish (ADR-0004). TOKEN_FOR_GITEA_WIKI is read from the organization
|
||||
# secrets; there is no fallback to the read-only sync token. The script is a
|
||||
# file of TirSystem/github-action (tools/publish_wiki.py), fetched with a
|
||||
# second checkout so that it is readable, lintable and tested as a file
|
||||
# (MIL-004 task 6).
|
||||
on:
|
||||
push:
|
||||
branches: [ main ]
|
||||
paths:
|
||||
- "wiki/**"
|
||||
workflow_dispatch:
|
||||
|
||||
concurrency:
|
||||
group: publish-wiki
|
||||
cancel-in-progress: false
|
||||
|
||||
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/github-action
|
||||
ref: v1
|
||||
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 }}
|
||||
run: python3 shared-scripts/tools/publish_wiki.py
|
||||
@@ -20,6 +20,31 @@ Each release lists its changes in these groups, in this order:
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
## [2.0.0] - 2026-10-14
|
||||
|
||||
### Breaking
|
||||
|
||||
- The scoped workflow `publish-wiki.yml` and the `wiki/.publish` marker are
|
||||
removed (ADR-0009, MIL-009). A repository publishes its wiki by calling the
|
||||
reusable workflow `publish-wiki-pages.yml`; one that still has the marker no
|
||||
longer publishes. The seven repositories that used the scoped workflow on
|
||||
2026-10-13 have a caller (checked on 2026-10-14). A repository that has
|
||||
`wiki/.publish` moves `wiki/` to `docs/wiki/`, copies
|
||||
`templates/ci/publish-wiki.yml` of the SQA and QC framework (0.7.0 or later)
|
||||
to `.gitea/workflows/publish-wiki.yml` and removes the marker.
|
||||
- `tools/publish_wiki.py` requires `WIKI_PRUNE` (`true` or `false`) and no longer
|
||||
reads a marker; `WIKI_DIR` defaults to `docs/wiki`.
|
||||
|
||||
### Changed
|
||||
|
||||
- The README, the onboarding, troubleshooting and upgrading guides and the
|
||||
wiki pages (English, Danish, Bahasa Malaysia) no longer describe the scoped
|
||||
workflow or the marker.
|
||||
- ADR-0004 is `Superseded by ADR-0009`.
|
||||
- Callers of `quality-checks.yml`, `quality-checks-cpp.yml`,
|
||||
`quality-checks-csharp.yml`, `release.yml` and `publish-wiki-pages.yml` need no
|
||||
change; `v1` stays at 1.2.2 and `v2` is the new moving major tag.
|
||||
|
||||
## [1.2.2] - 2026-10-13
|
||||
|
||||
### Added
|
||||
|
||||
@@ -17,16 +17,15 @@ 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.
|
||||
|
||||
It contains ten workflows: metadata sync to the GitHub mirror, wiki publishing (scoped, and reusable for repositories that call it), shared quality checks for Python and shell, for C and C++ and for C#, 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 nine 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#, 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
|
||||
|
||||
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.
|
||||
Nine 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 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 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 | [`publish-wiki.yml`](.gitea/scoped_workflows/publish-wiki.yml) | Scoped, opt-in with `wiki/.publish`; deprecated, replaced by the reusable workflow below (ADR-0009) | push to `main` that changes `wiki/**`, manual | Publishes the pages in `wiki/` to the repository wiki |
|
||||
| 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 |
|
||||
| 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 |
|
||||
@@ -102,50 +101,6 @@ deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### 📖 Publish wiki (scoped, deprecated)
|
||||
|
||||
Publishes `wiki/` to the repository wiki, only in a repository that has opted in with `wiki/.publish`. The word `prune` in that file also deletes pages that are not in `wiki/`.
|
||||
|
||||
#### 🔀 Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish wiki/ to the repository wiki
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Push to main that changes wiki/**,\nor manual trigger" as Trigger
|
||||
participant "Gitea Actions\npublish-wiki" as Workflow
|
||||
participant "shared-scripts\n(tools/publish_wiki.py at v1)" as Script
|
||||
participant "Gitea wiki API" as Wiki
|
||||
|
||||
Trigger -> Workflow: Start workflow
|
||||
activate Workflow
|
||||
Workflow -> Script: Check out the repository and the script, run it
|
||||
activate Script
|
||||
|
||||
alt wiki/.publish does not exist
|
||||
Script --> Workflow: Log that publishing is not enabled and succeed\n(nothing is written)
|
||||
else wiki/ has no Markdown pages
|
||||
Script --> Workflow: Fail with [configuration]\n(an empty wiki/ never deletes pages)
|
||||
else
|
||||
Script -> Script: Read the marker (empty, or the word prune)\nand TOKEN_FOR_GITEA_WIKI
|
||||
Script -> Wiki: GET repository (preflight)
|
||||
Wiki --> Script: Wiki is enabled, token accepted
|
||||
Script -> Wiki: GET pages
|
||||
Wiki --> Script: Existing pages
|
||||
Script -> Wiki: Create new pages, update changed pages
|
||||
opt marker says prune
|
||||
Script -> Wiki: Delete pages that are not in wiki/
|
||||
end
|
||||
Script --> Workflow: Log created, updated and deleted counts
|
||||
end
|
||||
deactivate Script
|
||||
Workflow --> Trigger: Workflow result
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### ✅ Quality checks
|
||||
|
||||
A reusable workflow for Python and shell, called with `uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1` (see the [guide](guides/quality-checks.md)).
|
||||
@@ -542,8 +497,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 |
|
||||
| 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) |
|
||||
| Publish a repository wiki from `wiki/` (opt-in, delivered to every organization) | Implemented in `.gitea/scoped_workflows/publish-wiki.yml`, with offline tests; a pilot in a second repository publishes its wiki (MIL-006); being replaced by the reusable workflow below (ADR-0009) |
|
||||
| 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; this repository's own wiki is in `docs/wiki/` and published by it through `publish-own-wiki.yml`; not yet called from another repository (MIL-008) |
|
||||
| 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) |
|
||||
| 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)) |
|
||||
| Versioned release and publishing | Release process, changelog and upgrade guide defined; the release workflow exists and `v1.0.0` is released (MIL-004) ([guide](guides/upgrading.md)) |
|
||||
|
||||
@@ -4,13 +4,13 @@
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | ADR-0004 |
|
||||
| CrossReference | [MIL-006], [ADR-0003], [ADR-0002] |
|
||||
| CrossReference | [MIL-006], [ADR-0003], [ADR-0002], [ADR-0009] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | [b22a2cd] |
|
||||
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Reviewed (RC-018): the `prune` variant added to the evaluated options | [b22a2cd] |
|
||||
| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Reviewed (RC-018): the `prune` variant added to the evaluated options | [b22a2cd] |
|
||||
| 2026-10-14 | Superseded by ADR-0009 | Jens Tirsvad Nielsen | AI as stand-in for S01 | The scoped delivery and the `wiki/.publish` marker are replaced by the reusable workflow of ADR-0009 and removed (MIL-009); the token and the empty-folder rules stand and are carried by ADR-0009; reviewed (RC-065) | [22fc323] |
|
||||
|
||||
Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
|
||||
|
||||
@@ -108,10 +108,13 @@ The rules that follow from it:
|
||||
- [ADR-0003] — its fallback to `TOKEN_FOR_GITEA` no longer applies to the
|
||||
shared workflow.
|
||||
- [ADR-0002] — the stand-in rule applies to the review of this ADR.
|
||||
- [ADR-0009] — the successor: the reusable workflow replaces the scoped delivery and the marker.
|
||||
|
||||
---
|
||||
|
||||
[MIL-006]: ../milestones/mil-006-shared-wiki-publishing.md
|
||||
[ADR-0003]: ./adr-0003-wiki-publish-token.md
|
||||
[ADR-0002]: ./adr-0002-s01-approves-as-stand-in.md
|
||||
[ADR-0009]: ./adr-0009-wiki-publishing-reusable-workflow.md
|
||||
[b22a2cd]: https://git.tirsystem.com/TirSystem/github-action/commit/b22a2cd59235078656c4440b945b787f88fbd345
|
||||
[22fc323]: https://git.tirsystem.com/TirSystem/github-action/commit/22fc323b41074ee0029ea2f07445a8e329e15d15
|
||||
|
||||
@@ -11,7 +11,7 @@ each document lives in *this* project and the next version to use.
|
||||
| SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 |
|
||||
| PP | Project Plan | docs/project-plan.md | 002 |
|
||||
| MIL | Milestone / Gateway | docs/milestones/*.md | 010 |
|
||||
| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 065 |
|
||||
| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 066 |
|
||||
| TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
|
||||
| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0010 |
|
||||
| UCD | Use Case Diagram | docs/use-case-diagram.md | 002 |
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
# Review Record: ADR-0004 superseded by ADR-0009
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | RC-065 |
|
||||
| CrossReference | [ADR-0004], [ADR-0009], [QC-ADR-001], [MIL-009] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [22fc323] |
|
||||
|
||||
---
|
||||
|
||||
## Artifact Under Review
|
||||
|
||||
- Instance reviewed: [ADR-0004] after the status change to `Superseded by ADR-0009` on 2026-10-14
|
||||
- Checklist used: [QC-ADR-001]
|
||||
- Scope: delta re-review of the criteria the status change touches (7, 8, 9, 11); the earlier record is RC-018
|
||||
- Language and domain: n/a (technical type)
|
||||
- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan [MIL-009] in chat on 2026-10-14)
|
||||
|
||||
## Checklist Results
|
||||
|
||||
| # | Criterion | Status | Evidence/Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | The ID matches the filename number and is unique and sequential | Pass | Unchanged. |
|
||||
| 2 | Context states the problem, the forces and the options evaluated | Pass | Unchanged. |
|
||||
| 3 | At least two options were considered | Pass | Unchanged. |
|
||||
| 4 | Decision is stated in one or two unhedged sentences and matches an evaluated option | Pass | Unchanged. |
|
||||
| 5 | Consequences list both Positive and Negative outcomes | Pass | Unchanged. |
|
||||
| 6 | Quality-attribute impacts are named where the decision affects them | Pass | Unchanged. |
|
||||
| 7 | Affected Artifacts are listed as links, and each is also in CrossReference | Pass | ADR-0009 is added to both. |
|
||||
| 8 | Status changes are recorded as new Version History rows with a Change summary and Commit link; retained rows are never rewritten | Pass | The change is a new row; the earlier `Accepted` row became `Deprecated` and its content is unchanged. |
|
||||
| 9 | A superseded or deprecated ADR names its successor, and the successor links back | Pass | The status names ADR-0009; ADR-0009 lists ADR-0004 under Affected Artifacts and in CrossReference. This closes the N-A of RC-018. |
|
||||
| 10 | Written in the language of the domain, with no unexplained abbreviations | Pass | Unchanged. |
|
||||
| 11 | Status is one of the allowed values and every row uses only these | Pass | `Deprecated` and `Superseded by ADR-0009`. |
|
||||
|
||||
## Overall Verdict
|
||||
|
||||
Go - all criteria pass. The scoped delivery and the marker are replaced and removed (MIL-009 tasks 2 to 6); the token and empty-folder rules of this ADR stand and are carried by ADR-0009. The AI records the acceptance as stand-in for S01; there is no independent reader, and the decision stays open to challenge in the run summary.
|
||||
|
||||
## Action Items
|
||||
|
||||
| Action | Owner | Due |
|
||||
| --- | --- | --- |
|
||||
| None open | - | - |
|
||||
|
||||
---
|
||||
|
||||
[ADR-0004]: ../../adr/adr-0004-shared-wiki-publishing-opt-in.md
|
||||
[ADR-0009]: ../../adr/adr-0009-wiki-publishing-reusable-workflow.md
|
||||
[QC-ADR-001]: ../../../framework/qc/artifacts/qc-adr.md
|
||||
[MIL-009]: ../../milestones/mil-009-migrate-wiki-callers-and-remove-scoped-workflow.md
|
||||
[22fc323]: https://git.tirsystem.com/TirSystem/github-action/commit/22fc323b41074ee0029ea2f07445a8e329e15d15
|
||||
@@ -4,13 +4,13 @@
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | TM-001 |
|
||||
| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [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], [ADR-0007], [ADR-0008], [ADR-0009], [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], [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], [ADR-0007], [ADR-0008], [ADR-0009], [UC-007], [UC-006], [ADR-0006], [UC-005], [ADR-0005], [UCD-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [ADR-0001], [ADR-0002], [ADR-0003], [ADR-0004] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-13 | Proposed | Jens Tirsvad Nielsen | S01 | Added MIL-009 and RC-064 (the MIL-009 plan row) | [86e69ce] |
|
||||
| 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | MIL-009, PP-001 and RC-064 accepted | [2f267df] |
|
||||
| 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | Added RC-065 (ADR-0004 superseded by ADR-0009) | [22fc323] |
|
||||
|
||||
---
|
||||
|
||||
@@ -49,7 +49,7 @@ updated whenever an artifact instance is created or reviewed.
|
||||
| [ADR-0001] | ADR | [BC-001], [MIL-005] | [ADR-0003] | [RC-012] |
|
||||
| [ADR-0002] | ADR | [SA-001], [RC-001] | - | [RC-013] |
|
||||
| [ADR-0003] | ADR | [MIL-005], [ADR-0001], [RC-011] | [ADR-0004] | [RC-014] |
|
||||
| [ADR-0004] | ADR | [MIL-006], [ADR-0003], [ADR-0002] | - | [RC-018] |
|
||||
| [ADR-0004] | ADR | [MIL-006], [ADR-0003], [ADR-0002] | [ADR-0009] | [RC-018], [RC-065] |
|
||||
| [RC-011] | RC | [MIL-005] | - | - |
|
||||
| [RC-012] | RC | [ADR-0001] | - | - |
|
||||
| [RC-013] | RC | [ADR-0002] | - | - |
|
||||
@@ -118,6 +118,7 @@ updated whenever an artifact instance is created or reviewed.
|
||||
| [RC-062] | RC | [PP-001] | - | - |
|
||||
| [RC-063] | RC | [ADR-0009] | - | - |
|
||||
| [RC-064] | RC | [MIL-009], [PP-001] | - | - |
|
||||
| [RC-065] | RC | [ADR-0004] | - | - |
|
||||
|
||||
## Coverage Notes
|
||||
|
||||
@@ -214,6 +215,7 @@ updated whenever an artifact instance is created or reviewed.
|
||||
[RC-062]: ./reviews/rc-062-pp-001-mil-008.md
|
||||
[RC-063]: ./reviews/rc-063-adr-0009.md
|
||||
[RC-064]: ./reviews/rc-064-mil-009-plan.md
|
||||
[RC-065]: ./reviews/rc-065-adr-0004-superseded.md
|
||||
[ADR-0008]: ../adr/adr-0008-cpp-csharp-quality-check-contract.md
|
||||
[ADR-0009]: ../adr/adr-0009-wiki-publishing-reusable-workflow.md
|
||||
[ADR-0007]: ../adr/adr-0007-release-publish-destination.md
|
||||
@@ -224,5 +226,5 @@ updated whenever an artifact instance is created or reviewed.
|
||||
[ADR-0005]: ../adr/adr-0005-quality-check-contract.md
|
||||
[faf13b2]: https://git.tirsystem.com/TirSystem/github-action/commit/faf13b2c2a4901c0171977de1ffc2841023f537a
|
||||
[1bc56f8]: https://git.tirsystem.com/TirSystem/github-action/commit/1bc56f8b771531f221f218fc00b147ecc73c051e
|
||||
[86e69ce]: https://git.tirsystem.com/TirSystem/github-action/commit/86e69ce85df72ea3caed40253e08231c73187fde
|
||||
[2f267df]: https://git.tirsystem.com/TirSystem/github-action/commit/2f267df2a270087cb7dc482af4ce4f4341e97b03
|
||||
[22fc323]: https://git.tirsystem.com/TirSystem/github-action/commit/22fc323b41074ee0029ea2f07445a8e329e15d15
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Capabilities.md, source sha256 c60d434988dc -->
|
||||
<!-- translation of Capabilities.md, source sha256 7c310ccc1a66 -->
|
||||
|
||||
> Dette er en oversættelse af [`Capabilities`](Capabilities). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
|
||||
|
||||
@@ -13,8 +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 |
|
||||
| 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) |
|
||||
| Publicering af et repositorys wiki fra `wiki/` (tilmelding, leveres til alle organisationer) | Implementeret i `.gitea/scoped_workflows/publish-wiki.yml`, med offline-tests; et pilotforsøg i et andet repository publicerer sin wiki (MIL-006); afløses af det genbrugelige workflow nedenfor (ADR-0009) |
|
||||
| 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; dette repositorys egen wiki er i `docs/wiki/` og publiceres af det gennem `publish-own-wiki.yml`; endnu ikke kaldt fra et andet repository (MIL-008) |
|
||||
| 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) |
|
||||
| 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)) |
|
||||
| Versioneret udgivelse og publicering | Udgivelsesproces, changelog og opgraderingsvejledning er defineret; udgivelsesworkflowet findes, og `v1.0.0` er udgivet (MIL-004) ([vejledning](Upgrading.da)) |
|
||||
|
||||
@@ -13,8 +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 |
|
||||
| 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) |
|
||||
| Publish a repository wiki from `wiki/` (opt-in, delivered to every organization) | Implemented in `.gitea/scoped_workflows/publish-wiki.yml`, with offline tests; a pilot in a second repository publishes its wiki (MIL-006); being replaced by the reusable workflow below (ADR-0009) |
|
||||
| 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; this repository's own wiki is in `docs/wiki/` and published by it through `publish-own-wiki.yml`; not yet called from another repository (MIL-008) |
|
||||
| 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) |
|
||||
| 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)) |
|
||||
| Versioned release and publishing | Release process, changelog and upgrade guide defined; the release workflow exists and `v1.0.0` is released (MIL-004) ([guide](Upgrading)) |
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Capabilities.md, source sha256 c60d434988dc -->
|
||||
<!-- translation of Capabilities.md, source sha256 7c310ccc1a66 -->
|
||||
|
||||
> Ini ialah terjemahan [`Capabilities`](Capabilities). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
|
||||
|
||||
@@ -13,8 +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 |
|
||||
| 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) |
|
||||
| Menerbitkan wiki repositori daripada `wiki/` (pilih menyertai, dihantar ke setiap organisasi) | Dilaksanakan dalam `.gitea/scoped_workflows/publish-wiki.yml`, dengan ujian luar talian; satu juruterbang dalam repositori kedua menerbitkan wikinya (MIL-006); sedang diganti oleh aliran kerja boleh guna semula di bawah (ADR-0009) |
|
||||
| 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; wiki repositori ini sendiri ada dalam `docs/wiki/` dan diterbitkan olehnya melalui `publish-own-wiki.yml`; belum dipanggil daripada repositori lain (MIL-008) |
|
||||
| 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) |
|
||||
| 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)) |
|
||||
| Keluaran berversi dan penerbitan | Proses keluaran, changelog dan panduan naik taraf telah ditakrifkan; aliran kerja keluaran sudah ada dan `v1.0.0` telah dikeluarkan (MIL-004) ([panduan](Upgrading.ms)) |
|
||||
|
||||
+3
-48
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Home.md, source sha256 b6796554f4eb -->
|
||||
<!-- translation of Home.md, source sha256 074ce16f3435 -->
|
||||
|
||||
> Dette er en oversættelse af [`Home`](Home). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
|
||||
|
||||
@@ -13,17 +13,16 @@ 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.
|
||||
|
||||
Det indeholder ti workflows: synkronisering af metadata til GitHub-spejlet, publicering af wiki (scoped og genbrugeligt for repositories, der kalder det), fælles kvalitetskontrol for Python og shell, for C og C++ og for C#, et udgivelsesworkflow, publicering af accepterede milepæle og repositoryets egen validering. De er listet med formål og diagram under [Workflows](#workflows).
|
||||
Det indeholder ni 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#, et udgivelsesworkflow, publicering af accepterede milepæle og repositoryets egen validering. De er listet med formål og diagram under [Workflows](#workflows).
|
||||
|
||||
|
||||
## Workflows
|
||||
|
||||
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.
|
||||
Der er ni 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 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Sync GitHub mirror metadata | [`sync-github-metadata.yml`](https://git.tirsystem.com/TirSystem/github-action/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 | [`publish-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/scoped_workflows/publish-wiki.yml) | Scoped, tilmelding med `wiki/.publish`; forældet, afløses af det genbrugelige workflow nedenfor (ADR-0009) | push til `main`, der ændrer `wiki/**`, manuelt | Publicerer siderne i `wiki/` til repositoryets wiki |
|
||||
| Publish wiki pages | [`publish-wiki-pages.yml`](https://git.tirsystem.com/TirSystem/github-action/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 |
|
||||
| Quality checks | [`quality-checks.yml`](https://git.tirsystem.com/TirSystem/github-action/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/github-action/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 |
|
||||
@@ -99,50 +98,6 @@ deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Publicering af wiki (scoped, forældet)
|
||||
|
||||
Publicerer `wiki/` til repositoryets wiki, kun i et repository, der har tilmeldt sig med `wiki/.publish`. Ordet `prune` i den fil sletter også sider, som ikke findes i `wiki/`.
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish wiki/ to the repository wiki
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Push to main that changes wiki/**,\nor manual trigger" as Trigger
|
||||
participant "Gitea Actions\npublish-wiki" as Workflow
|
||||
participant "shared-scripts\n(tools/publish_wiki.py at v1)" as Script
|
||||
participant "Gitea wiki API" as Wiki
|
||||
|
||||
Trigger -> Workflow: Start workflow
|
||||
activate Workflow
|
||||
Workflow -> Script: Check out the repository and the script, run it
|
||||
activate Script
|
||||
|
||||
alt wiki/.publish does not exist
|
||||
Script --> Workflow: Log that publishing is not enabled and succeed\n(nothing is written)
|
||||
else wiki/ has no Markdown pages
|
||||
Script --> Workflow: Fail with [configuration]\n(an empty wiki/ never deletes pages)
|
||||
else
|
||||
Script -> Script: Read the marker (empty, or the word prune)\nand TOKEN_FOR_GITEA_WIKI
|
||||
Script -> Wiki: GET repository (preflight)
|
||||
Wiki --> Script: Wiki is enabled, token accepted
|
||||
Script -> Wiki: GET pages
|
||||
Wiki --> Script: Existing pages
|
||||
Script -> Wiki: Create new pages, update changed pages
|
||||
opt marker says prune
|
||||
Script -> Wiki: Delete pages that are not in wiki/
|
||||
end
|
||||
Script --> Workflow: Log created, updated and deleted counts
|
||||
end
|
||||
deactivate Script
|
||||
Workflow --> Trigger: Workflow result
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Kvalitetskontrol
|
||||
|
||||
Et genbrugeligt workflow til Python og shell, kaldt med `uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1` (se [vejledningen](QualityChecksPythonShell)).
|
||||
|
||||
+2
-47
@@ -13,17 +13,16 @@ 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.
|
||||
|
||||
It contains ten workflows: metadata sync to the GitHub mirror, wiki publishing (scoped, and reusable for repositories that call it), shared quality checks for Python and shell, for C and C++ and for C#, 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 nine 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#, 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
|
||||
|
||||
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.
|
||||
Nine 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 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Sync GitHub mirror metadata | [`sync-github-metadata.yml`](https://git.tirsystem.com/TirSystem/github-action/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 | [`publish-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/scoped_workflows/publish-wiki.yml) | Scoped, opt-in with `wiki/.publish`; deprecated, replaced by the reusable workflow below (ADR-0009) | push to `main` that changes `wiki/**`, manual | Publishes the pages in `wiki/` to the repository wiki |
|
||||
| Publish wiki pages | [`publish-wiki-pages.yml`](https://git.tirsystem.com/TirSystem/github-action/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 |
|
||||
| Quality checks | [`quality-checks.yml`](https://git.tirsystem.com/TirSystem/github-action/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/github-action/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 |
|
||||
@@ -99,50 +98,6 @@ deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Publish wiki (scoped, deprecated)
|
||||
|
||||
Publishes `wiki/` to the repository wiki, only in a repository that has opted in with `wiki/.publish`. The word `prune` in that file also deletes pages that are not in `wiki/`.
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish wiki/ to the repository wiki
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Push to main that changes wiki/**,\nor manual trigger" as Trigger
|
||||
participant "Gitea Actions\npublish-wiki" as Workflow
|
||||
participant "shared-scripts\n(tools/publish_wiki.py at v1)" as Script
|
||||
participant "Gitea wiki API" as Wiki
|
||||
|
||||
Trigger -> Workflow: Start workflow
|
||||
activate Workflow
|
||||
Workflow -> Script: Check out the repository and the script, run it
|
||||
activate Script
|
||||
|
||||
alt wiki/.publish does not exist
|
||||
Script --> Workflow: Log that publishing is not enabled and succeed\n(nothing is written)
|
||||
else wiki/ has no Markdown pages
|
||||
Script --> Workflow: Fail with [configuration]\n(an empty wiki/ never deletes pages)
|
||||
else
|
||||
Script -> Script: Read the marker (empty, or the word prune)\nand TOKEN_FOR_GITEA_WIKI
|
||||
Script -> Wiki: GET repository (preflight)
|
||||
Wiki --> Script: Wiki is enabled, token accepted
|
||||
Script -> Wiki: GET pages
|
||||
Wiki --> Script: Existing pages
|
||||
Script -> Wiki: Create new pages, update changed pages
|
||||
opt marker says prune
|
||||
Script -> Wiki: Delete pages that are not in wiki/
|
||||
end
|
||||
Script --> Workflow: Log created, updated and deleted counts
|
||||
end
|
||||
deactivate Script
|
||||
Workflow --> Trigger: Workflow result
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Quality checks
|
||||
|
||||
A reusable workflow for Python and shell, called with `uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1` (see the [guide](QualityChecksPythonShell)).
|
||||
|
||||
+3
-48
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Home.md, source sha256 b6796554f4eb -->
|
||||
<!-- translation of Home.md, source sha256 074ce16f3435 -->
|
||||
|
||||
> Ini ialah terjemahan [`Home`](Home). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
|
||||
|
||||
@@ -13,17 +13,16 @@ 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.
|
||||
|
||||
Ia mengandungi sepuluh aliran kerja: penyegerakan metadata ke cermin GitHub, penerbitan wiki (scoped, dan boleh guna semula bagi repositori yang memanggilnya), semakan kualiti bersama untuk Python dan shell, untuk C dan C++ serta untuk C#, 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 sembilan 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#, 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
|
||||
|
||||
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.
|
||||
Terdapat sembilan 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 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Sync GitHub mirror metadata | [`sync-github-metadata.yml`](https://git.tirsystem.com/TirSystem/github-action/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 | [`publish-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/scoped_workflows/publish-wiki.yml) | Scoped, pilih menyertai dengan `wiki/.publish`; usang, sedang diganti oleh aliran kerja boleh guna semula di bawah (ADR-0009) | push ke `main` yang mengubah `wiki/**`, manual | Menerbitkan halaman dalam `wiki/` ke wiki repositori |
|
||||
| Publish wiki pages | [`publish-wiki-pages.yml`](https://git.tirsystem.com/TirSystem/github-action/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 |
|
||||
| Quality checks | [`quality-checks.yml`](https://git.tirsystem.com/TirSystem/github-action/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/github-action/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 |
|
||||
@@ -99,50 +98,6 @@ deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Menerbitkan wiki (scoped, usang)
|
||||
|
||||
Menerbitkan `wiki/` ke wiki repositori, hanya dalam repositori yang telah menyertai dengan `wiki/.publish`. Perkataan `prune` dalam fail itu juga memadam halaman yang tiada dalam `wiki/`.
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish wiki/ to the repository wiki
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Push to main that changes wiki/**,\nor manual trigger" as Trigger
|
||||
participant "Gitea Actions\npublish-wiki" as Workflow
|
||||
participant "shared-scripts\n(tools/publish_wiki.py at v1)" as Script
|
||||
participant "Gitea wiki API" as Wiki
|
||||
|
||||
Trigger -> Workflow: Start workflow
|
||||
activate Workflow
|
||||
Workflow -> Script: Check out the repository and the script, run it
|
||||
activate Script
|
||||
|
||||
alt wiki/.publish does not exist
|
||||
Script --> Workflow: Log that publishing is not enabled and succeed\n(nothing is written)
|
||||
else wiki/ has no Markdown pages
|
||||
Script --> Workflow: Fail with [configuration]\n(an empty wiki/ never deletes pages)
|
||||
else
|
||||
Script -> Script: Read the marker (empty, or the word prune)\nand TOKEN_FOR_GITEA_WIKI
|
||||
Script -> Wiki: GET repository (preflight)
|
||||
Wiki --> Script: Wiki is enabled, token accepted
|
||||
Script -> Wiki: GET pages
|
||||
Wiki --> Script: Existing pages
|
||||
Script -> Wiki: Create new pages, update changed pages
|
||||
opt marker says prune
|
||||
Script -> Wiki: Delete pages that are not in wiki/
|
||||
end
|
||||
Script --> Workflow: Log created, updated and deleted counts
|
||||
end
|
||||
deactivate Script
|
||||
Workflow --> Trigger: Workflow result
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Semakan kualiti
|
||||
|
||||
Aliran kerja boleh guna semula untuk Python dan shell, dipanggil dengan `uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1` (lihat [panduan](QualityChecksPythonShell)).
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Onboarding.md, source sha256 4de4897fb3b7 -->
|
||||
<!-- translation of Onboarding.md, source sha256 1bc66efd5874 -->
|
||||
|
||||
> Dette er en oversættelse af [`Onboarding`](Onboarding). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
|
||||
|
||||
@@ -56,8 +56,6 @@ Det genbrugelige workflow **Publish wiki pages** kopierer Markdown-siderne i `do
|
||||
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>`.
|
||||
|
||||
Et repository, der stadig har markøren `wiki/.publish`, publiceres af det ældre scoped workflow, som fjernes, når alle repositories har et kald. Flyt siderne til `docs/wiki/` og tilføj kaldet, før det sker.
|
||||
|
||||
## Runners
|
||||
|
||||
| Punkt | Værdi |
|
||||
|
||||
@@ -85,10 +85,6 @@ The wiki has English and the product owner's language as a minimum.
|
||||
5. Merge the change to `main`. The log must end with `Published <n> page(s) to
|
||||
the wiki of <owner>/<repo>`.
|
||||
|
||||
A repository that still has the marker `wiki/.publish` is published by the
|
||||
older scoped workflow, which is removed once every repository has a call.
|
||||
Move the pages to `docs/wiki/` and add the call before that.
|
||||
|
||||
## Runners
|
||||
|
||||
| Item | Value |
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Onboarding.md, source sha256 4de4897fb3b7 -->
|
||||
<!-- translation of Onboarding.md, source sha256 1bc66efd5874 -->
|
||||
|
||||
> Ini ialah terjemahan [`Onboarding`](Onboarding). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
|
||||
|
||||
@@ -56,8 +56,6 @@ Aliran kerja boleh guna semula **Publish wiki pages** menyalin halaman Markdown
|
||||
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>`.
|
||||
|
||||
Repositori yang masih mempunyai penanda `wiki/.publish` diterbitkan oleh aliran kerja scoped yang lebih lama, yang dibuang apabila setiap repositori mempunyai panggilan. Alihkan halaman ke `docs/wiki/` dan tambah panggilan sebelum itu.
|
||||
|
||||
## Runners
|
||||
|
||||
| Perkara | Nilai |
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Troubleshooting.md, source sha256 c68827295812 -->
|
||||
<!-- translation of Troubleshooting.md, source sha256 cad6363616e8 -->
|
||||
|
||||
> Dette er en oversættelse af [`Troubleshooting`](Troubleshooting). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
|
||||
|
||||
@@ -31,7 +31,6 @@ Kategorien fortæller, hvor du skal kigge. En fejl uden for scriptet (jobbet sta
|
||||
| `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 |
|
||||
| `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)) |
|
||||
| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Kun wiki-publicering gennem det ældre scoped workflow: lad markøren være tom, eller skriv kun ordet `prune` i den |
|
||||
| `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 |
|
||||
@@ -53,9 +52,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.
|
||||
|
||||
`No wiki/.publish marker in <owner>/<repo>; wiki publishing is not enabled for this repository.` Kørslen af det ældre scoped Publish wiki lykkes og skriver intet. Repositoryet har ikke meldt sig til; kald det genbrugelige workflow **Publish wiki pages** (se [onboarding.md](Onboarding.da)), hvis det skal publicere.
|
||||
|
||||
`<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"` (med det ældre scoped workflow: ordet `prune` i `wiki/.publish`).
|
||||
`<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"`.
|
||||
|
||||
## Runner-problemer
|
||||
|
||||
|
||||
@@ -33,7 +33,6 @@ never starts, or stops before the step) is a **runner** problem.
|
||||
| `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 |
|
||||
| `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)) |
|
||||
| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Wiki publishing through the older scoped workflow only: leave the marker empty, or put only the word `prune` in it |
|
||||
| `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 |
|
||||
@@ -60,15 +59,9 @@ settings.
|
||||
synced.` The run succeeds but nothing was synced. Check that the Gitea
|
||||
version supports the push mirror API and re-run.
|
||||
|
||||
`No wiki/.publish marker in <owner>/<repo>; wiki publishing is not enabled for
|
||||
this repository.` The older scoped Publish wiki run succeeds and writes
|
||||
nothing. The repository has not opted in; call the reusable workflow
|
||||
**Publish wiki pages** (see [onboarding.md](Onboarding)) if it should publish.
|
||||
|
||||
`<n> page(s) are in the wiki but not in <folder>/ and were kept; set the prune
|
||||
input to true to delete them.` The run succeeds. Pages that exist only in the
|
||||
wiki are left alone unless the call sets `prune: "true"` (with the older scoped
|
||||
workflow: the word `prune` in `wiki/.publish`).
|
||||
wiki are left alone unless the call sets `prune: "true"`.
|
||||
|
||||
## Runner problems
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Troubleshooting.md, source sha256 c68827295812 -->
|
||||
<!-- translation of Troubleshooting.md, source sha256 cad6363616e8 -->
|
||||
|
||||
> Ini ialah terjemahan [`Troubleshooting`](Troubleshooting). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
|
||||
|
||||
@@ -31,7 +31,6 @@ Kategori menunjukkan di mana perlu dilihat. Kegagalan di luar skrip (kerja tidak
|
||||
| `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 |
|
||||
| `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)) |
|
||||
| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Penerbitan wiki melalui aliran kerja scoped yang lebih lama sahaja: biarkan penanda kosong, atau letakkan hanya perkataan `prune` di dalamnya |
|
||||
| `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 |
|
||||
@@ -53,9 +52,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.
|
||||
|
||||
`No wiki/.publish marker in <owner>/<repo>; wiki publishing is not enabled for this repository.` Larian Publish wiki scoped yang lebih lama berjaya dan tidak menulis apa-apa. Repositori belum memilih menyertainya; panggil aliran kerja boleh guna semula **Publish wiki pages** (lihat [onboarding.md](Onboarding.ms)) jika ia sepatutnya menerbitkan.
|
||||
|
||||
`<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"` (dengan aliran kerja scoped yang lebih lama: perkataan `prune` dalam `wiki/.publish`).
|
||||
`<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"`.
|
||||
|
||||
## Masalah runner
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Upgrading.md, source sha256 7fba937279b1 -->
|
||||
<!-- translation of Upgrading.md, source sha256 1e6a40ed1320 -->
|
||||
|
||||
> 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`) henter deres script ved deres input `tools-ref`, som som standard er `v1`. 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.
|
||||
|
||||
De to scoped workflows (**Sync GitHub mirror metadata** og **Publish wiki**) 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.
|
||||
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).
|
||||
|
||||
## Aflæsning af en changelog-post
|
||||
|
||||
|
||||
@@ -27,9 +27,13 @@ The quality-checks workflows (`quality-checks.yml`, `quality-checks-cpp.yml` and
|
||||
defaults to `v1`. 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.
|
||||
|
||||
The two scoped workflows (**Sync GitHub mirror metadata** and **Publish
|
||||
wiki**) are delivered by the instance and are not in your `uses:` lines; you
|
||||
cannot pin them, but they fetch their scripts at the major tag.
|
||||
The scoped workflow **Sync GitHub mirror metadata** is delivered by the
|
||||
instance and is not in your `uses:` lines; you cannot pin it, but it fetches its
|
||||
script at the major tag. Wiki publishing is a reusable workflow you call
|
||||
(`publish-wiki-pages.yml`); the scoped **Publish wiki** workflow and its
|
||||
`wiki/.publish` marker were removed in 2.0.0, so a repository that still has the
|
||||
marker no longer publishes until it calls the reusable workflow (see the
|
||||
onboarding guide).
|
||||
|
||||
## Reading a changelog entry
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Upgrading.md, source sha256 7fba937279b1 -->
|
||||
<!-- translation of Upgrading.md, source sha256 1e6a40ed1320 -->
|
||||
|
||||
> 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`) mengambil skripnya pada inputnya `tools-ref`, yang lalai ialah `v1`. Untuk menyematkan satu sepenuhnya, panggil pada tag tepat dan tetapkan `tools-ref` kepada tag yang sama; jika tidak, skrip mengikuti tag major.
|
||||
|
||||
Dua aliran kerja scoped (**Sync GitHub mirror metadata** dan **Publish wiki**) dihantar oleh instans dan tidak terdapat dalam baris `uses:` anda; anda tidak boleh menyematkannya, tetapi ia mengambil skripnya pada 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).
|
||||
|
||||
## Membaca satu catatan changelog
|
||||
|
||||
|
||||
@@ -79,10 +79,6 @@ The wiki has English and the product owner's language as a minimum.
|
||||
5. Merge the change to `main`. The log must end with `Published <n> page(s) to
|
||||
the wiki of <owner>/<repo>`.
|
||||
|
||||
A repository that still has the marker `wiki/.publish` is published by the
|
||||
older scoped workflow, which is removed once every repository has a call.
|
||||
Move the pages to `docs/wiki/` and add the call before that.
|
||||
|
||||
## Runners
|
||||
|
||||
| Item | Value |
|
||||
|
||||
@@ -27,7 +27,6 @@ never starts, or stops before the step) is a **runner** problem.
|
||||
| `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 |
|
||||
| `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)) |
|
||||
| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Wiki publishing through the older scoped workflow only: leave the marker empty, or put only the word `prune` in it |
|
||||
| `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 |
|
||||
@@ -54,15 +53,9 @@ settings.
|
||||
synced.` The run succeeds but nothing was synced. Check that the Gitea
|
||||
version supports the push mirror API and re-run.
|
||||
|
||||
`No wiki/.publish marker in <owner>/<repo>; wiki publishing is not enabled for
|
||||
this repository.` The older scoped Publish wiki run succeeds and writes
|
||||
nothing. The repository has not opted in; call the reusable workflow
|
||||
**Publish wiki pages** (see [onboarding.md](onboarding.md)) if it should publish.
|
||||
|
||||
`<n> page(s) are in the wiki but not in <folder>/ and were kept; set the prune
|
||||
input to true to delete them.` The run succeeds. Pages that exist only in the
|
||||
wiki are left alone unless the call sets `prune: "true"` (with the older scoped
|
||||
workflow: the word `prune` in `wiki/.publish`).
|
||||
wiki are left alone unless the call sets `prune: "true"`.
|
||||
|
||||
## Runner problems
|
||||
|
||||
|
||||
+7
-3
@@ -21,9 +21,13 @@ The quality-checks workflows (`quality-checks.yml`, `quality-checks-cpp.yml` and
|
||||
defaults to `v1`. 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.
|
||||
|
||||
The two scoped workflows (**Sync GitHub mirror metadata** and **Publish
|
||||
wiki**) are delivered by the instance and are not in your `uses:` lines; you
|
||||
cannot pin them, but they fetch their scripts at the major tag.
|
||||
The scoped workflow **Sync GitHub mirror metadata** is delivered by the
|
||||
instance and is not in your `uses:` lines; you cannot pin it, but it fetches its
|
||||
script at the major tag. Wiki publishing is a reusable workflow you call
|
||||
(`publish-wiki-pages.yml`); the scoped **Publish wiki** workflow and its
|
||||
`wiki/.publish` marker were removed in 2.0.0, so a repository that still has the
|
||||
marker no longer publishes until it calls the reusable workflow (see the
|
||||
onboarding guide).
|
||||
|
||||
## Reading a changelog entry
|
||||
|
||||
|
||||
+13
-110
@@ -7,7 +7,7 @@ import urllib.error
|
||||
import pytest
|
||||
import yaml
|
||||
|
||||
from workflow_source import PUBLISH_WORKFLOW, REPO_ROOT, load_publish_module
|
||||
from workflow_source import REPO_ROOT, load_publish_module
|
||||
|
||||
REUSABLE_WORKFLOW = REPO_ROOT / ".gitea" / "workflows" / "publish-wiki-pages.yml"
|
||||
|
||||
@@ -25,22 +25,6 @@ def b64(text: str) -> str:
|
||||
return base64.b64encode(text.encode()).decode()
|
||||
|
||||
|
||||
class TestParseMarker:
|
||||
@pytest.mark.parametrize(
|
||||
("text", "expected"),
|
||||
[("", False), (" \n", False), (None, False), ("prune", True), (" prune\n", True)],
|
||||
)
|
||||
def test_reads_the_empty_marker_and_the_prune_word(self, publish_wiki, text, expected):
|
||||
assert publish_wiki.parse_marker(text) is expected
|
||||
|
||||
@pytest.mark.parametrize("text", ["Prune", "prune: true", "delete", "prune\nmore"])
|
||||
def test_rejects_anything_else(self, publish_wiki, text):
|
||||
with pytest.raises(publish_wiki.WorkflowError) as caught:
|
||||
publish_wiki.parse_marker(text)
|
||||
assert caught.value.category == "configuration"
|
||||
assert "prune" in str(caught.value)
|
||||
|
||||
|
||||
class TestParseGiteaToken:
|
||||
def test_returns_the_stripped_token(self, publish_wiki):
|
||||
assert publish_wiki.parse_gitea_token(" abc \n") == "abc"
|
||||
@@ -54,17 +38,15 @@ class TestParseGiteaToken:
|
||||
|
||||
|
||||
class TestReadPages:
|
||||
def test_reads_markdown_files_by_stem_and_ignores_the_marker(self, publish_wiki, tmp_path):
|
||||
def test_reads_markdown_files_by_stem_and_ignores_other_files(self, publish_wiki, tmp_path):
|
||||
(tmp_path / "Home.md").write_bytes(b"home")
|
||||
(tmp_path / "Home.da.md").write_bytes(b"hjem")
|
||||
(tmp_path / ".publish").write_bytes(b"prune")
|
||||
(tmp_path / "Notes.txt").write_bytes(b"ignored")
|
||||
assert publish_wiki.read_pages(tmp_path) == {"Home": b"home", "Home.da": b"hjem"}
|
||||
|
||||
def test_rejects_a_directory_without_pages_so_the_wiki_is_never_wiped(
|
||||
self, publish_wiki, tmp_path
|
||||
):
|
||||
(tmp_path / ".publish").write_text("prune", encoding="utf-8")
|
||||
with pytest.raises(publish_wiki.WorkflowError, match="no Markdown pages"):
|
||||
publish_wiki.read_pages(tmp_path)
|
||||
|
||||
@@ -143,7 +125,7 @@ def environment(monkeypatch, tmp_path):
|
||||
wiki_dir.mkdir()
|
||||
(wiki_dir / "Home.md").write_text("home v2", encoding="utf-8")
|
||||
(wiki_dir / "Credentials.md").write_text("credentials", encoding="utf-8")
|
||||
(wiki_dir / ".publish").write_text("prune\n", encoding="utf-8")
|
||||
monkeypatch.setenv("WIKI_PRUNE", "true")
|
||||
monkeypatch.setenv("WIKI_DIR", str(wiki_dir))
|
||||
monkeypatch.setenv("GITEA_API_URL", f"{API}/")
|
||||
monkeypatch.setenv("SOURCE_REPOSITORY", "TirSystem/repo")
|
||||
@@ -156,58 +138,6 @@ def run_main(publish_wiki, gitea):
|
||||
return publish_wiki.main()
|
||||
|
||||
|
||||
class TestOptIn:
|
||||
def test_a_repository_without_the_marker_is_never_written_to(
|
||||
self, publish_wiki, environment, capsys
|
||||
):
|
||||
(environment / ".publish").unlink()
|
||||
gitea = FakeGitea(publish_wiki, wiki={"Old": b64("hand written")})
|
||||
|
||||
assert run_main(publish_wiki, gitea) == 0
|
||||
|
||||
assert gitea.calls == []
|
||||
assert "wiki publishing is not enabled" in capsys.readouterr().out
|
||||
assert gitea.wiki == {"Old": b64("hand written")}
|
||||
|
||||
def test_a_repository_without_the_marker_does_not_need_the_secret(
|
||||
self, publish_wiki, environment, monkeypatch
|
||||
):
|
||||
(environment / ".publish").unlink()
|
||||
monkeypatch.setenv("WIKI_CREDENTIALS", "")
|
||||
assert run_main(publish_wiki, FakeGitea(publish_wiki)) == 0
|
||||
|
||||
def test_a_repository_without_a_wiki_directory_is_skipped(
|
||||
self, publish_wiki, monkeypatch, tmp_path
|
||||
):
|
||||
monkeypatch.setenv("WIKI_DIR", str(tmp_path / "missing"))
|
||||
monkeypatch.setenv("SOURCE_REPOSITORY", "TirSystem/repo")
|
||||
gitea = FakeGitea(publish_wiki)
|
||||
assert run_main(publish_wiki, gitea) == 0
|
||||
assert gitea.calls == []
|
||||
|
||||
def test_an_opted_in_repository_without_the_secret_fails_before_any_request(
|
||||
self, publish_wiki, environment, monkeypatch
|
||||
):
|
||||
monkeypatch.setenv("WIKI_CREDENTIALS", "")
|
||||
gitea = FakeGitea(publish_wiki)
|
||||
|
||||
with pytest.raises(publish_wiki.WorkflowError, match="TOKEN_FOR_GITEA_WIKI"):
|
||||
run_main(publish_wiki, gitea)
|
||||
|
||||
assert gitea.calls == []
|
||||
|
||||
def test_an_unknown_marker_content_is_refused_before_any_request(
|
||||
self, publish_wiki, environment
|
||||
):
|
||||
(environment / ".publish").write_text("mirror everything", encoding="utf-8")
|
||||
gitea = FakeGitea(publish_wiki)
|
||||
|
||||
with pytest.raises(publish_wiki.WorkflowError, match="prune"):
|
||||
run_main(publish_wiki, gitea)
|
||||
|
||||
assert gitea.calls == []
|
||||
|
||||
|
||||
class TestPublish:
|
||||
def test_prune_creates_updates_and_deletes_to_match_the_source(
|
||||
self, publish_wiki, environment, capsys
|
||||
@@ -227,9 +157,9 @@ class TestPublish:
|
||||
assert "0 created, 1 updated, 1 deleted" in capsys.readouterr().out
|
||||
|
||||
def test_without_prune_pages_outside_the_source_are_kept(
|
||||
self, publish_wiki, environment, capsys
|
||||
self, publish_wiki, environment, capsys, monkeypatch
|
||||
):
|
||||
(environment / ".publish").write_text("", encoding="utf-8")
|
||||
monkeypatch.setenv("WIKI_PRUNE", "false")
|
||||
gitea = FakeGitea(
|
||||
publish_wiki, wiki={"Home": b64("home v1"), "Old": b64("hand written")}
|
||||
)
|
||||
@@ -302,11 +232,11 @@ class TestPageIdentity:
|
||||
"""A wiki that already has pages named with spaces, as Gitea stores them."""
|
||||
|
||||
def test_a_file_named_with_a_space_updates_the_existing_page(
|
||||
self, publish_wiki, environment
|
||||
self, publish_wiki, environment, monkeypatch
|
||||
):
|
||||
(environment / "Home.md").unlink()
|
||||
(environment / "Credentials.md").unlink()
|
||||
(environment / ".publish").write_text("", encoding="utf-8")
|
||||
monkeypatch.setenv("WIKI_PRUNE", "false")
|
||||
(environment / "Home da.md").write_text("hjem v2", encoding="utf-8")
|
||||
gitea = FakeGitea(publish_wiki, wiki={"Home-da": b64("hjem v1")})
|
||||
|
||||
@@ -457,7 +387,6 @@ class TestExplicitPrune:
|
||||
|
||||
@pytest.fixture()
|
||||
def explicit(self, environment, monkeypatch):
|
||||
(environment / ".publish").unlink()
|
||||
monkeypatch.setenv("WIKI_PRUNE", "false")
|
||||
return environment
|
||||
|
||||
@@ -567,38 +496,12 @@ class TestReusableWorkflow:
|
||||
assert fetch["ref"] == "${{ inputs.tools-ref }}"
|
||||
|
||||
|
||||
class TestWorkflow:
|
||||
@pytest.fixture()
|
||||
def document(self):
|
||||
return yaml.safe_load(PUBLISH_WORKFLOW.read_text(encoding="utf-8"))
|
||||
|
||||
def test_runs_only_on_main_when_wiki_changes_or_by_hand(self, document):
|
||||
triggers = document[True] # PyYAML reads the key `on` as True
|
||||
assert triggers["push"]["branches"] == ["main"]
|
||||
assert triggers["push"]["paths"] == ["wiki/**"]
|
||||
assert "workflow_dispatch" in triggers
|
||||
|
||||
def test_job_has_read_only_permissions(self, document):
|
||||
assert document["jobs"]["publish-wiki"]["permissions"] == {"contents": "read"}
|
||||
|
||||
def test_secret_is_passed_only_through_the_environment_and_has_no_fallback(self, document):
|
||||
text = PUBLISH_WORKFLOW.read_text(encoding="utf-8")
|
||||
assert "secrets.TOKEN_FOR_GITEA }}" not in text
|
||||
publish_step = document["jobs"]["publish-wiki"]["steps"][-1]
|
||||
assert publish_step["env"]["WIKI_CREDENTIALS"] == "${{ secrets.TOKEN_FOR_GITEA_WIKI }}"
|
||||
assert "secrets" not in publish_step["run"]
|
||||
|
||||
def test_the_scoped_workflow_runs_the_script_file(self, document):
|
||||
assert (REPO_ROOT / "tools" / "publish_wiki.py").is_file()
|
||||
steps = document["jobs"]["publish-wiki"]["steps"]
|
||||
assert "python3 - <<" not in PUBLISH_WORKFLOW.read_text(encoding="utf-8")
|
||||
assert steps[0]["uses"].startswith("actions/checkout@")
|
||||
assert steps[1]["with"] == {
|
||||
"repository": "TirSystem/github-action",
|
||||
"ref": "v1",
|
||||
"path": "shared-scripts",
|
||||
}
|
||||
assert steps[-1]["run"] == "python3 shared-scripts/tools/publish_wiki.py"
|
||||
def test_the_scoped_workflow_is_gone_and_the_script_has_no_marker_path():
|
||||
"""ADR-0009, MIL-009: the scoped publish-wiki.yml and the marker are removed."""
|
||||
assert not (REPO_ROOT / ".gitea" / "scoped_workflows" / "publish-wiki.yml").exists()
|
||||
source = (REPO_ROOT / "tools" / "publish_wiki.py").read_text(encoding="utf-8")
|
||||
assert "MARKER_NAME" not in source
|
||||
assert "parse_marker" not in source
|
||||
|
||||
|
||||
def test_this_repository_publishes_docs_wiki_through_the_reusable_workflow():
|
||||
|
||||
@@ -13,7 +13,6 @@ WORKFLOW_DIRS = (
|
||||
)
|
||||
SYNC_WORKFLOW = WORKFLOW_DIRS[0] / "sync-github-metadata.yml"
|
||||
SYNC_SCRIPT = REPO_ROOT / "tools" / "sync_github_metadata.py"
|
||||
PUBLISH_WORKFLOW = WORKFLOW_DIRS[0] / "publish-wiki.yml"
|
||||
PUBLISH_SCRIPT = REPO_ROOT / "tools" / "publish_wiki.py"
|
||||
|
||||
_HEREDOC = re.compile(
|
||||
|
||||
+16
-50
@@ -1,19 +1,15 @@
|
||||
"""Publish the pages of a folder to the Gitea wiki of the repository.
|
||||
|
||||
Run by the reusable workflow publish-wiki.yml, which a repository calls
|
||||
(MIL-008), and by the scoped workflow of the same name until it is removed.
|
||||
The reusable workflow sets WIKI_PRUNE: the caller is the opt-in, and the
|
||||
folder must exist. The scoped workflow leaves WIKI_PRUNE unset: a repository
|
||||
publishes only when it has opted in with WIKI_DIR/.publish (ADR-0004), and the
|
||||
word prune in that file lets the run delete wiki pages that are not in the
|
||||
folder. It reads its settings from the environment:
|
||||
Run by the reusable workflow publish-wiki-pages.yml, which a repository calls
|
||||
(ADR-0009). The caller is the opt-in: the workflow sets WIKI_PRUNE and the
|
||||
folder must exist. It reads its settings from the environment:
|
||||
|
||||
GITEA_API_URL Gitea API base, for example https://host/api/v1
|
||||
SOURCE_REPOSITORY owner/repo of the repository whose wiki is written
|
||||
WIKI_CREDENTIALS the Gitea token, as clear text (TOKEN_FOR_GITEA_WIKI)
|
||||
WIKI_DIR directory with the pages (default: wiki)
|
||||
WIKI_PRUNE true or false: delete pages that are not in the
|
||||
folder; when set, no .publish marker is read
|
||||
WIKI_DIR directory with the pages (default: docs/wiki)
|
||||
WIKI_PRUNE true or false, required: delete pages that are not in
|
||||
the folder
|
||||
|
||||
Every failure is printed as ``ERROR: [category] message`` with the categories
|
||||
configuration, credentials, permissions and api; no secret value is printed.
|
||||
@@ -32,8 +28,7 @@ from pathlib import Path
|
||||
PAGE_LIMIT = 50
|
||||
REQUEST_TIMEOUT_SECONDS = 30
|
||||
COMMIT_MESSAGE = "Publish wiki from the repository"
|
||||
MARKER_NAME = ".publish"
|
||||
PRUNE_WORD = "prune"
|
||||
DEFAULT_WIKI_DIR = "docs/wiki"
|
||||
|
||||
|
||||
class WorkflowError(RuntimeError):
|
||||
@@ -81,19 +76,6 @@ def request_json(url, method="GET", headers=None, body=None):
|
||||
raise WorkflowError("api", f"Gitea API is unreachable ({error}).") from None
|
||||
|
||||
|
||||
def parse_marker(text):
|
||||
"""Return True when the marker asks for pruning, False when it is empty."""
|
||||
word = (text or "").strip()
|
||||
if not word:
|
||||
return False
|
||||
if word == PRUNE_WORD:
|
||||
return True
|
||||
raise WorkflowError(
|
||||
"configuration",
|
||||
f"wiki/{MARKER_NAME} may only be empty or contain the word '{PRUNE_WORD}'.",
|
||||
)
|
||||
|
||||
|
||||
def parse_prune_setting(text):
|
||||
"""Return the boolean of the WIKI_PRUNE input: true or false, nothing else."""
|
||||
word = (text or "").strip().lower()
|
||||
@@ -254,27 +236,16 @@ def publish(pages, wiki_url, headers, send, prune):
|
||||
|
||||
|
||||
def main():
|
||||
wiki_dir = Path(os.environ.get("WIKI_DIR", "wiki"))
|
||||
wiki_dir = Path(os.environ.get("WIKI_DIR", DEFAULT_WIKI_DIR))
|
||||
owner, repo = split_repository(os.environ.get("SOURCE_REPOSITORY"))
|
||||
|
||||
prune_setting = os.environ.get("WIKI_PRUNE")
|
||||
if prune_setting is None:
|
||||
marker = wiki_dir / MARKER_NAME
|
||||
if not marker.is_file():
|
||||
print(
|
||||
f"No {wiki_dir}/{MARKER_NAME} marker in {owner}/{repo}; "
|
||||
"wiki publishing is not enabled for this repository."
|
||||
)
|
||||
return 0
|
||||
prune = parse_marker(marker.read_text(encoding="utf-8"))
|
||||
else:
|
||||
prune = parse_prune_setting(prune_setting)
|
||||
if not wiki_dir.is_dir():
|
||||
raise WorkflowError(
|
||||
"configuration",
|
||||
f"The wiki folder {wiki_dir} does not exist in {owner}/{repo}; "
|
||||
"set the wiki_dir input to the folder with the pages.",
|
||||
)
|
||||
prune = parse_prune_setting(os.environ.get("WIKI_PRUNE"))
|
||||
if not wiki_dir.is_dir():
|
||||
raise WorkflowError(
|
||||
"configuration",
|
||||
f"The wiki folder {wiki_dir} does not exist in {owner}/{repo}; "
|
||||
"set the wiki_dir input to the folder with the pages.",
|
||||
)
|
||||
|
||||
pages = read_pages(wiki_dir)
|
||||
token = parse_gitea_token(os.environ.get("WIKI_CREDENTIALS"))
|
||||
@@ -316,12 +287,7 @@ def main():
|
||||
if result["kept"]:
|
||||
print(
|
||||
f"{len(result['kept'])} page(s) are in the wiki but not in "
|
||||
f"{wiki_dir}/ and were kept; "
|
||||
+ (
|
||||
f"put the word '{PRUNE_WORD}' in {wiki_dir}/{MARKER_NAME} to delete them."
|
||||
if prune_setting is None
|
||||
else "set the prune input to true to delete them."
|
||||
)
|
||||
f"{wiki_dir}/ and were kept; set the prune input to true to delete them."
|
||||
)
|
||||
return 0
|
||||
|
||||
|
||||
Reference in New Issue
Block a user