diff --git a/doc/source/contributor/addmethod.openstackapi.rst b/doc/source/contributor/addmethod.openstackapi.rst index 4d09651405..f0d2a5ed9b 100644 --- a/doc/source/contributor/addmethod.openstackapi.rst +++ b/doc/source/contributor/addmethod.openstackapi.rst @@ -14,6 +14,8 @@ License for the specific language governing permissions and limitations under the License. +.. _adding-a-new-api: + Adding a Method to the OpenStack Manila API =========================================== diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst index 1b88772b90..109ec86a3a 100644 --- a/doc/source/contributor/contributing.rst +++ b/doc/source/contributor/contributing.rst @@ -174,6 +174,8 @@ If you'd like to propose a new feature, do so by `creating a blueprint on Launchpad. `_ For significant changes we might require a design specification. +.. _features-that-require-spefication: + Feature changes that need a specification include: -------------------------------------------------- diff --git a/doc/source/contributor/development-environment-devstack.rst b/doc/source/contributor/development-environment-devstack.rst index 03b8f1bd61..81e4e221a3 100644 --- a/doc/source/contributor/development-environment-devstack.rst +++ b/doc/source/contributor/development-environment-devstack.rst @@ -12,6 +12,8 @@ License for the specific language governing permissions and limitations under the License. +.. _setting-up-manila-devstack: + Setting up a development environment with devstack ================================================== diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 0bc2c636b3..ac0bb14365 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -35,6 +35,7 @@ Programming HowTos and Tutorials .. toctree:: :maxdepth: 3 + new_feature_workflow development.environment development-environment-devstack apache-httpd diff --git a/doc/source/contributor/new_feature_workflow.rst b/doc/source/contributor/new_feature_workflow.rst new file mode 100644 index 0000000000..b356da55fc --- /dev/null +++ b/doc/source/contributor/new_feature_workflow.rst @@ -0,0 +1,217 @@ +.. + Copyright 2023 Red Hat, Inc. + 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. + +Proposing new features +====================== + +Planning and working on new features is a hard task. This documentation +suggests a workflow and highlights what is expected, suggested and +required when working on new features in the OpenStack Manila project. + +Planning the feature +~~~~~~~~~~~~~~~~~~~~ + +Features should always start with planning. It is important to start by +discussing the problems and possible solutions with the community, bringing up +the use cases it will cover, corner cases and alternative approaches, +so we suggest the following process: + +Registering a blueprint +----------------------- + +When starting a new feature, you should file a blueprint in the +OpenStack Manila `Launchpad tracker `_. +This blueprint should have a brief description of the feature, and it will be +used to track all changes proposed to the implementation, including the Manila +core changes, functional tests and the OpenStack client changes. One example +blueprint would be the share server migration +`blueprint `_. + +Discussing the feature during the PTG +------------------------------------- + +The OpenStack PTG is a very good timing to discuss new features, as the +upstream community is focused on planning and shaping the upcoming release. +So it is encouraged that you host a topic during the PTG to talk about the +design of the feature and have the community helping you shape it. + +In case you missed the PTG deadline to bring up such features, you can also +add a topic to the Manila community weekly IRC meeting +`agenda `_ and +request feedback from the community. + +As a result, you can get different perspectives on the design of the feature +and raise awareness, so there are no surprises when the feature is being +proposed. + +One other outcome of this discussion is determining the necessity of a +specification. The community will use +:ref:`pre-defined ` factors to decide if you +need a specification or not. + +Writing a specification +----------------------- + +After determining if a specification is necessary for your proposed feature, +you will need to write in more details about the problem you are trying to +solve, the use cases and all the impact this change will have in terms of API +changes, database, security and other aspects. The specification will be +reviewed by different people, and this process is crucial for hashing out +details. Please check the OpenStack Manila +`example specification `_ +and follow its guidelines. If you are working on a smaller feature, you may +submit a "lite spec". Please follow +`this example `_. + + +Working on the implementation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is when the coding happens. You will work on the feature and the code +you write must follow the OpenStack coding +`guidelines `_. +You can find examples of database migrations, driver implementations, +RPC APIs and many other changes in the Manila code base. As our code has been +worked on and improved over the years, there is a high chance that someone else +implemented something similar to what you are doing now, so keeping the +consistency with feature implementation is very important. + +In case you are making changes to the API or adding new APIs, please +read the :ref:`Manila API contributor docs `. + +Development environment +----------------------- + +So you have worked on your changes and would like to test them? +:ref:`Devstack ` is likely the easiest way to go. +With devstack, you can have OpenStack installed quickly. You can chose to +install it using the Manila Dummy Driver or another backend driver of your +choice. + +SDK and OpenStack client +------------------------ + +If the feature changes the Manila API, please ensure that support these changes +through the SDK bindings and OpenStack client in the +`python-manilaclient repository `_. + +Unit tests +---------- + +All new changes you implement must be covered by unit tests. We have a Zuul job +that will always check the coverage percentage of the changes and the reviewers +will also be actively looking at it. + +.. important:: + + Please :ref:`run the unit tests locally ` to ensure + that your tests are passing before submitting them to the upstream gerrit. + +Tempest tests +------------- + +All API changes must be tested with negative and positive tests within the +`manila-tempest-plugin repository `_. +You can use your development environment to +:ref:`run such tests `, and ensure your changes +don't break existing functional tests. + +Documenting your work +--------------------- + +:ref:`Documenting your work ` is very important. `API +documentation `_ +and make changes where necessary. Also, you must include a release notes with +your change. On devstack you may use `tox -e reno new insert-title-here` to +generate a release note." + +Collaborative review sessions +----------------------------- + +`Collaborative review sessions `_ +are a good way to speed up the review process. It is encouraged that you +propose one as early as possible. In the session, you can walk through the key +aspects of the changes you are working on and explain some decisions you took +during the implementation. It has proven to be very valuable to both change +owners and reviewers. To schedule, please bring it up during the Manila +upstream weekly meeting or send an email using the manila tag to OpenStack +discuss mailing list. + +Complying to the deadlines +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The deadlines are defined in the official +`OpenStack release schedule `_. The +Manila team also defines some extra project specific deadlines. Below, we have +specified what is expected from you in each of these deadlines. + +Manila spec freeze +------------------ + +All specifications must be merged prior to this date. + +Manila feature proposal freeze +------------------------------ + +New features must be submitted to gerrit before this deadline. The core, +client and tempest changes must be available on gerrit, but it does not mean +the changes should be merged by this deadline. + +Manila new driver deadline +-------------------------- + +By the end of the week all new backend drivers for Manila must be substantially +complete, with unit tests, and passing 3rd party CI. Drivers do not have to +actually merge until feature freeze. + +Feature freeze +-------------- + +The client release follows a different timeline from the core component, so the +client changes must be merged prior to this deadline, as defined in the release +schedule. The client must contain unit and functional tests. + +.. important:: + + API changes must have the documentation updated in the same change as the + entire feature change. + +All features and new drivers must be merged by the feature freeze date. In case +you need extra time for the Manila core change, please reach out to the team's +PTL during an upstream weekly meeting, and we can discuss a possible feature +freeze exception, considering if the comments were resolved in a reasonable +amount of time and if the change is already in a good shape to be merged. + +Acceptance criteria +~~~~~~~~~~~~~~~~~~~ + +- Changes were proposed in time and module deadlines were respected +- The code introduced or changed is covered by unit tests +- New functional tests were proposed and reports are positive +- API changes are correct and not introducing backwards compatible changes +- API changes are documented + +Additional tips +~~~~~~~~~~~~~~~ + +- Remember to join the upstream meetings often +- Make sure to use the :ref:`commit message tags ` in your + changes. +- Submit the changes upstream as early as possible. +- Remember to run pep8, unit tests and coverage locally before you submit your + changes to gerrit. +- Ensure you keep a review discipline. The best way to have reviewers + looking at your change is to also provide reviews to other people's changes. diff --git a/doc/source/contributor/tempest_tests.rst b/doc/source/contributor/tempest_tests.rst index 8def619bd0..1291853499 100644 --- a/doc/source/contributor/tempest_tests.rst +++ b/doc/source/contributor/tempest_tests.rst @@ -1,3 +1,5 @@ +.. _installing-tempest-tests: + Tempest Tests ============= diff --git a/doc/source/contributor/unit_tests.rst b/doc/source/contributor/unit_tests.rst index 5da6bc1866..c10bcb0aaa 100644 --- a/doc/source/contributor/unit_tests.rst +++ b/doc/source/contributor/unit_tests.rst @@ -1,3 +1,5 @@ +.. _running-unit-tests: + Unit Tests ==========