Publish the wiki through a reusable workflow; this wiki moves to docs/wiki
- publish-wiki-pages.yml: reusable workflow with wiki_dir, prune and tools-ref inputs and the declared secret TOKEN_FOR_GITEA_WIKI - tools/publish_wiki.py: WIKI_PRUNE selects explicit mode without the marker; a missing folder is a configuration error - publish-own-wiki.yml: this repository calls the reusable workflow - wiki/ moves to docs/wiki/; build_wiki.py and its tests follow - the scoped publish-wiki.yml is marked deprecated, not removed - guides, README and the Danish and Bahasa Malaysia wiki pages describe the caller, docs/wiki/ and the new error messages Task: MIL-008#2 Task: MIL-008#4 Task: MIL-008#5 Task: MIL-008#6
This commit is contained in:
@@ -0,0 +1,535 @@
|
||||
<!-- translation of Home.md, source sha256 b6796554f4eb -->
|
||||
|
||||
> Ini ialah terjemahan [`Home`](Home). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
|
||||
|
||||
[English](Home) | [Dansk](Home.da) | Bahasa Melayu
|
||||
|
||||
# TirSystem GitHub Actions
|
||||
|
||||
Koleksi aliran kerja (workflow) Gitea Actions yang boleh digunakan semula untuk profesional DevOps dan jurutera perisian yang mengusahakan projek TirSystem.
|
||||
|
||||
|
||||
## Gambaran keseluruhan
|
||||
|
||||
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).
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
| 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 |
|
||||
| Quality checks C# | [`quality-checks-csharp.yml`](https://git.tirsystem.com/TirSystem/github-action/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 |
|
||||
| Publish own wiki | [`publish-own-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/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/github-action/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/github-action/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/github-action/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 |
|
||||
|
||||
### Menyegerakkan metadata GitHub
|
||||
|
||||
Menyegerakkan penerangan dan topik repositori Gitea ke push mirror GitHub.
|
||||
|
||||
#### Jadual (cron)
|
||||
|
||||
Setiap hari pada 03:17 UTC (`17 3 * * *`), serta pada setiap push ke `main` dan `workflow_dispatch` manual.
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Sync Gitea repository description and topics to GitHub
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Push to main,\nmanual trigger, or schedule" as Trigger
|
||||
participant "Gitea Actions\nsync-github-metadata" as Workflow
|
||||
participant "Gitea REST API" as Gitea
|
||||
participant "GitHub REST API" as GitHub
|
||||
|
||||
Trigger -> Workflow: Start workflow
|
||||
activate Workflow
|
||||
|
||||
Workflow -> Workflow: Read and validate secrets
|
||||
note right
|
||||
TOKEN_FOR_GITEA
|
||||
PAT_FOR_GITHUB
|
||||
end note
|
||||
|
||||
alt secret validation failed
|
||||
Workflow --> Trigger: workflow failed
|
||||
end
|
||||
|
||||
|
||||
Workflow -> Gitea: GET /repos/{owner}/{repo}
|
||||
Gitea --> Workflow: Description and topics
|
||||
|
||||
Workflow -> Gitea: GET /repos/{owner}/{repo}/push_mirrors
|
||||
Gitea --> Workflow: Push mirror response
|
||||
|
||||
alt mirrors is not a list
|
||||
Workflow --> Trigger: Log a warning and succeed\n(GitHub metadata not synced)
|
||||
else mirrors is a list with no GitHub mirror
|
||||
Workflow --> Trigger: Log that there is nothing to sync and succeed
|
||||
else mirrors is a list
|
||||
Workflow -> Workflow: Find GitHub owner and repo from remote_address
|
||||
|
||||
Workflow -> GitHub: PATCH /repos/{owner}/{repo}\n{description}
|
||||
GitHub --> Workflow: Repository updated
|
||||
|
||||
Workflow -> GitHub: PUT /repos/{owner}/{repo}/topics\n{names}
|
||||
GitHub --> Workflow: Topics updated
|
||||
|
||||
Workflow --> Trigger: Sync completed
|
||||
else Gitea API denies access
|
||||
Gitea --> Workflow: HTTP 403 Forbidden
|
||||
Workflow --> Trigger: Workflow fails
|
||||
else GitHub API denies access
|
||||
GitHub --> Workflow: HTTP error
|
||||
Workflow --> Trigger: Workflow fails
|
||||
end
|
||||
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)).
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Shared quality checks (reusable workflow)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Calling repository\nuses: ...quality-checks.yml@v1" as Caller
|
||||
participant "Gitea Actions\nquality-checks" as Workflow
|
||||
participant "PyPI" as PyPI
|
||||
|
||||
Caller -> Workflow: workflow_call with languages,\nworking-directory and tool versions
|
||||
activate Workflow
|
||||
|
||||
Workflow -> Workflow: Validate the inputs
|
||||
alt languages or working-directory is invalid
|
||||
Workflow --> Caller: Fail with [configuration]
|
||||
end
|
||||
|
||||
Workflow -> Workflow: Check out the calling repository
|
||||
Workflow -> PyPI: Install the pinned tools in a virtual environment\n(ruff, mypy, shellcheck-py, shfmt-py as selected)
|
||||
PyPI --> Workflow: Tools installed
|
||||
|
||||
loop for each selected language
|
||||
Workflow -> Workflow: List tracked files
|
||||
alt no files of that language
|
||||
Workflow -> Workflow: Notice: nothing was checked
|
||||
else
|
||||
Workflow -> Workflow: Run every tool and record PASS or FAIL
|
||||
end
|
||||
end
|
||||
|
||||
alt any tool failed
|
||||
Workflow --> Caller: Fail and list the failed tools
|
||||
else
|
||||
Workflow --> Caller: All selected checks passed
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Semakan kualiti C++
|
||||
|
||||
Aliran kerja boleh guna semula untuk C dan C++, dipanggil dengan `uses: TirSystem/github-action/.gitea/workflows/quality-checks-cpp.yml@v1` (ADR-0008). Repositori mesti mempunyai `.clang-format`; `.clang-tidy` dan pangkalan data kompilasi adalah pilihan.
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Shared quality checks for C and C++ (reusable workflow)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Calling repository\nuses: ...quality-checks-cpp.yml@v1" as Caller
|
||||
participant "Gitea Actions\nquality-checks-cpp" as Workflow
|
||||
participant "PyPI" as PyPI
|
||||
|
||||
Caller -> Workflow: workflow_call with working-directory, std,\ncompile-commands-dir and tool versions
|
||||
activate Workflow
|
||||
|
||||
Workflow -> Workflow: Check out the caller and the shared script
|
||||
Workflow -> Workflow: Validate the inputs
|
||||
alt an input is invalid or a version is not exact
|
||||
Workflow --> Caller: Fail with [configuration]
|
||||
end
|
||||
|
||||
Workflow -> PyPI: Install clang-format and clang-tidy at the exact versions
|
||||
PyPI --> Workflow: Tools installed
|
||||
|
||||
alt no C or C++ file is tracked
|
||||
Workflow --> Caller: Notice: nothing was checked, pass
|
||||
else no .clang-format, or compile-commands-dir\nwithout compile_commands.json
|
||||
Workflow --> Caller: Fail with [configuration]
|
||||
else
|
||||
Workflow -> Workflow: clang-format --dry-run -Werror on all files
|
||||
Workflow -> Workflow: clang-tidy on the C++ files (-std=std)\nand on the C files (or with the compile database)
|
||||
alt any tool failed
|
||||
Workflow --> Caller: Fail with tool, file and line in the log
|
||||
else
|
||||
Workflow --> Caller: All selected checks passed
|
||||
end
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Semakan kualiti C#
|
||||
|
||||
Aliran kerja boleh guna semula untuk C#, dipanggil dengan `uses: TirSystem/github-action/.gitea/workflows/quality-checks-csharp.yml@v1` (ADR-0008). Ia memasang .NET SDK tepat yang diberikan oleh `dotnet-sdk-version` (10 atau lebih baharu) dan memerlukan rangkaian untuk pemulihan pakej.
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Shared quality checks for C# (reusable workflow)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Calling repository\nuses: ...quality-checks-csharp.yml@v1" as Caller
|
||||
participant "Gitea Actions\nquality-checks-csharp" as Workflow
|
||||
participant "dot.net\n(dotnet-install.sh)" as DotNet
|
||||
|
||||
Caller -> Workflow: workflow_call with working-directory,\nproject and dotnet-sdk-version
|
||||
activate Workflow
|
||||
|
||||
Workflow -> Workflow: Check out the caller and the shared script
|
||||
Workflow -> Workflow: Validate the inputs
|
||||
alt an input is invalid or the SDK is not an exact\nstable version 10 or later
|
||||
Workflow --> Caller: Fail with [configuration]
|
||||
end
|
||||
|
||||
Workflow -> DotNet: Install the exact .NET SDK version
|
||||
DotNet --> Workflow: SDK installed
|
||||
|
||||
alt no C# file is tracked
|
||||
Workflow --> Caller: Notice: nothing was checked, pass
|
||||
else no solution or project, or several without the project input
|
||||
Workflow --> Caller: Fail with [configuration] that names them
|
||||
else
|
||||
Workflow -> Workflow: dotnet format --verify-no-changes
|
||||
Workflow -> Workflow: dotnet build -warnaserror\n(package restore needs the network)
|
||||
alt any tool failed
|
||||
Workflow --> Caller: Fail with tool, file and line in the log
|
||||
else
|
||||
Workflow --> Caller: All selected checks passed
|
||||
end
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Keluaran
|
||||
|
||||
Dimulakan secara manual oleh penyelenggara; dengan `dry_run` `true` (lalai) ia hanya menyemak (lihat [proses keluaran](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/release-process.md)).
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Release this repository
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Maintainer\n(workflow_dispatch: version, dry_run)" as Trigger
|
||||
participant "Gitea Actions\nrelease" as Workflow
|
||||
participant "Gitea REST API" as Gitea
|
||||
|
||||
Trigger -> Workflow: Start with version and dry_run
|
||||
activate Workflow
|
||||
|
||||
Workflow -> Workflow: Check the version and read CHANGELOG.md
|
||||
alt version malformed or no changelog entry
|
||||
Workflow --> Trigger: Fail with [validation] or [configuration]
|
||||
end
|
||||
|
||||
Workflow -> Gitea: GET branch main and status of the commit
|
||||
Gitea --> Workflow: Tip of main and the validation run
|
||||
alt commit is not the tip of main,\nor the validation run is not green
|
||||
Workflow --> Trigger: Fail with [validation]\n(no tag is created)
|
||||
end
|
||||
|
||||
Workflow -> Gitea: GET tags
|
||||
Gitea --> Workflow: Existing tags
|
||||
alt tag vMAJOR.MINOR.PATCH exists
|
||||
Workflow --> Trigger: Fail with [validation]\n(tags are never moved)
|
||||
end
|
||||
|
||||
alt dry_run is true (default)
|
||||
Workflow --> Trigger: Log what would be created and stop
|
||||
else
|
||||
Workflow -> Gitea: POST release (creates the version tag,\nbody is the changelog entry)
|
||||
opt this is the highest version of its major
|
||||
Workflow -> Gitea: Delete and recreate the major tag vMAJOR
|
||||
end
|
||||
Workflow --> Trigger: Released
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### 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`.
|
||||
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
branches: [ main ]
|
||||
paths: [ "docs/wiki/**" ]
|
||||
jobs:
|
||||
wiki:
|
||||
uses: TirSystem/github-action/.gitea/workflows/publish-wiki-pages.yml@v1
|
||||
secrets:
|
||||
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
|
||||
```
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish docs/wiki to the wiki of the calling repository
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Calling repository\nuses: ...publish-wiki-pages.yml@v1" as Caller
|
||||
participant "Gitea Actions\npublish-wiki-pages" as Workflow
|
||||
participant "shared-scripts\n(tools/publish_wiki.py at tools-ref)" as Script
|
||||
participant "Gitea wiki API" as Wiki
|
||||
|
||||
Caller -> Workflow: Call with wiki_dir, prune and the secret
|
||||
activate Workflow
|
||||
Workflow -> Script: Check out the repository and the script, run it
|
||||
activate Script
|
||||
|
||||
alt wiki_dir does not exist, or has no Markdown pages
|
||||
Script --> Workflow: Fail with [configuration]\n(an empty folder never deletes pages)
|
||||
else
|
||||
Script -> Script: Read prune and 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 prune is true
|
||||
Script -> Wiki: Delete pages that are not in wiki_dir
|
||||
end
|
||||
Script --> Workflow: Log created, updated and deleted counts
|
||||
end
|
||||
deactivate Script
|
||||
Workflow --> Caller: Workflow result
|
||||
deactivate Workflow
|
||||
@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
|
||||
|
||||
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).
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish accepted milestones (this repository)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Push to main that changes\ndocs/milestones/** or docs/sqa/reviews/**,\nor manual trigger" as Trigger
|
||||
participant "Gitea Actions\nsync-milestones" as Workflow
|
||||
participant "framework/scripts/\nsync-project.sh" as Script
|
||||
participant "Gitea REST API" as Gitea
|
||||
|
||||
Trigger -> Workflow: Start workflow
|
||||
activate Workflow
|
||||
Workflow -> Workflow: Check out the project and the framework\nsubmodules over HTTPS with TOKEN_FOR_GITEA
|
||||
Workflow -> Script: --accepted-only (dry run)\nor --accepted-only --apply
|
||||
activate Script
|
||||
|
||||
loop for each docs/milestones/mil-*.md
|
||||
alt latest Version History row is not Accepted,\nor the latest review record is not a Go
|
||||
Script -> Script: Skip with the reason on stderr
|
||||
else
|
||||
alt dry run
|
||||
Script -> Script: Print the plan, no network call
|
||||
else
|
||||
Script -> Gitea: Create or update the Milestone\nand one Issue per task row
|
||||
Gitea --> Script: Milestone and issue numbers
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
note right of Script
|
||||
Nothing is closed or deleted.
|
||||
Each real run edits the issues
|
||||
of every accepted milestone.
|
||||
end note
|
||||
Script --> Workflow: Done, or "nothing to publish"
|
||||
deactivate Script
|
||||
Workflow --> Trigger: Workflow result
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Mengesahkan aliran kerja
|
||||
|
||||
Pengesahan repositori sendiri: ujian luar talian yang menjadi syarat bagi setiap pull request.
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Validate workflows (this repository's own checks)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Pull request,\npush to main, or manual trigger" as Trigger
|
||||
participant "Gitea Actions\nvalidate-workflows" as Workflow
|
||||
|
||||
Trigger -> Workflow: Start workflow
|
||||
activate Workflow
|
||||
Workflow -> Workflow: Check out the repository
|
||||
Workflow -> Workflow: Create a virtual environment and\ninstall tests/requirements.txt
|
||||
Workflow -> Workflow: Run pytest on tests/ under coverage (offline, no secrets):\nworkflows parse as YAML, no embedded Python,\nscripts compile, wiki pages and translations are current,\nsync, publish and release flows against a fake API
|
||||
|
||||
alt a test fails
|
||||
Workflow --> Trigger: Workflow fails (the pull request is not ready)
|
||||
else
|
||||
Workflow --> Trigger: Workflow succeeds
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
|
||||
## Keperluan
|
||||
|
||||
- Satu instans Gitea dengan Actions diaktifkan dan satu runner yang menyediakan `ubuntu-latest` dengan `python3`
|
||||
- Satu push mirror GitHub yang dikonfigurasi pada repositori Gitea (paling banyak satu; repositori tanpa cermin dilangkau dengan jayanya)
|
||||
- Rahsia (secret) repositori:
|
||||
- `TOKEN_FOR_GITEA`: token API Gitea (token sahaja, tanpa JSON)
|
||||
- `PAT_FOR_GITHUB`: personal access token GitHub yang dibenarkan mengubah suai repositori cermin (token sahaja, tanpa JSON)
|
||||
- `TOKEN_FOR_GITEA_WIKI` (hanya untuk repositori yang menerbitkan wiki, lihat [panduan menyertakan repositori](Onboarding.ms)): token Gitea yang boleh menulis ke wiki, disimpan sebagai secret organisasi repositori; tiada sandaran kepada `TOKEN_FOR_GITEA`
|
||||
|
||||
|
||||
## Persediaan
|
||||
|
||||
Tiada kebergantungan perlu dipasang; aliran kerja hanya menggunakan pustaka standard Python.
|
||||
|
||||
1. Klon repositori:
|
||||
```bash
|
||||
git clone ssh://git@git.tirsystem.com:10022/TirSystem/github-action.git
|
||||
```
|
||||
2. Tambah rahsia yang disenaraikan di bawah [Keperluan](#keperluan) ke tetapan repositori dalam Gitea.
|
||||
3. Konfigurasikan push mirror GitHub dalam tetapan repositori.
|
||||
|
||||
|
||||
## Jalankan
|
||||
|
||||
Aliran kerja berjalan secara automatik pada push ke `main` dan mengikut jadual harian. Untuk menjalankannya secara manual, cetuskan **Sync GitHub mirror metadata** melalui `workflow_dispatch` dari tab Actions dalam Gitea.
|
||||
|
||||
|
||||
## Ujian
|
||||
|
||||
Fail aliran kerja dan skrip dalam `tools/` disahkan oleh ujian luar talian yang tidak memerlukan akses rangkaian dan tidak memerlukan rahsia:
|
||||
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
|
||||
python -m pip install -r tests/requirements.txt
|
||||
python -m coverage run -m pytest -q tests
|
||||
python -m coverage report
|
||||
```
|
||||
|
||||
Semakan yang sama dijalankan pada setiap pull request dan setiap push ke `main` melalui [`validate-workflows.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/validate-workflows.yml). Semakan itu menghurai setiap aliran kerja sebagai YAML, memastikan tiada yang menanam Python, mengkompil skrip dalam `tools/`, memerlukan kebenaran kerja yang jelas, dan menguji penghuraian kelayakan (credentials), penghuraian alamat push mirror serta aliran penyegerakan dan penerbitan terhadap API palsu. Larian gagal apabila liputan baris dan cabang `tools/` di bawah 95% (`.coveragerc`).
|
||||
|
||||
Selepas perubahan pada aliran kerja penyegerakan, cetuskan juga **Sync GitHub mirror metadata** secara manual dalam Gitea dan bandingkan penerangan dan topik pada cermin GitHub.
|
||||
Reference in New Issue
Block a user