Tirsvad
4cf52afe00
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
67 lines
2.9 KiB
Markdown
67 lines
2.9 KiB
Markdown
# 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 |
|