TirSystem/github-action
0
1
Fork 0
Code Issues 5 Pull Requests 1 Actions Packages Projects Releases 3 Wiki Activity

Add the upgrade guide and the use case Consume a Workflow Update

Browse Source 
UC-007, US-001.14 and US-001.15, the upgrade guide on the wiki in three
languages, and RC-044 to RC-046 with the traceability matrix.

Task: MIL-004#3
This commit is contained in:
Tirsvad
2026-10-10 22:55:40 +08:00
parent 297095bdfb
commit 4cf52afe00
18 changed files with 507 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
wiki/Capabilities.da.md
+2 -2
View File
@@ -1,4 +1,4 @@
<!-- translation of Capabilities.md, source sha256 c55376110b0c -->
<!-- translation of Capabilities.md, source sha256 c1d5b1f173ef -->
> Dette er en oversættelse af [`Capabilities`](Capabilities). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
@@ -15,7 +15,7 @@ Rækker, der siger Implementeret eller Vejledninger er skrevet, findes i dag. Re
| Tilslutning af et repository, administration af runners, fejlfinding | Vejledninger er skrevet ([tilslutning](Onboarding.da), [fejlfinding](Troubleshooting.da)); scoped levering til andre repositories er ikke verificeret endnu; korte use cases er åbne (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; pilotforsøget i et andet repository afventer (MIL-006) |
| 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; tilslutningen i RepoFoundry er til gennemgang ([vejledning](QualityChecks.da)) |
| Versioneret udgivelse og publicering | Planlagt (MIL-004) |
| Versioneret udgivelse og publicering | Udgivelsesproces, changelog og opgraderingsvejledning er defineret; den første udgivelse `v1.0.0` og udgivelsesworkflowet mangler (MIL-004) ([vejledning](Upgrading.da)) |
### Synkronisering af GitHub-metadata
wiki/Capabilities.md
+1 -1
View File
@@ -15,7 +15,7 @@ Rows that say Implemented or Guides written exist today. The rest is planned and
| Onboard a repository, manage runners, diagnose failures | Guides written ([onboarding](Onboarding), [troubleshooting](Troubleshooting)); scoped delivery to other repositories not yet verified; brief use cases open (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; the pilot in a second repository is pending (MIL-006) |
| 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; adoption in RepoFoundry is in review ([guide](QualityChecks)) |
| Versioned release and publishing | Planned (MIL-004) |
| Versioned release and publishing | Release process, changelog and upgrade guide defined; the first release `v1.0.0` and the release workflow are pending (MIL-004) ([guide](Upgrading)) |
### Sync GitHub metadata
wiki/Capabilities.ms.md
+2 -2
View File
@@ -1,4 +1,4 @@
<!-- translation of Capabilities.md, source sha256 c55376110b0c -->
<!-- translation of Capabilities.md, source sha256 c1d5b1f173ef -->
> Ini ialah terjemahan [`Capabilities`](Capabilities). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
@@ -15,7 +15,7 @@ Baris yang menyatakan Dilaksanakan atau Panduan telah ditulis wujud hari ini. Se
| Menyertakan repositori, mengurus runner, mendiagnosis kegagalan | Panduan telah ditulis ([menyertakan repositori](Onboarding.ms), [diagnosis](Troubleshooting.ms)); penghantaran scoped ke repositori lain belum disahkan; use case ringkas masih terbuka (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; juruterbang dalam repositori kedua belum dibuat (MIL-006) |
| 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; penerimaan dalam RepoFoundry sedang disemak ([panduan](QualityChecks.ms)) |
| Keluaran dan penerbitan berversi | Dirancang (MIL-004) |
| Keluaran berversi dan penerbitan | Proses keluaran, changelog dan panduan naik taraf telah ditakrifkan; keluaran pertama `v1.0.0` dan aliran kerja keluaran belum ada (MIL-004) ([panduan](Upgrading.ms)) |
### Menyegerakkan metadata GitHub
wiki/Upgrading.da.md
+59
View File
@@ -0,0 +1,59 @@
<!-- translation of Upgrading.md, source sha256 ff8a06c4a03f -->
> Dette er en oversættelse af [`Upgrading`](Upgrading). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
[English](Upgrading) | Dansk | [Bahasa Melayu](Upgrading.ms)
# Opgradering til en ny version af de fælles workflows
Sådan tager en softwareudvikler en ny udgivelse af de fælles workflows i brug uden risiko: læs changelog, prøv opdateringen ét sted, og gå tilbage, hvis den fejler. Versionsreglerne er udgivelsesprocessens: én version for hele repositoryet, tags `vMAJOR.MINOR.PATCH` og et flytbart major-tag `vMAJOR`.
## Hvilken version du følger
| I din `uses:`-linje | Du modtager | Brug den, når |
| --- | --- | --- |
| `@v1.2.0` | aldrig noget nyt | en pipeline ikke må ændre sig |
| `@v1` | kun kompatible udgivelser (minor og patch) | standardvalget for et projekt |
| `@main` | alt, også uudgivet | aldrig; kun til dette repositorys egne tests |
En udgivelse, der bryder kompatibiliteten, får en ny major-version (`v2`), så en pipeline på `@v1` aldrig modtager den, før du selv ændrer linjen.
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.
## Aflæsning af en changelog-post
Åbn `CHANGELOG.md` i `TirSystem/github-action` eller tagget udgivelsesside. En post har op til fire grupper:
| Gruppe | Hvad den betyder for dig |
| --- | --- |
| Breaking | Du skal handle: et navn, et input, en secret eller en standardværdi er ændret. En udgivelse med denne gruppe har en ny major-version |
| Added | Intet at gøre; et nyt valgfrit input, workflow eller en ny funktion |
| Changed | Intet at gøre; ingen synlig virkning for eksisterende kaldere |
| Fixed | Intet at gøre; en rettelse, du modtager på `@v1` |
En post, der ændrer credentials, tokens eller tilladelser, siger det; kontroller dine secrets, før du opgraderer.
## Afprøvning af en opdatering
1. Ændr versionen i **ét** repository på en gren:
```yaml
jobs:
quality:
uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v2
```
2. Åbn en pull request, og læs kørslen. En mislykket kontrol viser værktøj, fil og meddelelse (se vejledningen til aflæsning af kvalitetskontrollens resultater).
3. For en udgivelse, der bryder kompatibiliteten, følges opgraderingsnoterne i changelog-posten, og trinnet gentages.
4. Når pull requesten er grøn, foretages den samme ændring i de øvrige repositories.
## Tilbage igen
1. Ret linjen tilbage til det forrige præcise tag, fx `@v1.2.0`, og flet. Præcise tags slettes eller flyttes aldrig, så det virker altid.
2. Fortæl vedligeholderne, hvilken udgivelse der fejlede, og hvad du så, så major-tagget kan flyttes tilbage og en rettelse udgives.
## Når noget er uklart
| Symptom | Sandsynlig årsag | Rettelse |
| --- | --- | --- |
| Kørslen siger, at workflowet ikke kan findes | Tagget findes ikke, eller stien er forkert | Kontroller tagget på udgivelsessiden og stien `.gitea/workflows/quality-checks.yml` |
| En grøn pipeline blev rød efter en udgivelse på `@v1` | En kompatibel udgivelse burde ikke gøre det | Fastlås det forrige præcise tag, og meld det som en defekt |
| Et input accepteres ikke længere | En udgivelse, der bryder kompatibiliteten, har omdøbt det | Læs gruppen Breaking i posten |
wiki/Upgrading.md
+72
View File
@@ -0,0 +1,72 @@
<!-- Generated from guides/upgrading.md by tools/build_wiki.py. Edit the source, not this page. -->
> This page is generated from [`guides/upgrading.md`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/upgrading.md). Changes made here are overwritten the next time the wiki is published.
English | [Dansk](Upgrading.da) | [Bahasa Melayu](Upgrading.ms)
# Upgrading to a new version of the shared workflows
How a software engineer adopts a new release of the shared workflows safely:
read the changelog, try the update in one place, and go back if it fails. The
version rules are those of the release process: one version for the whole
repository, tags `vMAJOR.MINOR.PATCH` and a moving major tag `vMAJOR`.
## Which version you follow
| In your `uses:` line | You receive | When to use it |
| --- | --- | --- |
| `@v1.2.0` | nothing new, ever | a pipeline that must not change |
| `@v1` | compatible releases only (minor and patch) | the default for a project |
| `@main` | everything, unreleased | never; only for this repository's own tests |
A breaking release gets a new major version (`v2`), so a pipeline on `@v1`
never receives it until you change the line yourself.
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.
## Reading a changelog entry
Open `CHANGELOG.md` of `TirSystem/github-action`, or the release page of the tag.
An entry has up to four groups:
| Group | What it means for you |
| --- | --- |
| Breaking | You must act: a name, an input, a secret or a default changed. A release with this group has a new major version |
| Added | Nothing to do; a new optional input, workflow or capability |
| Changed | Nothing to do; no visible effect for existing callers |
| Fixed | Nothing to do; a fix you receive on `@v1` |
An entry that changes credentials, tokens or permissions says so; check your
secrets before you upgrade.
## Trying an update
1. Change the version in **one** repository, on a branch:
```yaml
jobs:
quality:
uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v2
```
2. Open a pull request and read the run. A failing check shows the tool, the
file and the message (see the guide for reading quality-check results).
3. For a breaking release, follow the upgrade notes of the changelog entry,
then repeat.
4. When the pull request is green, make the same change in the other
repositories.
## Going back
1. Change the line back to the previous exact tag, for example `@v1.2.0`, and
merge it. Exact tags are never deleted or moved, so this always works.
2. Tell the maintainers which release failed and what you saw, so that the
major tag can be moved back and a fix released.
## When something is unclear
| Symptom | Likely cause | Fix |
| --- | --- | --- |
| The run says the workflow cannot be found | The tag does not exist, or the path is wrong | Check the tag on the release page and the path `.gitea/workflows/quality-checks.yml` |
| A green pipeline turned red after a release on `@v1` | A compatible release should not do this | Pin the previous exact tag and report it as a defect |
| An input is no longer accepted | A breaking release renamed it | Read the Breaking group of the entry |
wiki/Upgrading.ms.md
+59
View File
@@ -0,0 +1,59 @@
<!-- translation of Upgrading.md, source sha256 ff8a06c4a03f -->
> Ini ialah terjemahan [`Upgrading`](Upgrading). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
[English](Upgrading) | [Dansk](Upgrading.da) | Bahasa Melayu
# Menaik taraf kepada versi baharu aliran kerja bersama
Cara seorang jurutera perisian menerima keluaran baharu aliran kerja bersama dengan selamat: baca changelog, cuba kemas kini di satu tempat, dan berpatah balik jika gagal. Peraturan versi ialah peraturan proses keluaran: satu versi untuk seluruh repositori, tag `vMAJOR.MINOR.PATCH` dan tag major yang boleh digerakkan `vMAJOR`.
## Versi yang anda ikuti
| Dalam baris `uses:` anda | Anda menerima | Gunakan apabila |
| --- | --- | --- |
| `@v1.2.0` | tiada apa-apa yang baharu, selama-lamanya | saluran paip tidak boleh berubah |
| `@v1` | keluaran serasi sahaja (minor dan patch) | pilihan lalai untuk sesebuah projek |
| `@main` | semuanya, termasuk yang belum dikeluarkan | jangan sekali-kali; hanya untuk ujian repositori ini sendiri |
Keluaran yang memecahkan keserasian mendapat versi major baharu (`v2`), jadi saluran paip pada `@v1` tidak menerimanya sehingga anda sendiri menukar baris itu.
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.
## Membaca satu catatan changelog
Buka `CHANGELOG.md` bagi `TirSystem/github-action`, atau halaman keluaran tag itu. Satu catatan mempunyai sehingga empat kumpulan:
| Kumpulan | Maksudnya untuk anda |
| --- | --- |
| Breaking | Anda mesti bertindak: nama, input, secret atau nilai lalai telah berubah. Keluaran dengan kumpulan ini mempunyai versi major baharu |
| Added | Tiada apa-apa untuk dibuat; input pilihan, aliran kerja atau keupayaan baharu |
| Changed | Tiada apa-apa untuk dibuat; tiada kesan yang kelihatan bagi pemanggil sedia ada |
| Fixed | Tiada apa-apa untuk dibuat; pembetulan yang anda terima pada `@v1` |
Catatan yang mengubah kelayakan (credentials), token atau kebenaran menyatakannya; semak secret anda sebelum menaik taraf.
## Mencuba satu kemas kini
1. Tukar versi dalam **satu** repositori, pada satu cabang:
```yaml
jobs:
quality:
uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v2
```
2. Buka pull request dan baca larian. Semakan yang gagal menunjukkan alat, fail dan mesej (lihat panduan membaca keputusan semakan kualiti).
3. Bagi keluaran yang memecahkan keserasian, ikut nota naik taraf dalam catatan changelog, kemudian ulang.
4. Apabila pull request hijau, buat perubahan yang sama dalam repositori lain.
## Berpatah balik
1. Tukar baris itu kembali kepada tag tepat yang terdahulu, contohnya `@v1.2.0`, dan gabungkan. Tag tepat tidak pernah dipadam atau digerakkan, jadi ini sentiasa berfungsi.
2. Beritahu penyelenggara keluaran mana yang gagal dan apa yang anda lihat, supaya tag major boleh digerakkan balik dan pembetulan dikeluarkan.
## Apabila ada yang tidak jelas
| Gejala | Punca yang mungkin | Pembetulan |
| --- | --- | --- |
| Larian menyatakan aliran kerja tidak ditemui | Tag tidak wujud, atau laluan salah | Semak tag pada halaman keluaran dan laluan `.gitea/workflows/quality-checks.yml` |
| Saluran paip hijau menjadi merah selepas keluaran pada `@v1` | Keluaran serasi tidak sepatutnya berbuat demikian | Sematkan tag tepat yang terdahulu dan laporkan sebagai kecacatan |
| Satu input tidak lagi diterima | Keluaran yang memecahkan keserasian menamakannya semula | Baca kumpulan Breaking dalam catatan itu |