From c6ca48fafa653450673f8238fd4a794f51a6eb01 Mon Sep 17 00:00:00 2001 From: Roger Luethi Date: Fri, 12 Jun 2026 14:11:09 +0200 Subject: [PATCH 1/2] Rewrite the releases developer guide The guide still described the release process of the 5.x/6.x era and had drifted far from current practice: * The pre-release directory mechanics (copying latest/, stripping renovate lines, fixing symlinks, prepare-release.py) were replaced by src/create-version.py and -rc.N release candidates. * Release-name tags on the container image repositories were replaced by date-based component tags created with scripts/create-tags.sh. * The osism/sbom repository is archived, so all SBOM steps are gone. * Reno is no longer used in the component repositories; release notes live in osism/osism.github.io and per-component changelogs are generated in the osism/release repository. All of the in-repo mechanics are documented in the README of the osism/release repository, so link there instead of duplicating them. Keep what that README does not cover: the release policy (major/minor semantics and upgrade guarantees) and the cross-repo release checklist, reverse engineered from the git history of the 9.x and 10.0.0 releases (testbed release candidate jobs, release notes in the documentation, version examples in the documentation, the cfg-cookiecutter manager_version default, and switching the testbed stable jobs as the final step). Statements that need confirmation by the team are marked with warning admonitions: the release cadence, the completeness and order of the checklist, the retirement of GitHub releases on osism/release, and the removal of the Reno section. Assisted-by: Claude:claude-fable-5 Signed-off-by: Roger Luethi --- docs/guides/developer-guide/releases.md | 389 ++++++++---------------- 1 file changed, 122 insertions(+), 267 deletions(-) diff --git a/docs/guides/developer-guide/releases.md b/docs/guides/developer-guide/releases.md index f3d3aa82aa..0c26bf3637 100644 --- a/docs/guides/developer-guide/releases.md +++ b/docs/guides/developer-guide/releases.md @@ -7,8 +7,19 @@ sidebar_position: 10 ## How we handle releases -Currently we do a major release every 6 months. Minor releases we do when -needed and about every 2 weeks. +Currently we do a major release about once a year. Minor releases we do when +needed, typically every couple of months. + +:::warning Confirm release cadence + +This guide previously stated "a major release every 6 months" and "minor +releases about every 2 weeks". Recent practice differs: the last major +releases were 7–11 months apart (8.0.0: September 2024, 9.0.0: April 2025, +10.0.0: March 2026), and the 9.x minor releases were 6–10 weeks apart. +The wording above is derived from observed practice and needs to be +confirmed as the intended cadence. + +::: In a minor release, only updates, bug fixes, etc. take place. There are also no major upgrades of included components such as OpenStack, Keycloak or Ceph @@ -19,7 +30,8 @@ minor versions without any intervention. Deprecations, removals, etc. take place in a major release. New mandatory features are also added in a major release. Upgrades of the included components -can also take place during a major release (e.g. OpenStack Xena -> OpenStack Yoga). +can also take place during a major release (e.g. OpenStack 2024.1 -> OpenStack +2025.1). It is possible to jump from the previous major version to the next major version. It may be that manual intervention is necessary. For example, configuration @@ -28,270 +40,113 @@ removed. ## How to make a release -1. On all repositories that are used, check that the versions to be used have an - appropriate version tag (e.g. `v0.20230308.0`). - - ```text - osism/ansible-collection-commons - osism/ansible-collection-services - osism/ansible-collection-validations - osism/ansible-defaults - osism/ansible-playbooks - osism/ansible-playbooks-manager - osism/cf-generics - osism/kolla-operations - osism/python-osism - ``` - -2. Copy the `latest` directory. The release to be created is used as the new name. - - ```text - latest -> 6.0.0b - ``` - -3. Remove all `# renovate` lines from the `base.yml` file. - -4. Remove all Ceph and OpenStack releases that should not be part of the pre-release. - There is only one OpenStack version and one Ceph version per (pre-)release. - -5. Ensure that the symlinks `openstack.yml` and `ceph.yml` point to the releases - to be used in this pre-release. - - ```text - base.yml - ceph-pacific.yml - ceph.yml -> ceph-pacific.yml - openstack-zed.yml - openstack.yml -> openstack-zed.yml - ``` - -6. Run `src/prepare-release.py`. - - ```bash - RELEASE=6.0.0b python3 src/prepare-release.py - ``` - -7. Do the steps from the `Stable release` starting from the 4th step. - -### Stable release - -1. Copy the directory of the last pre-release or the previous stable release. - The release to be created is used as the new name. - - ```text - 5.0.0a -> 5.0.0b - 5.0.0b -> 5.0.0 - 5.0.0 -> 5.1.0 - 5.1.0 -> 5.2.0 - 5.2.0 -> 5.3.0 - ``` - -2. Change all necessary versions in the YAML files within the new directory. - In any case, the version of the pre-release or the version of the stable - release must be replaced by the release to be created. - -3. The release to be created is submitted as a pull request as usual and then - merged. - -4. Add a tag with the name of the new release to the listed repositories. - - ```text - osism/container-image-ceph-ansible - osism/container-image-inventory-reconciler - osism/container-image-osism-ansible - osism/container-images-kolla - ``` - -5. After completing the creation of the images in repository `container-images-kolla`, - the file `images.yml` must be added to repository `osism/sbom` as - `5.0.0/openstack.yml` (instead of `5.0.0`, the corresponding release is used). - The file is available as a build artifact of the `Release container images` action - on the created tag. - - Before the file is added, it is enhanced with the checksums of the images. The script - is available in the `osism/sbom` repository. - - ```bash - VERSION=5.0.0 python3 scripts/add-image-checksum.py - ``` - -6. If `5.0.0/openstack.yml` is present in `osism/sbom`, repository - `osism/container-image-kolla-ansible` can be tagged like the other - repositories before. - -7. Add the created SPDX files from the listed repositories to the `osism/sbom` repository. - The file are available as build artifacts of the ``Build container image`` action - on the created tags. - - ```text - osism/container-image-ceph-ansible - osism/container-image-kolla-ansible - osism/container-image-osism-ansible - ``` - -8. Add and run temporary CI jobs in `osism/testbed` that uses the pre-release. - - ```yaml - - job: - name: testbed-deploy-stable-next - parent: testbed-deploy - vars: - manager_version: "5.0.0a" - refstack: true - nodeset: testbed-orchestrator - - - job: - name: testbed-upgrade-stable-next - parent: testbed-deploy - vars: - manager_version: "4.2.0" - manager_version_next: "5.0.0a" - nodeset: testbed-orchestrator - ``` - -9. Test. Test. Test. - -10. Prepare a PR to change the stable version to the new stable version in the following Zuul jobs - in the `osism/testbed` repository. All tests there must pass successfully before the tag is - set on this repository in the next step. The temporary CI jobs (step 8) are removed again with - this PR. - - ```text - testbed-deploy-stable - testbed-update-stable - testbed-update-stable - testbed-upgrade-stable - ``` - -11. Add a new release notes file to `doc/source/notes`. Generate the versions table with the - help of the `release-table.py` script in the `osism/sbom` repository. - -12. After all known issues are documented, a corresponding tag, e.g. `5.0.0`, is set on the - [osism/release](https://github.com/osism/release/releases) repository. - -13. Create a [GitHub release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) with the new tag on the - [osism/release](https://github.com/osism/release/releases) repository. The release is - now public available. - -14. As the last of the release process, the previously prepared PR is merged on the - `osism/testbed` repository to change the stable version. +All component versions of a release are pinned in the +[osism/release](https://github.com/osism/release) repository. The mechanics +inside that repository — continuous version updates via Renovate, tagging the +core container image projects with `scripts/create-tags.sh`, freezing a +release with `src/create-version.py`, and changelog generation — are +documented in the +[README of the osism/release repository](https://github.com/osism/release#release-process). + +The checklist below covers the overall release flow, including the steps that +happen outside the osism/release repository. + +:::warning Confirm checklist + +This checklist was reverse engineered from the git history of the 9.x and +10.0.0 releases. The testbed jobs are switched ahead of the documentation +steps to match the order observed for the 10.1.0 release, but the completeness +of the steps still needs to be confirmed by the people who actually made those +releases. + +::: + +1. Create one or more release candidates (e.g. `10.1.0-rc.1`) in the + osism/release repository as described in its README. + +2. Add temporary release candidate jobs to `.zuul.yaml` in the + [osism/testbed](https://github.com/osism/testbed) repository that deploy + the release candidate and upgrade from the current stable release to the + release candidate (e.g. `abstract-testbed-deploy-rc` with + `manager_version: 10.1.0-rc.1` and `abstract-testbed-upgrade-rc`). + +3. Test. Test. Test. + +4. Create the final release version (e.g. `10.1.0`) in the osism/release + repository as described in its README. + +5. Switch the pinned stable jobs in the + [osism/testbed](https://github.com/osism/testbed) repository to the new + release and remove the temporary release candidate jobs added in step 2. + Do this before the documentation steps that follow: the stable jobs are + what validate the release, so they must pass before it is announced. For + the `10.1.0` example the version variables change as follows. + + - Deploy jobs (`abstract-testbed-deploy-stable` and + `abstract-testbed-deploy-stable-in-a-nutshell`): set `manager_version` + to the new release — `10.1.0`. + + - Upgrade job (`testbed-upgrade-stable-*`): a major upgrade across the + series boundary, from the last release of the previous major series to + the new release — `manager_version: 9.5.0`, + `manager_version_next: 10.1.0`. + + - Update job (`testbed-update-stable-*`): a minor update within the same + major series, from the preceding release in the series to the new + release — `manager_version: 10.0.0`, `manager_version_next: 10.1.0`. + The first release of a new major series has no in-series predecessor, + so this job only becomes meaningful from the second release of a series + onwards. + + The jobs that track the development head instead of a pinned release — + `testbed-update-stable-current-*` (update to `latest`) and + `testbed-upgrade-stable-next-*` (upgrade to `latest`) — are not touched + here. All stable jobs must pass successfully. + +6. Add release notes to the + [osism/osism.github.io](https://github.com/osism/osism.github.io) + repository: a new `docs/release-notes/osism-N.md` file for a major + release, or a new entry in the existing file for a minor release. + +7. Update the version examples in the documentation that reference a concrete + release, e.g. `docs/guides/configuration-guide/manager.mdx`, + `docs/guides/upgrade-guide/manager.mdx` and + `docs/guides/configuration-guide/configuration-repository.md`. + +8. As the last step, bump the `manager_version` default in the + [osism/cfg-cookiecutter](https://github.com/osism/cfg-cookiecutter) + repository so that newly created configuration repositories use the new + release. The documentation promises that this default is always the latest + stable release. + +:::warning Confirm retirement of GitHub releases + +Earlier releases were tagged on the osism/release repository and published as +[GitHub releases](https://github.com/osism/release/releases). This was last +done for 8.0.2 (October 2024), and the Releases section is now hidden on the +repository homepage. It needs to be confirmed that GitHub releases are +permanently retired — and documented what, if anything, replaces them as the +public release announcement. + +::: ## How we write release notes -We use [Reno](https://docs.openstack.org/reno/latest/) to manage the release notes. - -### Installation - -Reno is provided as a [Python package](https://pypi.org/project/reno/) and can be installed with pip. - -```bash -pip3 install reno -``` - -### Usage - -For each change in a repository, a release note is created with Reno. -Something meaningful is used as the name for the note. For example, if the -requirements file for Ansible is removed, `remove-ansible-requirements` is a good name. - -```console -$ reno new remove-ansible-requirements -no configuration file in: ./releasenotes/config.yaml, ./reno.yaml -Created new notes file in releasenotes/notes/remove-ansible-requirements-6c6eba43f616bc6b.yaml -``` - -The created file contains prepared entries for several categories. It is described briefly -in each instance which contents belong in which category. What is not needed is deleted. - -```yaml -prelude: > - Replace this text with content to appear at the top of the section for this - release. All of the prelude content is merged together and then rendered - separately from the items listed in other parts of the file, so the text - needs to be worded so that both the prelude and the other items make sense - when read independently. This may mean repeating some details. Not every - release note requires a prelude. Usually only notes describing major - features or adding release theme details should have a prelude. -features: - - | - List new features here, or remove this section. All of the list items in - this section are combined when the release notes are rendered, so the text - needs to be worded so that it does not depend on any information only - available in another section, such as the prelude. This may mean repeating - some details. -issues: - - | - List known issues here, or remove this section. All of the list items in - this section are combined when the release notes are rendered, so the text - needs to be worded so that it does not depend on any information only - available in another section, such as the prelude. This may mean repeating - some details. -upgrade: - - | - List upgrade notes here, or remove this section. All of the list items in - this section are combined when the release notes are rendered, so the text - needs to be worded so that it does not depend on any information only - available in another section, such as the prelude. This may mean repeating - some details. -deprecations: - - | - List deprecations notes here, or remove this section. All of the list - items in this section are combined when the release notes are rendered, so - the text needs to be worded so that it does not depend on any information - only available in another section, such as the prelude. This may mean - repeating some details. -critical: - - | - Add critical notes here, or remove this section. All of the list items in - this section are combined when the release notes are rendered, so the text - needs to be worded so that it does not depend on any information only - available in another section, such as the prelude. This may mean repeating - some details. -security: - - | - Add security notes here, or remove this section. All of the list items in - this section are combined when the release notes are rendered, so the text - needs to be worded so that it does not depend on any information only - available in another section, such as the prelude. This may mean repeating - some details. -fixes: - - | - Add normal bug fixes here, or remove this section. All of the list items - in this section are combined when the release notes are rendered, so the - text needs to be worded so that it does not depend on any information only - available in another section, such as the prelude. This may mean repeating - some details. -other: - - | - Add other notes here, or remove this section. All of the list items in - this section are combined when the release notes are rendered, so the text - needs to be worded so that it does not depend on any information only - available in another section, such as the prelude. This may mean repeating - some details. -``` - -### Example - -Here is an example of a [commit from the osism/generics repository](https://github.com/osism/generics/commit/e2f04a9f4a51eb058446d7a8ab6835df53989099). - -```yaml ---- -features: - - | - The `requirements.yml` has been removed. The version will be set in the `run.sh` - script for the seed process in the future exactly as later in the update process - via the parameters `ANSIBLE_COLLECTION_SERVICES_VERSION` and - `ANSIBLE_PLAYBOOKS_MANAGER_VERSION`. -upgrade: - - | - In existing configuration repositories, the `environments/manager/requirements.yml` - file can be removed after the generics have been synced. -``` - -### Repositories without release notes - -We do not create release notes in the following repositories: - -* osism/github-manager -* osism/osism.github.io -* osism/release +Release notes for OSISM releases are maintained as Markdown pages in the +[osism/osism.github.io](https://github.com/osism/osism.github.io) repository +(`docs/release-notes/`) and published at +[osism.tech/docs/release-notes](https://osism.tech/docs/release-notes/). + +Per-component changelogs are generated from the git history in the +osism/release repository. This is documented in the +[README of the osism/release repository](https://github.com/osism/release#release-process). + +:::warning Removed: Reno + +This guide previously documented [Reno](https://docs.openstack.org/reno/latest/) +based release notes in the component repositories. Reno is no longer used +(e.g. osism/generics removed its release notes in +[#446](https://github.com/osism/generics/pull/446)), so that section was +removed. Please confirm that no component repository still relies on Reno. + +::: From 2ed5bf9d457d605606d9171299a3ce2dd0667ce3 Mon Sep 17 00:00:00 2001 From: Roger Luethi Date: Wed, 24 Jun 2026 21:43:57 +0200 Subject: [PATCH 2/2] releases: note inventory sync on series bump A major release that moves to a new OpenStack series must bump KOLLA_BRANCH in osism/generics src/check-kolla-inventory.py to the matching kolla-ansible stable branch and resolve the resulting inventory drift before anything else. The inventory is baked into the osism-ansible and inventory-reconciler images, so it has to match the new series before the release candidate is built and tested -- otherwise the testing steps validate an inventory that aborts on the new release (as the neutron and ironic-dnsmasq groups did in the 2025.2 series). Add this as a prerequisite note before the release checklist rather than a numbered step, since it is major-release-only and gates the steps that follow. Assisted-by: Claude:claude-opus-4-8 Signed-off-by: Roger Luethi --- docs/guides/developer-guide/releases.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/guides/developer-guide/releases.md b/docs/guides/developer-guide/releases.md index 0c26bf3637..342af7fe2b 100644 --- a/docs/guides/developer-guide/releases.md +++ b/docs/guides/developer-guide/releases.md @@ -61,6 +61,20 @@ releases. ::: +:::note Major releases: sync the inventory first + +If the release moves to a new OpenStack series, bump `KOLLA_BRANCH` in +[osism/generics](https://github.com/osism/generics) +`src/check-kolla-inventory.py` to the matching `stable/` branch and +resolve the drift the `generics-tox-check-kolla` job then reports — add the +new kolla-ansible service groups to the inventory (or, for services OSISM does +not deploy, to the IGNORE lists) and merge. The inventory is baked into the +`osism-ansible` and `inventory-reconciler` images, so it must match the new +series before the release candidate is built and tested; otherwise the testing +in the steps below validates an inventory that aborts on the new release. + +::: + 1. Create one or more release candidates (e.g. `10.1.0-rc.1`) in the osism/release repository as described in its README.