Releasing Ironic Projects

Since the responsibility for releases will move between people, we document that process here.

A full list of projects that Ironic manages is available in the governance site.

Who is responsible for releases?

The current PTL is ultimately responsible for making sure code gets released. They may choose to delegate this responsibility to a liaison, which is documented in the release liaison documentation.

Anyone may submit a release request per the process below, but the PTL or liaison must +1 the request for it to be processed.

Release process

Releases are managed by the OpenStack release team. The release process is documented in the Project Team Guide.

What do we have to release?

The Ironic project has a number of deliverables under its governance. The ultimate source of truth for this is projects.yaml in the governance repository. These deliverables have varying release models, and these are defined in the deliverables YAML files in the releases repository.

In general, Ironic deliverables follow the cycle-with-intermediary release model.

Non-client libraries

The following deliverables are non-client libraries:

Client libraries

The following deliverables are client libraries:

Normal release

The following deliverables are Neutron plugins:

The following deliverables are Horizon plugins:

The following deliverables are Tempest plugins:

The following deliverables are tools:

  • ironic-python-agent-builder

    Note

    if ironic-python-agent-builder is branched after ironic-python-agent, we need to make sure all artifacts are built by the time of Ironic branching.

The following deliverables are services, or treated as such:

Manual release

The ironic-staging-drivers follows a different procedure, see Releasing ironic-staging-drivers.

Independent

The following deliverables are released independently:

Not released

The following deliverables do not need to be released:

OpenStack Release Schedule

The Ironic project follows the OpenStack coordinated release schedule. Each OpenStack release cycle spans approximately 6 months (26 weeks) and follows a structured timeline with specific milestones and deadlines.

Based on the standard OpenStack release schedule, a typical release cycle includes the following key phases:

Release Timeline Overview

Development Phase (Weeks R-25 to R-12)
  • R-25 to R-21: Early development, feature planning

  • R-20 (Week 6): First milestone

  • R-17: Cycle-trailing release deadline for previous cycle

  • R-12 (Week 14): Second milestone and membership freeze

Feature Development Phase (Weeks R-11 to R-5)
Stabilization Phase (Weeks R-4 to R-1)
Release Week (R+0)

Key Deadlines for Ironic Projects

Milestone Releases
  • Projects following the cycle-with-intermediary model should aim to release at each milestone

  • Milestone participation is required for projects to be considered part of the coordinated release

Library Releases
Plugin Releases
Service Releases
Feature Freeze (R-5)
  • No new features accepted after the third milestone

  • Focus shifts to bug fixes and stabilization

  • Release notes should be finalized

String Freeze
  • Soft string freeze at R-5: No new user-facing strings

  • Hard string freeze at R-3: No string changes to allow translation work

Requirements Freeze (R-5)
  • Only critical requirements changes allowed after feature freeze

  • Helps downstream packagers prepare for the release

Planning Your Release

When planning Ironic releases within an OpenStack cycle:

  1. Early Cycle (R-25 to R-12): Plan major features, coordinate with dependencies

  2. Mid Cycle (R-11 to R-6): Complete feature development, release libraries

  3. Late Cycle (R-5 to R+0): Focus on stabilization, bug fixes, and release preparation

For the most current release schedule, always refer to the official OpenStack releases website at https://releases.openstack.org/.

Bugfix branches

Some Ironic deliverables also use short-lived bugfix/X.Y branches between coordinated OpenStack releases. The projects, cadence, eligibility criteria, branching procedure, and maintenance instructions are documented in Bugfix Branches.

Things to do before releasing

  • Review the unreleased release notes, if the project uses them. Make sure they follow our standards, are coherent, and have proper grammar. Combine release notes if necessary (for example, a release note for a feature and another release note to add to that feature may be combined).

  • For Ironic releases only: if any new API microversions have been added since the last release, update the REST API version history (doc/source/contributor/webapi-version-history.rst) to indicate that they were part of the new release.

  • To support rolling upgrades, add this new release version (and release name if it is a named release) into ironic/common/release_mappings.py:

    • in RELEASE_MAPPING make a copy of the master entry, and rename the first master entry to the new semver release version.

    • If this is a named release, add a RELEASE_MAPPING entry for the named release. Its value should be the same as that of the latest semver one (that you just added above).

      It is important to do this before a stable/<release> branch is made (or if the grenade switch is made to use the latest release from stable as the ‘old’ release). Otherwise, once it is made, CI (the grenade job that tests new-release -> master) will fail.

  • Check for any open patches that are close to be merged or release critical.

    This usually includes important bug fixes and/or features that we’d like to release, including the related documentation.

How to propose a release

The steps that lead to a release proposal are mainly manual, while proposing the release itself is almost a 100% automated process, accomplished by following the next steps:

  • Clone the openstack/releases repository. This is where deliverables are tracked and all the automation resides.

    • Under the deliverables directory you can see yaml files for each deliverable (i.e. subproject) grouped by release cycles.

    • The _independent directory contains yaml files for deliverables that are not bound to (official) cycles (e.g. Ironic-python-agent-builder).

  • To check the changes we’re about to release we can use the tox environment list-unreleased-changes, with this syntax:

    tox -e venv -- list-unreleased-changes <series> <deliverable>
    

    The series argument is a release series (i.e. master or train, not stable/ussuri or stable/train).

    For example, assuming we’re in the main directory of the releases repository, to check the changes in the ussuri series for Ironic-python-agent type:

    tox -e venv -- list-unreleased-changes ussuri openstack/ironic-python-agent
    
  • To update the deliverable file for the new release, we use a scripted process in the form of a tox environment called new-release.

    To get familiar with it and see all the options, type:

    tox -e venv -- new-release -h
    

    Now, based on the list of changes we found in the precedent step, and the release notes, we need to decide on whether the next version will be major, minor (feature) or patch (bugfix).

    Note that in this case series is a code name (train, ussuri), not a branch. That is also valid for the current development branch (master) that takes the code name of the future stable release, for example if the future stable release code name is wallaby, we need to use wallaby as series.

    The --stable-branch argument is used only for branching in the end of a cycle, independent projects are not branched this way though.

    To create an intermediate bugfix branch, use the --intermediate-branch option. See Bugfix Branches for the project list and branch-specific instructions.

    To propose the release, use the script to update the deliverable file, then commit the change, and propose it for review.

    For example, to propose a minor release for Ironic in the master branch (current development branch), considering that the code name of the future stable release is wallaby, use:

    tox -e venv -- new-release -v wallaby ironic feature
    

    Remember to use a meaningful topic, usually using the name of the deliverable, the new version and the branch, if applicable.

    A good commit message title should also include the same, for example “Release Ironic 1.2.3 for ussuri”

  • As an optional step, we can use tox -e list-changes to double-check the changes before submitting them for review.

    Also tox -e validate (it might take a while to run based on the number of changes) does some some sanity-checks, but since everything is scripted, there shouldn’t be any issue.

    All the scripts are designed and maintained by the release team; in case of questions or doubts or if any errors should arise, you can reach to them in the IRC channel #openstack-release; all release liaisons should be present there.

  • After the change is up for review, the PTL or a release liaison will have to approve it before it can get approved by the release team. Then, it will be processed automatically by zuul.

Things to do after releasing

When a release is done that results in a stable branch

When a release is done that results in a stable branch for the project, several changes need to be made.

The release automation will push a number of changes that need to be approved. This includes:

  • In the new stable branch:

    Note

    OpenStack Release tooling does this automatically.

    • a change to point .gitreview at the branch

    • a change to update the upper constraints file used by tox

  • In the master branch:

    • updating the release notes RST to include the new branch.

      The generated RST does not include the version range in the title, so we typically submit a follow-up patch to do that. An example of this patch is here.

    • update the templates in .zuul.yaml or zuul.d/project.yaml.

      The update is necessary to use the job for the next release openstack-python3-<next_release>-jobs. An example of this patch is here.

We need to submit patches for changes in the stable branch to:

  • update the Ironic devstack plugin to point at the branched tarball for IPA. An example of this patch is here.

  • set appropriate defaults for TEMPEST_BAREMETAL_MIN_MICROVERSION and TEMPEST_BAREMETAL_MAX_MICROVERSION in devstack/lib/ironic to make sure that unsupported API tempest tests are skipped on stable branches. E.g. patch 495319.

  • remove any CI jobs which are not required. Mainly this revolves around the metal3-integration CI job, however other non-voting jobs can also be removed safely. This can be achieved by editing the .zuul.d/project.yaml file.

Note

It is normal to reduce the number of CI jobs present on a stable branch the longer the branch exists. This is a mix of challenges related to distributions, dependencies, and CI resources. Maintainers should anticipate this as a normal activity and should avoid heroic efforts.

We need to submit patches for changes on master to:

  • to support rolling upgrades, since the release was a named release, we need to make these changes. Note that we need to wait until after the switch in grenade is made to test the latest release (N) with master (e.g. for stable/queens). Doing these changes sooner – after the Ironic release and before the switch when grenade is testing the prior release (N-1) with master, will cause the tests to fail. (You may want to ask/remind infra/qa team, as to when they will do this switch.)

    • In ironic/common/release_mappings.py, delete any entries from RELEASE_MAPPING associated with the oldest named release. Since we support upgrades between adjacent named releases, the master branch will only support upgrades from the most recent named release to master.

    • remove any DB migration scripts from ironic.command.dbsync.ONLINE_MIGRATIONS and remove the corresponding code from Ironic. (These migration scripts are used to migrate from an old release to this latest release; they shouldn’t be needed after that.)

Ironic Tempest plugin

As ironic-tempest-plugin is branchless, we need to submit a patch adding stable jobs to its master branch. Example for Queens.

Bifrost

Bifrost needs to be updated to install dependencies using the stable branch. Example for Victoria. The upper constraints file referenced in scripts/install-deps.sh needs to be updated to the new release.

For all releases

For all releases, whether or not it results in a stable branch:

  • update the specs repo to mark any specs completed in the release as implemented.

  • remove any -2s on patches that were blocked until after the release.