Merge "Add comprehensive release liaison guide for DPL model"
This commit is contained in:
Zuul
@@ -10,3 +10,4 @@ Contribution Guide
|
|||||||
devstack
|
devstack
|
||||||
testing
|
testing
|
||||||
rally_link
|
rally_link
|
||||||
|
release-guide
|
||||||
|
|||||||
462
doc/source/contributor/release-guide.rst
Normal file
462
doc/source/contributor/release-guide.rst
Normal file
@@ -0,0 +1,462 @@
|
|||||||
|
..
|
||||||
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||||
|
not use this file except in compliance with the License. You may obtain
|
||||||
|
a copy of the License at
|
||||||
|
|
||||||
|
http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
|
||||||
|
Unless required by applicable law or agreed to in writing, software
|
||||||
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||||
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||||
|
License for the specific language governing permissions and limitations
|
||||||
|
under the License.
|
||||||
|
|
||||||
|
Chronological Release Liaison Guide
|
||||||
|
====================================
|
||||||
|
|
||||||
|
This is a reference guide that a release liaison may use as an aid, if
|
||||||
|
they choose.
|
||||||
|
|
||||||
|
Watcher uses the `Distributed Project Leadership (DPL)`__ model where
|
||||||
|
traditional release liaison responsibilities are distributed among various
|
||||||
|
liaisons. The release liaison is responsible for requesting releases,
|
||||||
|
reviewing Feature Freeze Exception (FFE) requests, and coordinating
|
||||||
|
release-related activities with the team.
|
||||||
|
|
||||||
|
.. __: https://governance.openstack.org/tc/reference/distributed-project-leadership.html
|
||||||
|
|
||||||
|
How to Use This Guide
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
This guide is organized chronologically to follow the OpenStack release
|
||||||
|
cycle from PTG planning through post-release activities. You can use it
|
||||||
|
in two ways:
|
||||||
|
|
||||||
|
**For New Release Liaisons**
|
||||||
|
Read through the entire guide to understand the full release cycle,
|
||||||
|
then bookmark it for reference during your term.
|
||||||
|
|
||||||
|
**For Experienced Release Liaisons**
|
||||||
|
Jump directly to the relevant section for your current phase in the
|
||||||
|
release cycle. Each major section corresponds to a specific time period.
|
||||||
|
|
||||||
|
**Key Navigation Tips**
|
||||||
|
* The :ref:`glossary` defines all acronyms and terminology used
|
||||||
|
* Time-sensitive activities are clearly marked by milestone phases
|
||||||
|
* DPL coordination notes indicate when team collaboration is required
|
||||||
|
|
||||||
|
DPL Liaison Coordination
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
Under the DPL model, the release liaison coordinates with other project
|
||||||
|
liaisons and the broader team for effective release management. The release
|
||||||
|
liaison has authority for release-specific decisions (FFE approvals, release
|
||||||
|
timing, etc.) while major process changes and strategic decisions require
|
||||||
|
team consensus.
|
||||||
|
|
||||||
|
This coordination approach ensures that:
|
||||||
|
|
||||||
|
* Release activities are properly managed by a dedicated liaison
|
||||||
|
* Team input is gathered for significant decisions
|
||||||
|
* Other liaisons are informed of release-related developments that may
|
||||||
|
affect their areas
|
||||||
|
* Release processes remain responsive while maintaining team alignment
|
||||||
|
|
||||||
|
Project Context
|
||||||
|
---------------
|
||||||
|
|
||||||
|
* Coordinate with the watcher meeting (chair rotates each meeting, with
|
||||||
|
volunteers requested at the end of each meeting)
|
||||||
|
|
||||||
|
* Meeting etherpad: https://etherpad.opendev.org/p/openstack-watcher-irc-meeting
|
||||||
|
* IRC channel: #openstack-watcher
|
||||||
|
|
||||||
|
* Get acquainted with the release schedule
|
||||||
|
|
||||||
|
* Example: https://releases.openstack.org/<current-release>/schedule.html
|
||||||
|
|
||||||
|
* Familiarize with Watcher project repositories and tracking:
|
||||||
|
|
||||||
|
Watcher Main Repository
|
||||||
|
`Primary codebase for the Watcher service <https://opendev.org/openstack/watcher>`__
|
||||||
|
|
||||||
|
Watcher Dashboard
|
||||||
|
`Horizon plugin for Watcher UI <https://opendev.org/openstack/watcher-dashboard>`__
|
||||||
|
|
||||||
|
Watcher Tempest Plugin
|
||||||
|
`Integration tests <https://opendev.org/openstack/watcher-tempest-plugin>`__ (follows tempest cycle)
|
||||||
|
|
||||||
|
Python Watcher Client
|
||||||
|
`Command-line client and Python library <https://opendev.org/openstack/python-watcherclient>`__
|
||||||
|
|
||||||
|
Watcher Specifications
|
||||||
|
`Design specifications <https://opendev.org/openstack/watcher-specs>`__ (not released)
|
||||||
|
|
||||||
|
Watcher Launchpad (Main)
|
||||||
|
`Primary bug and feature tracking <https://launchpad.net/watcher>`__
|
||||||
|
|
||||||
|
Watcher Dashboard Launchpad
|
||||||
|
`Dashboard-specific tracking <https://launchpad.net/watcher-dashboard/>`__
|
||||||
|
|
||||||
|
Watcher Tempest Plugin Launchpad
|
||||||
|
`Test plugin tracking <https://launchpad.net/watcher-tempest-plugin>`__
|
||||||
|
|
||||||
|
Python Watcher Client Launchpad
|
||||||
|
`Client library tracking <https://launchpad.net/python-watcherclient>`__
|
||||||
|
|
||||||
|
Project Team Gathering
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
Event Liaison Coordination
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
* Work with the project team to select an event liaison for PTG coordination.
|
||||||
|
The event liaison is responsible for:
|
||||||
|
|
||||||
|
* Reserving sufficient space at PTG for the project team's meetings
|
||||||
|
* Putting out an agenda for team meetings
|
||||||
|
* Ensuring meetings are organized and facilitated
|
||||||
|
* Documenting meeting results
|
||||||
|
|
||||||
|
* If no event liaison is selected, these duties revert to the release liaison.
|
||||||
|
|
||||||
|
* Monitor for OpenStack Events team queries on the mailing list requesting
|
||||||
|
event liaison volunteers - teams not responding may lose event
|
||||||
|
representation.
|
||||||
|
|
||||||
|
PTG Planning and Execution
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
* Create PTG planning etherpad, retrospective etherpad and alert about it in
|
||||||
|
watcher meeting and dev mailing list
|
||||||
|
|
||||||
|
* Example: https://etherpad.opendev.org/p/apr2025-ptg-watcher
|
||||||
|
|
||||||
|
* Run sessions at the PTG (if no event liaison is selected)
|
||||||
|
|
||||||
|
* Do a retro of the previous cycle
|
||||||
|
|
||||||
|
* Coordinate with team to establish agreement on the agenda for this release:
|
||||||
|
|
||||||
|
Review Days Planning
|
||||||
|
Determine number of review days allocated for specs and implementation work
|
||||||
|
|
||||||
|
Freeze Dates Coordination
|
||||||
|
Define Spec approval and Feature freeze dates through team collaboration
|
||||||
|
|
||||||
|
Release Schedule Modifications
|
||||||
|
Modify the OpenStack release schedule if needed by proposing new dates
|
||||||
|
(Example: https://review.opendev.org/c/openstack/releases/+/877094)
|
||||||
|
|
||||||
|
* Discuss the implications of the `SLURP or non-SLURP`__ current release
|
||||||
|
|
||||||
|
.. __: https://governance.openstack.org/tc/resolutions/20220210-release-cadence-adjustment.html
|
||||||
|
|
||||||
|
* Sign up for group photo at the PTG (if applicable)
|
||||||
|
|
||||||
|
|
||||||
|
After PTG
|
||||||
|
---------
|
||||||
|
|
||||||
|
* Send PTG session summaries to the dev mailing list
|
||||||
|
|
||||||
|
* Add `RFE bugs`__ if you have action items that are simple to do but
|
||||||
|
without a owner yet.
|
||||||
|
|
||||||
|
* Update IRC #openstack-watcher channel topic to point to new
|
||||||
|
development-planning etherpad.
|
||||||
|
|
||||||
|
.. __: https://bugs.launchpad.net/watcher/+bugs?field.tag=rfe
|
||||||
|
|
||||||
|
A few weeks before milestone 1
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
* Plan a spec review day
|
||||||
|
|
||||||
|
* Periodically check the series goals others have proposed in the “Set series
|
||||||
|
goals” link:
|
||||||
|
|
||||||
|
* Example: https://blueprints.launchpad.net/watcher/<current-release>/+setgoals
|
||||||
|
|
||||||
|
Milestone 1
|
||||||
|
-----------
|
||||||
|
|
||||||
|
* Release watcher and python-watcherclient via the openstack/releases repo.
|
||||||
|
Watcher follows the `cycle-with-intermediary`__ release model:
|
||||||
|
|
||||||
|
.. __: https://releases.openstack.org/reference/release_models.html#cycle-with-intermediary
|
||||||
|
|
||||||
|
* Create actual releases (not just launchpad bookkeeping) at milestone points
|
||||||
|
* No launchpad milestone releases are created for intermediary releases
|
||||||
|
* When releasing the first version of a library for the cycle,
|
||||||
|
bump
|
||||||
|
the minor version to leave room for future stable branch
|
||||||
|
releases
|
||||||
|
|
||||||
|
* Release stable branches of watcher
|
||||||
|
|
||||||
|
Stable Branch Release Process
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Prepare the stable branch for evaluation:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
git checkout <stable branch>
|
||||||
|
git log --no-merges <last tag>..
|
||||||
|
|
||||||
|
Analyze commits to determine version bump according to semantic versioning.
|
||||||
|
|
||||||
|
Semantic Versioning Guidelines
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Choose version bump based on changes since last release:
|
||||||
|
|
||||||
|
Major Version (X)
|
||||||
|
Backward-incompatible changes that break existing APIs
|
||||||
|
|
||||||
|
Minor Version (Y)
|
||||||
|
New features that maintain backward compatibility
|
||||||
|
|
||||||
|
Patch Version (Z)
|
||||||
|
Bug fixes that maintain backward compatibility
|
||||||
|
|
||||||
|
Release Command Usage
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Generate the release using OpenStack tooling:
|
||||||
|
|
||||||
|
* Use the `new-release command
|
||||||
|
<https://releases.openstack.org/reference/using.html#using-new-release-command>`__
|
||||||
|
* Propose the release with version according to chosen semver format
|
||||||
|
(x.y.z)
|
||||||
|
|
||||||
|
Summit
|
||||||
|
------
|
||||||
|
|
||||||
|
``Responsibility Precedence for Summit Activities:``
|
||||||
|
|
||||||
|
1. ``Project Update/Onboarding Liaisons`` (if appointed):
|
||||||
|
|
||||||
|
* ``Project Update Liaison``: responsible for giving the project update
|
||||||
|
showcasing team's achievements for the cycle to the community
|
||||||
|
* ``Project Onboarding Liaison``: responsible for giving/facilitating
|
||||||
|
onboarding sessions during events for the project's community
|
||||||
|
|
||||||
|
2. ``Event Liaison`` (if no Project Update/Onboarding liaisons exist):
|
||||||
|
|
||||||
|
* Coordinates all Summit activities including project updates and onboarding
|
||||||
|
|
||||||
|
3. ``Release Liaison`` (if no Event Liaison is appointed):
|
||||||
|
|
||||||
|
* Work with the team to ensure Summit activities are properly handled:
|
||||||
|
|
||||||
|
* Prepare the project update presentation
|
||||||
|
* Prepare the on-boarding session materials
|
||||||
|
* Prepare the operator meet-and-greet session
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
The team can choose to not have a Summit presence if desired.
|
||||||
|
|
||||||
|
A few weeks before milestone 2
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
* Plan a spec review day (optional)
|
||||||
|
|
||||||
|
Milestone 2
|
||||||
|
-----------
|
||||||
|
|
||||||
|
* Spec freeze (unless changed by team agreement at PTG)
|
||||||
|
|
||||||
|
* Release watcher and python-watcherclient (if needed)
|
||||||
|
|
||||||
|
* Stable branch releases of watcher
|
||||||
|
|
||||||
|
|
||||||
|
Shortly after spec freeze
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
* Create a blueprint status etherpad to help track, especially non-priority
|
||||||
|
blueprint work, to help things get done by Feature Freeze (FF). Example:
|
||||||
|
|
||||||
|
* https://etherpad.opendev.org/p/watcher-<release>-blueprint-status
|
||||||
|
|
||||||
|
* Create or review a patch to add the next release’s specs directory so people
|
||||||
|
can propose specs for next release after spec freeze for current release
|
||||||
|
|
||||||
|
Milestone 3
|
||||||
|
-----------
|
||||||
|
|
||||||
|
* Feature freeze day
|
||||||
|
|
||||||
|
* Client library freeze, release python-watcherclient
|
||||||
|
|
||||||
|
* Close out all blueprints, including “catch all” blueprints like mox,
|
||||||
|
versioned notifications
|
||||||
|
|
||||||
|
* Stable branch releases of watcher
|
||||||
|
|
||||||
|
* Start writing the `cycle highlights
|
||||||
|
<https://docs.openstack.org/project-team-guide/release-management.html#cycle-highlights>`__
|
||||||
|
|
||||||
|
Week following milestone 3
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
* If warranted, announce the FFE (feature freeze exception process) to
|
||||||
|
have people propose FFE requests to a special etherpad where they will
|
||||||
|
be reviewed.
|
||||||
|
FFE requests should first be discussed in the IRC meeting with the
|
||||||
|
requester present.
|
||||||
|
The release liaison has final decision on granting exceptions.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
if there is only a short time between FF and RC1 (lately it’s been 2
|
||||||
|
weeks), then the only likely candidates will be low-risk things that are
|
||||||
|
almost done. In general Feature Freeze exceptions should not be granted,
|
||||||
|
instead features should be deferred and reproposed for the next
|
||||||
|
development
|
||||||
|
cycle. FFE never extend beyond RC1.
|
||||||
|
|
||||||
|
* Mark the max microversion for the release in the
|
||||||
|
:doc:`/contributor/api_microversion_history`
|
||||||
|
|
||||||
|
A few weeks before RC
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
* Update the release status etherpad with RC1 todos and keep track
|
||||||
|
of them in meetings
|
||||||
|
|
||||||
|
* Go through the bug list and identify any rc-potential bugs and tag them
|
||||||
|
|
||||||
|
RC
|
||||||
|
--
|
||||||
|
|
||||||
|
* Follow the standard OpenStack release checklist process
|
||||||
|
|
||||||
|
* If we want to drop backward-compat RPC code, we have to do a major RPC
|
||||||
|
version bump and coordinate it just before the major release:
|
||||||
|
|
||||||
|
* https://wiki.openstack.org/wiki/RpcMajorVersionUpdates
|
||||||
|
|
||||||
|
* Example: https://review.opendev.org/541035
|
||||||
|
|
||||||
|
* “Merge latest translations" means translation patches
|
||||||
|
|
||||||
|
* Check for translations with:
|
||||||
|
|
||||||
|
* https://review.opendev.org/#/q/status:open+project:openstack/watcher+branch:master+topic:zanata/translations
|
||||||
|
|
||||||
|
* Should NOT plan to have more than one RC if possible. RC2 should only happen
|
||||||
|
if there was a mistake and something was missed for RC, or a new regression
|
||||||
|
was discovered
|
||||||
|
|
||||||
|
* Write the reno prelude for the release GA
|
||||||
|
|
||||||
|
* Example: https://review.opendev.org/644412
|
||||||
|
|
||||||
|
* Push the cycle-highlights in marketing-friendly sentences and propose to the
|
||||||
|
openstack/releases repo. Usually based on reno prelude but made more readable
|
||||||
|
and friendly
|
||||||
|
|
||||||
|
* Example: https://review.opendev.org/644697
|
||||||
|
|
||||||
|
Immediately after RC
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
* Look for bot proposed changes to reno and stable/<cycle>
|
||||||
|
|
||||||
|
* Create the launchpad series for the next cycle
|
||||||
|
|
||||||
|
* Set the development focus of the project to the new cycle series
|
||||||
|
|
||||||
|
* Set the status of the new series to “active development”
|
||||||
|
|
||||||
|
* Set the last series status to “current stable branch release”
|
||||||
|
|
||||||
|
* Set the previous to last series status to “supported”
|
||||||
|
|
||||||
|
* Repeat launchpad steps ^ for all watcher deliverables.
|
||||||
|
|
||||||
|
* Make sure the specs directory for the next cycle gets created so people can
|
||||||
|
start proposing new specs
|
||||||
|
|
||||||
|
* Make sure to move implemented specs from the previous release
|
||||||
|
|
||||||
|
* Move implemented specs manually (TODO: add tox command in future)
|
||||||
|
|
||||||
|
* Remove template files:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
rm doc/source/specs/<release>/index.rst
|
||||||
|
rm doc/source/specs/<release>/template.rst
|
||||||
|
|
||||||
|
* Ensure liaison handoff: either transition to new release liaison or confirm
|
||||||
|
reappointment for next cycle
|
||||||
|
|
||||||
|
.. _glossary:
|
||||||
|
|
||||||
|
Glossary
|
||||||
|
--------
|
||||||
|
|
||||||
|
DPL
|
||||||
|
Distributed Project Leadership - A governance model where traditional PTL
|
||||||
|
responsibilities are distributed among various specialized liaisons.
|
||||||
|
|
||||||
|
FFE
|
||||||
|
Feature Freeze Exception - A request to add a feature after the feature
|
||||||
|
freeze deadline. Should be used sparingly for low-risk, nearly
|
||||||
|
complete features.
|
||||||
|
|
||||||
|
GA
|
||||||
|
General Availability - The final release of a software version for
|
||||||
|
production use.
|
||||||
|
|
||||||
|
PTG
|
||||||
|
Project Team Gathering - A collaborative event where OpenStack project
|
||||||
|
teams meet to plan and coordinate development activities.
|
||||||
|
|
||||||
|
RC
|
||||||
|
Release Candidate - A pre-release version that is potentially the final
|
||||||
|
version, pending testing and bug fixes.
|
||||||
|
|
||||||
|
RFE
|
||||||
|
Request for Enhancement - A type of bug report requesting a new feature
|
||||||
|
or enhancement to existing functionality.
|
||||||
|
|
||||||
|
SLURP
|
||||||
|
Skip Level Upgrade Release Process - An extended maintenance release
|
||||||
|
that allows skipping intermediate versions during upgrades.
|
||||||
|
|
||||||
|
Summit
|
||||||
|
OpenStack Summit - A conference where the OpenStack community gathers
|
||||||
|
for presentations, discussions, and project updates.
|
||||||
|
|
||||||
|
Miscellaneous Notes
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
How to track launchpad blueprint approvals
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Core team approves blueprints through team consensus. The release liaison
|
||||||
|
ensures launchpad status is updated correctly after core team approval:
|
||||||
|
|
||||||
|
* Set the approver as the core team member who approved the spec
|
||||||
|
|
||||||
|
* Set the Direction => Approved and Definition => Approved and make sure the
|
||||||
|
Series goal is set to the current release. If code is already proposed, set
|
||||||
|
Implementation => Needs Code Review
|
||||||
|
|
||||||
|
* Optional: add a comment to the Whiteboard explaining the approval,
|
||||||
|
with a date
|
||||||
|
(launchpad does not record approval dates). For example: “We discussed this
|
||||||
|
in the team meeting and agreed to approve this for <release>. -- <nick>
|
||||||
|
<YYYYMMDD>”
|
||||||
|
|
||||||
|
How to complete a launchpad blueprint
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
* Set Implementation => Implemented. The completion date will be recorded by
|
||||||
|
launchpad
|
||||||
Reference in New Issue
Block a user