Add the upgrade guide and the use case Consume a Workflow Update
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:
@@ -68,7 +68,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](guides/onboarding.md), [troubleshooting](guides/troubleshooting.md)); 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](guides/quality-checks.md)) |
|
||||
| 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](guides/upgrading.md)) |
|
||||
|
||||
### 🔄 Sync GitHub metadata
|
||||
|
||||
|
||||
@@ -11,12 +11,12 @@ 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 | 007 |
|
||||
| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 044 |
|
||||
| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 047 |
|
||||
| TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
|
||||
| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0007 |
|
||||
| UCD | Use Case Diagram | docs/use-case-diagram.md | 002 |
|
||||
| US | User Story | docs/user-stories.md | 002 |
|
||||
| UC | Use Case | docs/uc-NNN/uc.md | 007 |
|
||||
| UC | Use Case | docs/uc-NNN/uc.md | 008 |
|
||||
|
||||
## Languages
|
||||
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
# Review Record: UC-007
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | RC-044 |
|
||||
| CrossReference | [UC-007], [QC-UC-001] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending |
|
||||
|
||||
---
|
||||
|
||||
## Artifact Under Review
|
||||
|
||||
- Instance reviewed: [UC-007]
|
||||
- Checklist used: [QC-UC-001] (Brief format)
|
||||
|
||||
## Checklist Results
|
||||
|
||||
| # | Criterion | Status | Evidence/Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | Consists of a single, concise paragraph summarizing only the primary success scenario | Pass | The paragraph describes read, try in one repository, read the run, roll out; the rollback and the failures are in the stories and the guide. |
|
||||
| 2 | Written as an informal multi-paragraph narrative; may mention some alternate flows without formal structure | N-A | Format is Brief. |
|
||||
| 3 | All standard sections are present: actors, preconditions, postconditions, main success scenario, alternative/exception flows | N-A | Format is Brief; actor, stakeholders, pre- and postconditions and the paragraph are present. |
|
||||
| 4 | Preconditions and postconditions are explicitly defined | Pass | Both stated; the precondition names the release process of UC-006. |
|
||||
| 5 | Primary actor is explicitly stated | Pass | Software Engineer. |
|
||||
| 6 | Stakeholders and their interests are stated | Pass | S02 and S05. |
|
||||
| 7 | Main success scenario is written as clear, numbered steps | N-A | Format is Brief. |
|
||||
| 8 | Alternative/exception flows correctly reference `<<include>>`/`<<extend>>` use cases where relevant, per UML 2.5.1 | N-A | No alternative flows in a Brief use case. |
|
||||
| 9 | Explicit business rules are captured per step where applicable, rather than embedded loosely in narrative text | N-A | No steps in a Brief use case. |
|
||||
| 10 | Naming of actors and use case title is consistent with the corresponding Use Case Diagram and User Stories | Pass | Title and actor match UCD-001 (checked mechanically); stories are US-001.13 to US-001.15. |
|
||||
| 11 | Scope/level (e.g. summary, user-goal, subfunction) is explicitly stated | Pass | Scope and user-goal level. |
|
||||
| 12 | Use case is written from the actor's goal perspective, free of UI or implementation detail | Pass | Goal wording; no tool named. |
|
||||
|
||||
## Overall Verdict
|
||||
|
||||
Go - all applicable criteria pass. S01 gave the Go in chat on 2026-10-10, standing in for the other reviewers as ADR-0002 records; there is no independent reader.
|
||||
|
||||
## Action Items
|
||||
|
||||
| Action | Owner | Due |
|
||||
| --- | --- | --- |
|
||||
| None | - | - |
|
||||
|
||||
---
|
||||
|
||||
[UC-007]: ../../uc-007/uc.md
|
||||
[QC-UC-001]: ../../../framework/qc/qc-use-case.md
|
||||
@@ -0,0 +1,47 @@
|
||||
# Review Record: UCD-001 (consume an update)
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | RC-045 |
|
||||
| CrossReference | [UCD-001], [QC-UCD-001] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending |
|
||||
|
||||
---
|
||||
|
||||
## Artifact Under Review
|
||||
|
||||
- Instance reviewed: [UCD-001]
|
||||
- Checklist used: [QC-UCD-001]
|
||||
|
||||
## Checklist Results
|
||||
|
||||
| # | Criterion | Status | Evidence/Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | Actors are defined with correct UML stereotypes (e.g. `<<System>>`, `<<Actor>>`) | Pass | Unchanged actors. |
|
||||
| 2 | System boundary is clearly drawn and labeled | Pass | Unchanged. |
|
||||
| 3 | Include/extend relationships are used correctly per UML 2.5.1, not as generic "uses" arrows | Pass | The new use case has none; its dependency on UC-006 is a precondition. |
|
||||
| 4 | Every actor participates in at least one use case (no orphan actors) | Pass | Software Engineer now reaches two use cases. |
|
||||
| 5 | Diagram is traceable to a documented stakeholder need | Pass | S02 in the Actor Table. |
|
||||
| 6 | Use case names are verb phrases describing actor goals, not internal system operations | Pass | "Consume a Workflow Update". |
|
||||
| 7 | Diagram is free of implementation detail (e.g. UI widgets, database tables) | Pass | No tool or file named. |
|
||||
| 8 | Actor and use case naming is consistent with corresponding Use Case and User Story documents | Pass | UC-007's title and the story roles match. |
|
||||
|
||||
## Overall Verdict
|
||||
|
||||
Go - all eight criteria pass for the amendment (the use case of UC-007). S01 gave the Go in chat on 2026-10-10, standing in for the other reviewers as ADR-0002 records; there is no independent reader.
|
||||
|
||||
## Action Items
|
||||
|
||||
| Action | Owner | Due |
|
||||
| --- | --- | --- |
|
||||
| None | - | - |
|
||||
|
||||
---
|
||||
|
||||
[UCD-001]: ../../use-case-diagram.md
|
||||
[QC-UCD-001]: ../../../framework/qc/qc-use-case-diagram.md
|
||||
@@ -0,0 +1,46 @@
|
||||
# Review Record: US-001 (consume an update)
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | RC-046 |
|
||||
| CrossReference | [US-001], [QC-US-001] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending |
|
||||
|
||||
---
|
||||
|
||||
## Artifact Under Review
|
||||
|
||||
- Instance reviewed: [US-001]
|
||||
- Checklist used: [QC-US-001]
|
||||
|
||||
## Checklist Results
|
||||
|
||||
| # | Criterion | Status | Evidence/Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | Follows INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable) | Pass | INVEST check updated to fifteen stories. |
|
||||
| 2 | Written in "As a / I want / So that" form | Pass | US-001.14 and US-001.15. |
|
||||
| 3 | Clear, testable acceptance criteria are included | Pass | Two Given/When/Then criteria each; both are checked by reading the changelog or a run. |
|
||||
| 4 | Traceable to a use case or epic | Pass | UC-007 and MIL-004; US-001.13 is now traced to UC-007 as well, closing the gap noted in RC-041. |
|
||||
| 5 | Story is sized to fit within a single iteration | Pass | One goal each. |
|
||||
| 6 | Story statement avoids technical implementation detail | Pass | No tool named in the statements. |
|
||||
| 7 | Role named in the story matches an actor defined in the Use Case Diagram | Pass | Software Engineer is in UCD-001. |
|
||||
|
||||
## Overall Verdict
|
||||
|
||||
Go - all seven criteria pass. S01 gave the Go in chat on 2026-10-10, standing in for the other reviewers as ADR-0002 records; there is no independent reader.
|
||||
|
||||
## Action Items
|
||||
|
||||
| Action | Owner | Due |
|
||||
| --- | --- | --- |
|
||||
| None | - | - |
|
||||
|
||||
---
|
||||
|
||||
[US-001]: ../../user-stories.md
|
||||
[QC-US-001]: ../../../framework/qc/qc-user-story.md
|
||||
@@ -4,13 +4,13 @@
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | TM-001 |
|
||||
| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [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], [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], [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], [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-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added RC-039 for MIL-003 | [3b8681d] |
|
||||
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added UC-006, ADR-0006 and RC-040 to RC-043 | [044d8ba] |
|
||||
| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added UC-006, ADR-0006 and RC-040 to RC-043 | [044d8ba] |
|
||||
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added UC-007 and RC-044 to RC-046 | pending |
|
||||
|
||||
---
|
||||
|
||||
@@ -55,8 +55,8 @@ updated whenever an artifact instance is created or reviewed.
|
||||
| [RC-016] | RC | [MIL-006] | - | - |
|
||||
| [RC-017] | RC | [PP-001] | - | - |
|
||||
| [RC-018] | RC | [ADR-0004] | - | - |
|
||||
| [UCD-001] | UCD | [SA-001], [BC-001] | [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006] | [RC-019], [RC-035], [RC-040] |
|
||||
| [US-001] | US | [UCD-001], [BC-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004] | [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006] | [RC-020], [RC-036], [RC-041] |
|
||||
| [UCD-001] | UCD | [SA-001], [BC-001] | [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007] | [RC-019], [RC-035], [RC-040], [RC-045] |
|
||||
| [US-001] | US | [UCD-001], [BC-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004] | [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007] | [RC-020], [RC-036], [RC-041], [RC-046] |
|
||||
| [UC-001] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-021] |
|
||||
| [UC-002] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-022] |
|
||||
| [UC-003] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-023] |
|
||||
@@ -65,6 +65,7 @@ updated whenever an artifact instance is created or reviewed.
|
||||
| [ADR-0005] | ADR | [MIL-003], [UC-005], [US-001], [ADR-0004] | - | [RC-038] |
|
||||
| [UC-006] | UC | [UCD-001], [US-001], [SA-001] | [ADR-0006] | [RC-042] |
|
||||
| [ADR-0006] | ADR | [MIL-004], [UC-006], [US-001], [ADR-0004], [ADR-0005] | - | [RC-043] |
|
||||
| [UC-007] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-044] |
|
||||
| [RC-019] | RC | [UCD-001] | - | - |
|
||||
| [RC-020] | RC | [US-001] | - | - |
|
||||
| [RC-021] | RC | [UC-001] | - | - |
|
||||
@@ -90,6 +91,9 @@ updated whenever an artifact instance is created or reviewed.
|
||||
| [RC-041] | RC | [US-001] | - | - |
|
||||
| [RC-042] | RC | [UC-006] | - | - |
|
||||
| [RC-043] | RC | [ADR-0006] | - | - |
|
||||
| [RC-044] | RC | [UC-007] | - | - |
|
||||
| [RC-045] | RC | [UCD-001] | - | - |
|
||||
| [RC-046] | RC | [US-001] | - | - |
|
||||
|
||||
## Coverage Notes
|
||||
|
||||
@@ -162,9 +166,12 @@ updated whenever an artifact instance is created or reviewed.
|
||||
[RC-041]: ./reviews/rc-041-us-001-release.md
|
||||
[RC-042]: ./reviews/rc-042-uc-006.md
|
||||
[RC-043]: ./reviews/rc-043-adr-0006.md
|
||||
[RC-044]: ./reviews/rc-044-uc-007.md
|
||||
[RC-045]: ./reviews/rc-045-ucd-001-consume.md
|
||||
[RC-046]: ./reviews/rc-046-us-001-consume.md
|
||||
[UC-007]: ../uc-007/uc.md
|
||||
[UC-006]: ../uc-006/uc.md
|
||||
[ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.md
|
||||
[UC-005]: ../uc-005/uc.md
|
||||
[ADR-0005]: ../adr/adr-0005-quality-check-contract.md
|
||||
[3b8681d]: https://git.tirsystem.com/TirSystem/github-action/commit/3b8681d0236c669b794ffbba725433fff600a2d2
|
||||
[044d8ba]: https://git.tirsystem.com/TirSystem/github-action/commit/044d8ba21f96f4aceb807d62addc35cdcbb56051
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
# UC-007: Consume a Workflow Update
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | UC-007 |
|
||||
| CrossReference | [UCD-001], [US-001], [SA-001] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending |
|
||||
|
||||
---
|
||||
|
||||
**Format:** Brief
|
||||
|
||||
**Title:** Consume a Workflow Update
|
||||
**Scope:** Reusable Workflow Collection
|
||||
**Level:** user-goal
|
||||
**Primary Actor:** Software Engineer
|
||||
**Stakeholders:** S02, S05 (interests below)
|
||||
**Stories:** US-001.13, US-001.14, US-001.15
|
||||
|
||||
## Brief
|
||||
|
||||
When a new release of the shared workflows is announced, the Software Engineer reads its changelog entry to see whether it is breaking, changes the pinned version in one repository on a branch, opens a pull request and reads the run, and, when it is green, makes the same change in the other repositories.
|
||||
|
||||
**Stakeholder interests**
|
||||
|
||||
- S02 — an update is adopted deliberately, in one place first, and can be undone
|
||||
- S05 — consumers move to supported versions without a support request
|
||||
|
||||
**Preconditions:** Releases are versioned with a changelog (the release process), and the repository calls the shared workflow at a version tag.
|
||||
|
||||
**Postconditions (success guarantee):** The repository calls the new version, its pipeline still passes, and the previous version remains the way back.
|
||||
|
||||
---
|
||||
|
||||
[UCD-001]: ../use-case-diagram.md
|
||||
[US-001]: ../user-stories.md
|
||||
[SA-001]: ../stakeholder-analysis.md
|
||||
@@ -4,13 +4,13 @@
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | UCD-001 |
|
||||
| CrossReference | [SA-001], [BC-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006] |
|
||||
| CrossReference | [SA-001], [BC-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added the actor Software Engineer and the use case Run Project Quality Checks | [385d2fb] |
|
||||
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added the use case Release a Reusable Workflow (UC-006) | [044d8ba] |
|
||||
| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added the use case Release a Reusable Workflow (UC-006) | [044d8ba] |
|
||||
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added the use case Consume a Workflow Update (UC-007) (RC-045) | pending |
|
||||
|
||||
---
|
||||
|
||||
@@ -45,6 +45,7 @@ rectangle "Reusable Workflow Collection" <<System>> {
|
||||
usecase "Diagnose a Failed Workflow" as UC4
|
||||
usecase "Run Project Quality Checks" as UC5
|
||||
usecase "Release a Reusable Workflow" as UC6
|
||||
usecase "Consume a Workflow Update" as UC7
|
||||
}
|
||||
|
||||
DevOps --> UC1
|
||||
@@ -55,6 +56,7 @@ DevOps --> UC6
|
||||
Operator --> UC2
|
||||
Operator --> UC4
|
||||
Engineer --> UC5
|
||||
Engineer --> UC7
|
||||
UC1 --> Gitea
|
||||
UC1 --> GitHub
|
||||
UC3 ..> UC2 : <<include>>
|
||||
@@ -68,7 +70,7 @@ UC4 ..> UC1 : <<extend>>
|
||||
| --- | --- | --- | --- |
|
||||
| DevOps Professional | `<<Actor>>` | S05 | Synchronize Repository Metadata, Configure Workflow Credentials, Onboard a Repository, Diagnose a Failed Workflow, Release a Reusable Workflow |
|
||||
| Platform Operator | `<<Actor>>` | S03 | Configure Workflow Credentials, Diagnose a Failed Workflow |
|
||||
| Software Engineer | `<<Actor>>` | S02 | Run Project Quality Checks |
|
||||
| Software Engineer | `<<Actor>>` | S02 | Run Project Quality Checks, Consume a Workflow Update |
|
||||
| Gitea Instance | `<<System>>` | - | Synchronize Repository Metadata (source of description and topics) |
|
||||
| GitHub | `<<System>>` | S04 (audience of the mirror) | Synchronize Repository Metadata (target) |
|
||||
|
||||
@@ -82,6 +84,7 @@ UC4 ..> UC1 : <<extend>>
|
||||
| Diagnose a Failed Workflow | DevOps Professional, Platform Operator | The cause of a failed run is found and placed in a category |
|
||||
| Run Project Quality Checks | Software Engineer | Lint, format and type checks run on every change and report a pass or a fail |
|
||||
| Release a Reusable Workflow | DevOps Professional | A validated, versioned update that consumers can pin |
|
||||
| Consume a Workflow Update | Software Engineer | A new version is adopted safely, one repository first |
|
||||
|
||||
## Relationships
|
||||
|
||||
@@ -100,6 +103,6 @@ UC4 ..> UC1 : <<extend>>
|
||||
[UC-003]: ./uc-003/uc.md
|
||||
[UC-004]: ./uc-004/uc.md
|
||||
[UC-005]: ./uc-005/uc.md
|
||||
[385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7
|
||||
[UC-006]: ./uc-006/uc.md
|
||||
[044d8ba]: https://git.tirsystem.com/TirSystem/github-action/commit/044d8ba21f96f4aceb807d62addc35cdcbb56051
|
||||
[UC-007]: ./uc-007/uc.md
|
||||
|
||||
+33
-7
@@ -4,13 +4,13 @@
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | US-001 |
|
||||
| CrossReference | [UCD-001], [BC-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006] |
|
||||
| CrossReference | [UCD-001], [BC-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added US-001.09 and US-001.10 (quality checks, UC-005) | [385d2fb] |
|
||||
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added US-001.11 to US-001.13 (releases, UC-006); US-001.13 traced to the epic (RC-041) | [044d8ba] |
|
||||
| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added US-001.11 to US-001.13 (releases, UC-006); US-001.13 traced to the epic (RC-041) | [044d8ba] |
|
||||
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added US-001.14 and US-001.15 (UC-007); US-001.13 traced to UC-007 (RC-046) | pending |
|
||||
|
||||
---
|
||||
|
||||
@@ -19,7 +19,7 @@
|
||||
These stories cover the P1 use cases of the Project Plan that MIL-002 delivers
|
||||
(O1 to O3 of [BC-001]): keeping the mirror metadata correct, configuring
|
||||
credentials, onboarding a repository and diagnosing a failed run. Roles are the
|
||||
actors of [UCD-001]. Stories for quality checks and releases (the consumer's update, MIL-004) and for the wiki (MIL-005, MIL-006) are not written yet.
|
||||
actors of [UCD-001]. Stories for quality checks and releases (MIL-004) and for the wiki (MIL-005, MIL-006) are not written yet.
|
||||
|
||||
## Story List
|
||||
|
||||
@@ -190,11 +190,37 @@ actors of [UCD-001]. Stories for quality checks and releases (the consumer's upd
|
||||
|
||||
| Traces to | Size | INVEST exceptions |
|
||||
| --- | --- | --- |
|
||||
| [MIL-004] (epic; its use case, Consume a Workflow Update, is not written yet) | fits one iteration | none |
|
||||
| [UC-007], [MIL-004] | fits one iteration | none |
|
||||
|
||||
### US-001.14 — A changelog says whether to act
|
||||
|
||||
**As a** Software Engineer, **I want** to see in a changelog entry whether a release is breaking, **so that** I know whether I must change my pipeline.
|
||||
|
||||
**Acceptance Criteria**
|
||||
|
||||
- Given a release page or a changelog entry, when it is read, then the groups Breaking, Added, Changed and Fixed are visible and a breaking change is the first group.
|
||||
- Given a breaking release, when the entry is read, then it names what changed and what to do.
|
||||
|
||||
| Traces to | Size | INVEST exceptions |
|
||||
| --- | --- | --- |
|
||||
| [UC-007], [MIL-004] | fits one iteration | none |
|
||||
|
||||
### US-001.15 — Try an update in one place and go back
|
||||
|
||||
**As a** Software Engineer, **I want** to try a new version in one repository and return to the previous one, **so that** an update cannot harm all my pipelines at once.
|
||||
|
||||
**Acceptance Criteria**
|
||||
|
||||
- Given a branch that changes the pinned version in one repository, when its pull request runs, then the result of the new version is visible before any other repository changes.
|
||||
- Given a failing update, when the pin is set back to the previous exact tag, then the pipeline runs the previous code unchanged.
|
||||
|
||||
| Traces to | Size | INVEST exceptions |
|
||||
| --- | --- | --- |
|
||||
| [UC-007], [MIL-004] | fits one iteration | none |
|
||||
|
||||
## INVEST Check
|
||||
|
||||
All thirteen stories are independent of each other except that US-001.05 and
|
||||
All fifteen stories are independent of each other except that US-001.05 and
|
||||
US-001.06 build on US-001.04 (the secrets must exist before a repository can
|
||||
run the workflow). Each states one goal and can be negotiated, delivers value
|
||||
to the named role, is small enough for one iteration, and has acceptance
|
||||
@@ -215,6 +241,6 @@ behaviour is tested rather than built.
|
||||
[UC-003]: ./uc-003/uc.md
|
||||
[UC-004]: ./uc-004/uc.md
|
||||
[UC-005]: ./uc-005/uc.md
|
||||
[385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7
|
||||
[UC-006]: ./uc-006/uc.md
|
||||
[044d8ba]: https://git.tirsystem.com/TirSystem/github-action/commit/044d8ba21f96f4aceb807d62addc35cdcbb56051
|
||||
[UC-007]: ./uc-007/uc.md
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
# 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 |
|
||||
@@ -96,7 +96,7 @@ def _write_sources(root: Path) -> None:
|
||||
"### 🔄 Sync\nDetails.\n\n## 📄 License\nMIT.\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
for name in ("onboarding", "credentials", "troubleshooting", "quality-checks"):
|
||||
for name in ("onboarding", "credentials", "troubleshooting", "quality-checks", "upgrading"):
|
||||
(root / "guides" / f"{name}.md").write_text(
|
||||
f"# {name.title()}\nBody.\n", encoding="utf-8"
|
||||
)
|
||||
|
||||
@@ -44,6 +44,7 @@ PAGES: tuple[Page, ...] = (
|
||||
Page("Credentials", "guides/credentials.md"),
|
||||
Page("Troubleshooting", "guides/troubleshooting.md"),
|
||||
Page("QualityChecks", "guides/quality-checks.md"),
|
||||
Page("Upgrading", "guides/upgrading.md"),
|
||||
Page("Capabilities", "README.md", ("Capabilities",)),
|
||||
)
|
||||
|
||||
@@ -61,6 +62,7 @@ _PAGE_FOR_SOURCE = {
|
||||
"guides/credentials.md": "Credentials",
|
||||
"guides/troubleshooting.md": "Troubleshooting",
|
||||
"guides/quality-checks.md": "QualityChecks",
|
||||
"guides/upgrading.md": "Upgrading",
|
||||
}
|
||||
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 |
|
||||
@@ -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 |
|
||||
@@ -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 |
|
||||
Reference in New Issue
Block a user