Releases and Upgrade Guidance¶
Customers pin a version of the code repository and upgrade when they choose, sometimes over several versions at once. This section helps the platform team to see what changed between versions and what it has to do by hand when it takes a new one.
Who the platform team is depends on your operating model: XMMS engineers in the managed model, your own engineers in the self-managed model.
Pages in this section¶
| Page | Use it to |
|---|---|
| Release history | See what each major and minor version brought, and which versions needed manual steps |
| Platform upgrade guides | Do the version-specific steps from v4.4.0 up to v4.12.x |
| Spoke canvas upgrade guides | Do the version-specific steps for the older, separate spoke canvas (v2.9.x and v2.10.0), and see what each setting of its common.tf does |
| Generic update runbook | Follow the update flow of the older single-pipeline repositories |
| What to do when a new version is released | Follow the current upgrade procedure (hub, spoke and tooling pipelines) |
For the people who create releases, see Releasing; the format and tone of release notes are in its Release note conventions. For the rules that keep upgrades safe, see Backwards compatibility.
How versions work¶
| Version bump | What to expect |
|---|---|
Patch (v4.12.1 to v4.12.2) |
Bug fixes only. No configuration changes. |
Minor (v4.11.x to v4.12.0) |
New features, opt-in. A version-specific upgrade guide lists any manual step. |
Major (v4.x to v5.0) |
Breaking changes are possible. Each one comes with a migration in the upgrade guide. |
A customer configuration repository pins a release branch (for example release/v4.12) or a tag. A release branch gives
you every patch automatically on the next run. See
Versioning.
The contract was not always kept
Some minor versions in the history needed manual steps, such as removing policy assignments in the Azure portal or editing files in the configuration repository. Those steps are the reason upgrade guides exist. Always read the guide of every version between your current and your target version.
How to read a release note¶
Release notes use the same few headings in every version, so you can scan them quickly:
| Heading | What it tells you | Do you need to act? |
|---|---|---|
| New features | Something you can switch on. Opt-in | Only if you want it |
| Improvements | Existing behavior that got better | No |
| Bug fixes | Something that did not work and now does | Maybe: check whether you built a workaround |
| Breaking changes | A change that needs a step from you | Yes. Look for the upgrade guide |
| Known issues | A problem that is not fixed yet | Read it before you upgrade |
A title such as ... version 2.6.0 - Minor Release names the bump. A patch release needs no configuration change. A
minor release can have an upgrade guide. For a major release, expect one.
Where to find what¶
| Question | Answer |
|---|---|
| Which version do I run? | The pin in every entry pipeline of the configuration repository (step 1) |
| What changed in a version? | The release notes in the history, and the release notes of the code repository |
| Do I need to do something by hand? | The platform upgrade guides. A version without a guide needs no special steps |
| In which order do I run the layers? | Deployment layers. Legacy order: Generic update runbook |
| How do I know the upgrade worked? | A hub run from main plans no changes (step 8) |
Coverage of the release notes¶
The release notes in this documentation are condensed from the notes kept for each version:
- v2.0 to v4.6.1 have release notes. v3.3 to v4.3 have none.
- From v4.7 onward there are upgrade guides (v4.7.0, v4.9.0, v4.11.x, v4.12.x) but no separate release notes. The history lists what those guides show.
- The newest tags at the time of writing are on
release/v4.12. Check the code repository for the latest patch (Release state today).