diff options
Diffstat (limited to 'doc/source/contributor')
| -rw-r--r-- | doc/source/contributor/api-2.rst | 56 | ||||
| -rw-r--r-- | doc/source/contributor/api-ref-guideline.rst | 2 | ||||
| -rw-r--r-- | doc/source/contributor/api.rst | 112 | ||||
| -rw-r--r-- | doc/source/contributor/development-environment.rst | 2 | ||||
| -rw-r--r-- | doc/source/contributor/how-to-get-involved.rst | 4 | ||||
| -rw-r--r-- | doc/source/contributor/index.rst | 21 | ||||
| -rw-r--r-- | doc/source/contributor/notifications.rst | 272 | ||||
| -rw-r--r-- | doc/source/contributor/process.rst | 10 | ||||
| -rw-r--r-- | doc/source/contributor/ptl-guide.rst | 78 |
9 files changed, 395 insertions, 162 deletions
diff --git a/doc/source/contributor/api-2.rst b/doc/source/contributor/api-2.rst deleted file mode 100644 index a5bf639f81..0000000000 --- a/doc/source/contributor/api-2.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. - Copyright 2010-2011 OpenStack Foundation - All Rights Reserved. - - 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. - -.. TODO:: - - This should be merged into contributor/api - -Adding a Method to the OpenStack API -==================================== - -The interface is a mostly RESTful API. REST stands for Representational State Transfer and provides an architecture "style" for distributed systems using HTTP for transport. Figure out a way to express your request and response in terms of resources that are being created, modified, read, or destroyed. - -Routing -------- - -To map URLs to controllers+actions, OpenStack uses the Routes package, a clone of Rails routes for Python implementations. See http://routes.readthedocs.io/en/latest/ for more information. - -URLs are mapped to "action" methods on "controller" classes in ``nova/api/openstack/__init__/ApiRouter.__init__`` . - -See http://routes.readthedocs.io/en/latest/modules/mapper.html for all syntax, but you'll probably just need these two: - - mapper.connect() lets you map a single URL to a single action on a controller. - - mapper.resource() connects many standard URLs to actions on a controller. - -Controllers and actions ------------------------ - -Controllers live in ``nova/api/openstack``, and inherit from nova.wsgi.Controller. - -See ``nova/api/openstack/compute/servers.py`` for an example. - -Action methods take parameters that are sucked out of the URL by mapper.connect() or .resource(). The first two parameters are self and the WebOb request, from which you can get the req.environ, req.body, req.headers, etc. - -Serialization -------------- - -Actions return a dictionary, and wsgi.Controller serializes that to JSON. - -Faults ------- - -If you need to return a non-200, you should -return faults.Fault(webob.exc.HTTPNotFound()) -replacing the exception as appropriate. diff --git a/doc/source/contributor/api-ref-guideline.rst b/doc/source/contributor/api-ref-guideline.rst index cc5eab2538..0aec4eeeb4 100644 --- a/doc/source/contributor/api-ref-guideline.rst +++ b/doc/source/contributor/api-ref-guideline.rst @@ -351,7 +351,7 @@ In the parameter file, define the ``required`` field in each parameter. but does not appear when non-admin users call. If a parameter must be specified in the request or always appears -in the response in the micoversion added or later, +in the response in the microversion added or later, the parameter must be defined as required (``true``). Microversion diff --git a/doc/source/contributor/api.rst b/doc/source/contributor/api.rst index 2371990147..2e9cea3300 100644 --- a/doc/source/contributor/api.rst +++ b/doc/source/contributor/api.rst @@ -1,23 +1,38 @@ Extending the API ================= -Background ----------- +.. note:: -Nova has v2.1 API frameworks which supports microversions. + This document provides general background information on how one can extend + the REST API in nova. For information on the microversion support including + how to add new microversions, see :doc:`/contributor/microversions`. For + information on how to use the API, refer to the `API guide`__ and `API + reference guide`__. + + .. __: https://docs.openstack.org/api-guide/compute/ + .. __: https://docs.openstack.org/api-ref/compute/ + +Nova's API is a mostly RESTful API. REST stands for *Representational State +Transfer* and provides an architecture "style" for distributed systems using +HTTP for transport. Figure out a way to express your request and response in +terms of resources that are being created, modified, read, or destroyed. +Nova has v2.1 API frameworks which supports microversions. This document covers how to add API for the v2.1 API framework. A -:doc:`microversions specific document <microversions>` covers the details +:doc:`microversions-specific document <microversions>` covers the details around what is required for the microversions part. The v2.1 API framework is under ``nova/api`` and each API is implemented in ``nova/api/openstack/compute``. -Note that any change to the Nova API to be merged will first require a -spec be approved first. See `here <https://opendev.org/openstack/nova-specs>`_ -for the appropriate repository. For guidance on the design of the API -please refer to the `OpenStack API WG -<https://wiki.openstack.org/wiki/API_Working_Group>`_ +.. note:: + + Any change to the Nova API to be merged will first require a spec be + approved first. + See `here <https://opendev.org/openstack/nova-specs>`_ for the appropriate + repository. + For guidance on the design of the API please refer to the `OpenStack API WG + <https://wiki.openstack.org/wiki/API_Working_Group>`_ Basic API Controller @@ -25,7 +40,9 @@ Basic API Controller API controller includes the implementation of API methods for a resource. -A very basic controller of a v2.1 API:: +A very basic controller of a v2.1 API: + +.. code-block:: python """Basic Controller""" @@ -51,6 +68,8 @@ A very basic controller of a v2.1 API:: # Defining support for other RESTFul methods based on resource. + # ... + See `servers.py <https://opendev.org/openstack/nova/src/branch/master/nova/api/openstack/compute/servers.py>`_ for ref. @@ -63,7 +82,9 @@ The URL mapping is based on the plain list which routes the API request to appropriate controller and method. Each API needs to add its route information in ``nova/api/openstack/compute/routes.py``. -A basic skeleton of URL mapping in routers.py:: +A basic skeleton of URL mapping in ``routers.py``: + +.. code-block:: python """URL Mapping Router List""" @@ -74,7 +95,8 @@ A basic skeleton of URL mapping in routers.py:: # Create a controller object basic_controller = functools.partial( - _create_controller, basic_api.BasicController, [], []) + _create_controller, basic_api.BasicController, [], [], + ) # Routing list structure: # ( @@ -88,20 +110,16 @@ A basic skeleton of URL mapping in routers.py:: # ... # ) ROUTE_LIST = ( - . - . - . + # ... ('/basic', { 'GET': [basic_controller, 'index'], 'POST': [basic_controller, 'create'] }), - . - . - . + # ... ) -Complete routing list can be found in `routes.py <https://opendev.org/openstack/nova/src/branch/master/nova/api/openstack/compute/routes.py>`_. - +Complete routing list can be found in `routes.py +<https://opendev.org/openstack/nova/src/branch/master/nova/api/openstack/compute/routes.py>`_. Policy ~~~~~~ @@ -113,7 +131,7 @@ Modularity ~~~~~~~~~~ The Nova REST API is separated into different controllers in the directory -'nova/api/openstack/compute/' +``nova/api/openstack/compute/``. Because microversions are supported in the Nova REST API, the API can be extended without any new controller. But for code readability, the Nova REST API @@ -140,39 +158,13 @@ JSON-Schema The v2.1 API validates a REST request body with JSON-Schema library. Valid body formats are defined with JSON-Schema in the directory -'nova/api/openstack/compute/schemas'. Each definition is used at the -corresponding method with the ``validation.schema`` decorator like:: - - @validation.schema(schema.update_something) - def update(self, req, id, body): - .... - -Similarly to controller modularity, JSON-Schema definitions can be added -in same or separate JSON-Schema module. +``nova/api/openstack/compute/schemas``. Each definition is used at the +corresponding method with the ``validation.schema`` decorator like: -The following are the combinations of extensible API and method name -which returns additional JSON-Schema parameters: +.. code-block:: python -* Create a server API - get_server_create_schema() - -For example, keypairs extension(Keypairs class) contains the method -get_server_create_schema() which returns:: - - { - 'key_name': parameter_types.name, - } - -then the parameter key_name is allowed on Create a server API. - -.. note:: Currently only create schema are implemented in modular way. - Final goal is to merge them all and define the concluded - process in this doc. - -These are essentially hooks into the servers controller which allow other -controller to modify behaviour without having to modify servers.py. In -the past not having this capability led to very large chunks of -unrelated code being added to servers.py which was difficult to -maintain. + @validation.schema(schema.update_something) + def update(self, req, id, body): Unit Tests @@ -187,7 +179,7 @@ Negative tests would include such things as: * Request schema validation failures, for both the request body and query parameters -* HTTPNotFound or other >=400 response code failures +* ``HTTPNotFound`` or other >=400 response code failures Functional tests and API Samples @@ -203,6 +195,7 @@ The API samples tests are made of two parts: ``doc/api_samples/``. There is typically one directory per API controller with subdirectories per microversion for that API controller. The unversioned samples are used for the base v2.0 / v2.1 APIs. + * Corresponding API sample templates found under path ``nova/tests/functional/api_sample_tests/api_samples``. These have a similar structure to the API reference docs samples, except the format of the sample @@ -220,7 +213,7 @@ need to be made. Note that it is possible to automatically generate the API reference doc samples using the templates by simply running the tests using -``tox -r -e api-samples``. This relies, of course, upon the test and templates +``tox -e api-samples``. This relies, of course, upon the test and templates being correct for the test to pass, which may take some iteration. In general, if you are adding a new microversion to an existing API controller, @@ -228,7 +221,7 @@ it is easiest to simply copy an existing test and modify it for the new microversion and the new samples/templates. The functional API samples tests are not the simplest thing in the world to -get used to, and can be very frustrating at times when they fail in not +get used to and it can be very frustrating at times when they fail in not obvious ways. If you need help debugging a functional API sample test failure, feel free to post your work-in-progress change for review and ask for help in the ``openstack-nova`` OFTC IRC channel. @@ -270,11 +263,13 @@ The general steps for deprecating a REST API are: * Set a maximum allowed microversion for the route. Requests beyond that microversion on that route will result in a ``404 HTTPNotFound`` error. + * Update the Compute API reference documentation to indicate the route is deprecated and move it to the bottom of the list with the other deprecated APIs. + * Deprecate, and eventually remove, related CLI / SDK functionality in other - projects like python-novaclient. + projects like *python-novaclient*. Removing deprecated APIs @@ -294,15 +289,20 @@ The general steps for removing support for a deprecated REST API are: microversion that does not support a deprecated API. 410 means the resource is gone and not coming back, which is more appropriate when the API is fully removed and will not work at any microversion. + * Related configuration options, policy rules, and schema validation are removed. + * The API reference documentation should be updated to move the documentation for the removed API to the `Obsolete APIs`_ section and mention in which release the API was removed. + * Unit tests can be removed. + * API sample functional tests can be changed to assert the 410 response behavior, but can otherwise be mostly gutted. Related \*.tpl files for the API sample functional tests can be deleted since they will not be used. + * An "upgrade" :doc:`release note <releasenotes>` should be added to mention the REST API routes that were removed along with any related configuration options that were also removed. diff --git a/doc/source/contributor/development-environment.rst b/doc/source/contributor/development-environment.rst index 32b8f8334e..3e19ef1ca2 100644 --- a/doc/source/contributor/development-environment.rst +++ b/doc/source/contributor/development-environment.rst @@ -197,7 +197,7 @@ Using fake computes for tests The number of instances supported by fake computes is not limited by physical constraints. It allows you to perform stress tests on a deployment with few resources (typically a laptop). Take care to avoid using scheduler filters -that will limit the number of instances per compute, such as ``AggregateCoreFilter``. +that will limit the number of instances per compute, such as ``NumInstancesFilter``. Fake computes can also be used in multi hypervisor-type deployments in order to take advantage of fake and "real" computes during tests: diff --git a/doc/source/contributor/how-to-get-involved.rst b/doc/source/contributor/how-to-get-involved.rst index dcf869bad7..28e75564b0 100644 --- a/doc/source/contributor/how-to-get-involved.rst +++ b/doc/source/contributor/how-to-get-involved.rst @@ -261,7 +261,7 @@ reviews: - Where do I start? What should I review? - There are various tools, but a good place to start is: - https://etherpad.openstack.org/p/nova-runways-yoga + https://review.opendev.org/q/project:openstack/nova+status:open+label:Review-Priority%253DANY - Depending on the time in the cycle, it's worth looking at NeedsCodeReview blueprints: https://blueprints.launchpad.net/nova/ @@ -323,7 +323,7 @@ becoming a member of nova-core. How to do great nova-spec reviews? ================================== -https://specs.openstack.org/openstack/nova-specs/specs/yoga/template.html +https://specs.openstack.org/openstack/nova-specs/specs/2023.1/template.html :doc:`/contributor/blueprints`. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 2889199147..5b6e0b8f92 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -22,7 +22,7 @@ Getting Started * :doc:`/contributor/development-environment`: Get your computer setup to contribute -.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to +.. # NOTE(amotoki): toctree needs to be placed at the end of the section to # keep the document structure in the PDF doc. .. toctree:: :hidden: @@ -60,7 +60,7 @@ while keeping users happy and keeping developers productive. * :doc:`/contributor/ptl-guide`: A chronological PTL reference guide -.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to +.. # NOTE(amotoki): toctree needs to be placed at the end of the section to # keep the document structure in the PDF doc. .. toctree:: :hidden: @@ -86,7 +86,7 @@ Reviewing * :doc:`/contributor/documentation`: Guidelines for handling documentation contributions -.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to +.. # NOTE(amotoki): toctree needs to be placed at the end of the section to # keep the document structure in the PDF doc. .. toctree:: :hidden: @@ -120,7 +120,7 @@ be Python code. All new code needs to be validated somehow. * :doc:`/contributor/testing/eventlet-profiling` -.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to +.. # NOTE(amotoki): toctree needs to be placed at the end of the section to # keep the document structure in the PDF doc. .. toctree:: :hidden: @@ -140,8 +140,6 @@ changes done to the API, as the impact can be very wide. * :doc:`/contributor/api`: How the code is structured inside the API layer -* :doc:`/contributor/api-2`: (needs update) - * :doc:`/contributor/microversions`: How the API is (micro)versioned and what you need to do when adding an API exposed feature that needs a new microversion. @@ -149,15 +147,20 @@ changes done to the API, as the impact can be very wide. * :doc:`/contributor/api-ref-guideline`: The guideline to write the API reference. -.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to +Nova also provides notifications over the RPC API, which you may wish to +extend. + +* :doc:`/contributor/notifications`: How to add your own notifications + +.. # NOTE(amotoki): toctree needs to be placed at the end of the section to # keep the document structure in the PDF doc. .. toctree:: :hidden: api - api-2 microversions api-ref-guideline + notifications Nova Major Subsystems ===================== @@ -173,7 +176,7 @@ diving in. * :doc:`/contributor/resize-and-cold-migrate`: Describes the differences and similarities between resize and cold migrate operations. -.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to +.. # NOTE(amotoki): toctree needs to be placed at the end of the section to # keep the document structure in the PDF doc. .. toctree:: :hidden: diff --git a/doc/source/contributor/notifications.rst b/doc/source/contributor/notifications.rst new file mode 100644 index 0000000000..d94051a2e5 --- /dev/null +++ b/doc/source/contributor/notifications.rst @@ -0,0 +1,272 @@ +============= +Notifications +============= + +As discussed in :doc:`/admin/notifications`, nova emits notifications to the +message bus. There are two types of notifications provided in nova: legacy +(unversioned) notifications and versioned notifications. As a developer, you +may choose to add additional notifications or extend existing notifications. + +.. note:: + + This section provides information on adding your own notifications in nova. + For background information on notifications including usage information, + refer to :doc:`/admin/notifications`. + For a list of available versioned notifications, refer to + :doc:`/reference/notifications`. + + +How to add a new versioned notification +--------------------------------------- + +To provide the versioning for versioned notifications, each notification +is modeled with oslo.versionedobjects. Every versioned notification class +shall inherit from the ``nova.notifications.objects.base.NotificationBase`` +which already defines three mandatory fields of the notification +``event_type``, ``publisher`` and ``priority``. The new notification class +shall add a new field ``payload`` with an appropriate payload type. The payload +object of the notifications shall inherit from the +``nova.notifications.objects.base.NotificationPayloadBase`` class and shall +define the fields of the payload as versionedobject fields. The base classes +are described in the following section. + +.. rubric:: The ``nova.notifications.objects.base`` module + +.. automodule:: nova.notifications.objects.base + :noindex: + :members: + :show-inheritance: + +Note that the notification objects must not be registered to the +``NovaObjectRegistry`` to avoid mixing nova-internal objects with the +notification objects. Instead, use the ``register_notification`` decorator on +every concrete notification object. + +The following code example defines the necessary model classes for a new +notification ``myobject.update``. + +.. code-block:: python + + @notification.notification_sample('myobject-update.json') + @object_base.NovaObjectRegistry.register.register_notification + class MyObjectNotification(notification.NotificationBase): + # Version 1.0: Initial version + VERSION = '1.0' + + fields = { + 'payload': fields.ObjectField('MyObjectUpdatePayload') + } + + + @object_base.NovaObjectRegistry.register.register_notification + class MyObjectUpdatePayload(notification.NotificationPayloadBase): + # Version 1.0: Initial version + VERSION = '1.0' + fields = { + 'some_data': fields.StringField(), + 'another_data': fields.StringField(), + } + + +After that the notification can be populated and emitted with the following +code. + +.. code-block:: python + + payload = MyObjectUpdatePayload(some_data="foo", another_data="bar") + MyObjectNotification( + publisher=notification.NotificationPublisher.from_service_obj( + <nova.objects.service.Service instance that emits the notification>), + event_type=notification.EventType( + object='myobject', + action=fields.NotificationAction.UPDATE), + priority=fields.NotificationPriority.INFO, + payload=payload).emit(context) + +The above code will generate the following notification on the wire. + +.. code-block:: json + + { + "priority":"INFO", + "payload":{ + "nova_object.namespace":"nova", + "nova_object.name":"MyObjectUpdatePayload", + "nova_object.version":"1.0", + "nova_object.data":{ + "some_data":"foo", + "another_data":"bar", + } + }, + "event_type":"myobject.update", + "publisher_id":"<the name of the service>:<the host where the service runs>" + } + + +There is a possibility to reuse an existing versionedobject as notification +payload by adding a ``SCHEMA`` field for the payload class that defines a +mapping between the fields of existing objects and the fields of the new +payload object. For example the service.status notification reuses the existing +``nova.objects.service.Service`` object when defines the notification's +payload. + +.. code-block:: python + + @notification.notification_sample('service-update.json') + @object_base.NovaObjectRegistry.register.register_notification + class ServiceStatusNotification(notification.NotificationBase): + # Version 1.0: Initial version + VERSION = '1.0' + + fields = { + 'payload': fields.ObjectField('ServiceStatusPayload') + } + + @object_base.NovaObjectRegistry.register.register_notification + class ServiceStatusPayload(notification.NotificationPayloadBase): + SCHEMA = { + 'host': ('service', 'host'), + 'binary': ('service', 'binary'), + 'topic': ('service', 'topic'), + 'report_count': ('service', 'report_count'), + 'disabled': ('service', 'disabled'), + 'disabled_reason': ('service', 'disabled_reason'), + 'availability_zone': ('service', 'availability_zone'), + 'last_seen_up': ('service', 'last_seen_up'), + 'forced_down': ('service', 'forced_down'), + 'version': ('service', 'version') + } + # Version 1.0: Initial version + VERSION = '1.0' + fields = { + 'host': fields.StringField(nullable=True), + 'binary': fields.StringField(nullable=True), + 'topic': fields.StringField(nullable=True), + 'report_count': fields.IntegerField(), + 'disabled': fields.BooleanField(), + 'disabled_reason': fields.StringField(nullable=True), + 'availability_zone': fields.StringField(nullable=True), + 'last_seen_up': fields.DateTimeField(nullable=True), + 'forced_down': fields.BooleanField(), + 'version': fields.IntegerField(), + } + + def populate_schema(self, service): + super(ServiceStatusPayload, self).populate_schema(service=service) + +If the ``SCHEMA`` field is defined then the payload object needs to be +populated with the ``populate_schema`` call before it can be emitted. + +.. code-block:: python + + payload = ServiceStatusPayload() + payload.populate_schema(service=<nova.object.service.Service object>) + ServiceStatusNotification( + publisher=notification.NotificationPublisher.from_service_obj( + <nova.object.service.Service object>), + event_type=notification.EventType( + object='service', + action=fields.NotificationAction.UPDATE), + priority=fields.NotificationPriority.INFO, + payload=payload).emit(context) + +The above code will emit the :ref:`already shown notification <service.update>` +on the wire. + +Every item in the ``SCHEMA`` has the syntax of:: + + <payload field name which needs to be filled>: + (<name of the parameter of the populate_schema call>, + <the name of a field of the parameter object>) + +The mapping defined in the ``SCHEMA`` field has the following semantics. When +the ``populate_schema`` function is called the content of the ``SCHEMA`` field +is enumerated and the value of the field of the pointed parameter object is +copied to the requested payload field. So in the above example the ``host`` +field of the payload object is populated from the value of the ``host`` field +of the ``service`` object that is passed as a parameter to the +``populate_schema`` call. + +A notification payload object can reuse fields from multiple existing +objects. Also a notification can have both new and reused fields in its +payload. + +Note that the notification's publisher instance can be created two different +ways. It can be created by instantiating the ``NotificationPublisher`` object +with a ``host`` and a ``source`` string parameter or it can be generated from a +``Service`` object by calling ``NotificationPublisher.from_service_obj`` +function. + +Versioned notifications shall have a sample file stored under +``doc/sample_notifications`` directory and the notification object shall be +decorated with the ``notification_sample`` decorator. For example the +``service.update`` notification has a sample file stored in +``doc/sample_notifications/service-update.json`` and the +``ServiceUpdateNotification`` class is decorated accordingly. + +Notification payload classes can use inheritance to avoid duplicating common +payload fragments in nova code. However the leaf classes used directly in a +notification should be created with care to avoid future needs of adding extra +level of inheritance that changes the name of the leaf class as that name is +present in the payload class. If this cannot be avoided and the only change is +the renaming then the version of the new payload shall be the same as the old +payload was before the rename. See [1]_ as an example. If the renaming +involves any other changes on the payload (e.g. adding new fields) then the +version of the new payload shall be higher than the old payload was. See [2]_ +as an example. + + +What should be in the notification payload? +------------------------------------------- + +This is just a guideline. You should always consider the actual use case that +requires the notification. + +* Always include the identifier (e.g. uuid) of the entity that can be used to + query the whole entity over the REST API so that the consumer can get more + information about the entity. + +* You should consider including those fields that are related to the event + you are sending the notification about. For example if a change of a field of + the entity triggers an update notification then you should include the field + to the payload. + +* An update notification should contain information about what part of the + entity is changed. Either by filling the nova_object.changes part of the + payload (note that it is not supported by the notification framework + currently) or sending both the old state and the new state of the entity in + the payload. + +* You should never include a nova internal object in the payload. Create a new + object and use the SCHEMA field to map the internal object to the + notification payload. This way the evolution of the internal object model + can be decoupled from the evolution of the notification payload. + + .. important:: + + This does not mean that every field from internal objects + should be mirrored in the notification payload objects. + Think about what is actually needed by a consumer before + adding it to a payload. When in doubt, if no one is requesting + specific information in notifications, then leave it out until + someone asks for it. + +* The delete notification should contain the same information as the create or + update notifications. This makes it possible for the consumer to listen only to + the delete notifications but still filter on some fields of the entity + (e.g. project_id). + + +What should **NOT** be in the notification payload +-------------------------------------------------- + +* Generally anything that contains sensitive information about the internals + of the nova deployment, for example fields that contain access credentials + to a cell database or message queue (see `bug 1823104`_). + +.. _bug 1823104: https://bugs.launchpad.net/nova/+bug/1823104 + +.. references: + +.. [1] https://review.opendev.org/#/c/463001/ +.. [2] https://review.opendev.org/#/c/453077/ diff --git a/doc/source/contributor/process.rst b/doc/source/contributor/process.rst index 2ee2e2fa6f..f1be1c1b4a 100644 --- a/doc/source/contributor/process.rst +++ b/doc/source/contributor/process.rst @@ -36,8 +36,8 @@ If you are new to Nova, please read this first: :ref:`getting_involved`. Dates overview ============== -For Yoga, please see: -https://wiki.openstack.org/wiki/Nova/Yoga_Release_Schedule +For 2023.1 Antelope, please see: +https://wiki.openstack.org/wiki/Nova/2023.1_Release_Schedule .. note:: Throughout this document any link which references the name of a release cycle in the link can usually be changed to the name of the @@ -102,9 +102,9 @@ Why we have a Spec Freeze: By the freeze date, we expect all blueprints that will be approved for the cycle to be listed on launchpad and all relevant specs to be merged. -For Yoga, blueprints can be found at -https://blueprints.launchpad.net/nova/yoga and specs at -https://specs.openstack.org/openstack/nova-specs/specs/yoga/index.html +For 2023.1 Antelope, blueprints can be found at +https://blueprints.launchpad.net/nova/antelope and specs at +https://specs.openstack.org/openstack/nova-specs/specs/2023.1/index.html Starting with Liberty, we are keeping a backlog open for submission at all times. diff --git a/doc/source/contributor/ptl-guide.rst b/doc/source/contributor/ptl-guide.rst index d12e1beeb0..b530b100bc 100644 --- a/doc/source/contributor/ptl-guide.rst +++ b/doc/source/contributor/ptl-guide.rst @@ -29,7 +29,11 @@ New PTL * Get acquainted with the release schedule - * Example: https://wiki.openstack.org/wiki/Nova/Stein_Release_Schedule + * Example: https://releases.openstack.org/antelope/schedule.html + + * Also, note that we usually create a specific wiki page for each cycle like + https://wiki.openstack.org/wiki/Nova/2023.1_Release_Schedule but it's + preferred to use the main release schedule above. Project Team Gathering ---------------------- @@ -37,30 +41,34 @@ Project Team Gathering * Create PTG planning etherpad, retrospective etherpad and alert about it in nova meeting and dev mailing list - * Example: https://etherpad.openstack.org/p/nova-ptg-stein + * Example: https://etherpad.opendev.org/p/nova-antelope-ptg * Run sessions at the PTG -* Have a priorities discussion at the PTG +* Do a retro of the previous cycle - * Example: https://etherpad.openstack.org/p/nova-ptg-stein-priorities +* Make agreement on the agenda for this release, including but not exhaustively: -* Sign up for group photo at the PTG (if applicable) + * Number of review days, for either specs or implementation + * Define the Spec approval and Feature freeze dates + * Modify the release schedule if needed by adding the new dates. + As an 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 -* Open review runways for the cycle +* Sign up for group photo at the PTG (if applicable) - * Example: https://etherpad.openstack.org/p/nova-runways-stein After PTG --------- * Send PTG session summaries to the dev mailing list -* Make sure the cycle priorities spec gets reviewed and merged - - * Example: https://specs.openstack.org/openstack/nova-specs/priorities/stein-priorities.html +* Add `RFE bugs`__ if you have action items that are simple to do but without a owner yet. -* Run the count-blueprints script daily to gather data for the cycle burndown chart +.. __: https://bugs.launchpad.net/nova/+bugs?field.tag=rfe A few weeks before milestone 1 ------------------------------ @@ -70,12 +78,13 @@ A few weeks before milestone 1 * Periodically check the series goals others have proposed in the “Set series goals” link: - * Example: https://blueprints.launchpad.net/nova/stein/+setgoals + * Example: https://blueprints.launchpad.net/nova/antelope/+setgoals Milestone 1 ----------- -* Do milestone release of nova and python-novaclient (in launchpad only) +* Do milestone release of nova and python-novaclient (in launchpad only, can be + optional) * This is launchpad bookkeeping only. With the latest release team changes, projects no longer do milestone releases. See: https://releases.openstack.org/reference/release_models.html#cycle-with-milestones-legacy @@ -87,6 +96,8 @@ Milestone 1 the minor version to leave room for future stable branch releases * os-vif + * placement + * os-traits / os-resource-classes * Release stable branches of nova @@ -117,28 +128,26 @@ Summit * Prepare the on-boarding session materials. Enlist help of others +* Prepare the operator meet-and-greet session. Enlist help of others + A few weeks before milestone 2 ------------------------------ * Plan a spec review day (optional) -* Periodically check the series goals others have proposed in the “Set series - goals” link: - - * Example: https://blueprints.launchpad.net/nova/stein/+setgoals - Milestone 2 ----------- -* Spec freeze +* Spec freeze (if agreed) -* Release nova and python-novaclient +* Release nova and python-novaclient (if new features were merged) * Release other libraries as needed * Stable branch releases of nova * For nova, set the launchpad milestone release as “released” with the date + (can be optional) Shortly after spec freeze ------------------------- @@ -146,7 +155,7 @@ 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.openstack.org/p/nova-stein-blueprint-status + * https://etherpad.opendev.org/p/nova-antelope-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 @@ -155,13 +164,15 @@ Non-client library release freeze --------------------------------- * Final release for os-vif +* Final release for os-traits +* Final release for os-resource-classes Milestone 3 ----------- * Feature freeze day -* Client library freeze, release python-novaclient +* Client library freeze, release python-novaclient and osc-placement * Close out all blueprints, including “catch all” blueprints like mox, versioned notifications @@ -170,6 +181,9 @@ Milestone 3 * For nova, set the launchpad milestone release as “released” with the date +* Start writing the `cycle highlights + <https://docs.openstack.org/project-team-guide/release-management.html#cycle-highlights>`__ + Week following milestone 3 -------------------------- @@ -196,7 +210,7 @@ A few weeks before RC * Make a RC1 todos etherpad and tag bugs as ``<release>-rc-potential`` and keep track of them, example: - * https://etherpad.openstack.org/p/nova-stein-rc-potential + * https://etherpad.opendev.org/p/nova-antelope-rc-potential * Go through the bug list and identify any rc-potential bugs and tag them @@ -239,7 +253,7 @@ RC * Example: https://review.opendev.org/644412 -* Write the cycle-highlights in marketing-friendly sentences and propose to the +* 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 @@ -254,15 +268,13 @@ Immediately after RC * https://wiki.openstack.org/wiki/Nova/ReleaseChecklist - * Add database migration placeholders - - * Example: https://review.opendev.org/650964 - - * Drop old RPC compat code (if there was a RPC major version bump) + * Drop old RPC compat code (if there was a RPC major version bump and if + agreed on at the PTG) * Example: https://review.opendev.org/543580 - * Bump the oldest supported compute service version + * Bump the oldest supported compute service version (if master branch is now + on a non-SLURP version) * https://review.opendev.org/#/c/738482/ @@ -276,7 +288,9 @@ Immediately after RC * Set the previous to last series status to “supported” -* Repeat launchpad steps ^ for python-novaclient +* Repeat launchpad steps ^ for python-novaclient (optional) + +* Repeat launchpad steps ^ for placement * Register milestones in launchpad for the new cycle based on the new cycle release schedule @@ -294,7 +308,7 @@ Immediately after RC * Create new release wiki: - * Example: https://wiki.openstack.org/wiki/Nova/Train_Release_Schedule + * Example: https://wiki.openstack.org/wiki/Nova/2023.1_Release_Schedule * Update the contributor guide for the new cycle |